4.2  Common Tag Attributes and Handlers

The display tags, i.e. the tags representing visible display elements, support a set of common attributes and action handlers.

4.2.1  Attributes

Name Type Default Value Description
anchor direction nw Positioning anchor of the element. It determines which point is used for positioning using the x, y properties.
cursor string [New in 0.35] The name of the mouse cursor which will be displayed when the mouse pointer enters the element. Set this property to an empty string in order to revert that setting.
index-path integer list Read-only property for retrieving the index of the element with in an array. This is a list because arrays can be nested, thus requiring multiple indexes to address an element.
menu object [New in 0.35] The menu to be displayed. Whenever you assign a menu (a list of MenuItem objects) to this property, it will immediately popup.
relative-to string list

Usage: relative-to="id, dir"

Places the element relative to the element with ID id.
x unit 0 X coordinate of the element.
y unit 0 Y coordinate of the element.
width unit Width of the element.
height unit Height coordinate of the element.
id string Unique ID of the element. The ID is used for referencing the element.
visible boolean true Visibility state of the element. Either true (visible) or false (hidden). Hidden elements don't consume any space and can thus not detect mouse events.

4.2.2  Action Handlers

Name Event Members Description
on-click

button: integer

x: unit

y: unit

Handler for mouse click events. A click consists of pressing and releasing a mouse button without moving the pointer significantly.
on-doubleclick

button: integer

x: unit

y: unit

Like on-click, but only reacts on double clicks.
on-enter Handler for enter events that are triggered every time the mouse pointer enters the element.
on-file-drop

files: URI list

Handler for dropping files after drag-and-drop operations. This only accepts files to be dropped.
on-key-press

key: string

Handler for key presses.
on-key-release

key: string

Handler for key releases.
on-leave Like on-enter, but for leave events.
on-link-drop

links: URI list

Handler for dropping browser links after drag-and-drop operations.
on-menu script Handler for the popup menu, reacting when the user opens the popup-menu.
on-motion

x: unit

y: unit

Handler for mouse motion events.
on-press

button: integer

x: unit

y: unit

Like on-click, but reacts on pressing a button.
on-release

button: integer

x: unit

y: unit

Like on-click, but reacts on releasing a button.
on-scroll

direction: integer

Handler for mouse wheel events. The direction property is 0 for a scroll up event and 1 for a scroll down.

4.2.3  Examples

Sample from SideCandy displays:
<group id="slider"
       on-click="if (sc_behavior == 'click'): slide(self, SC_IN, SC_OUT)"
       on-doubleclick="if (sc_behavior == 'double'): slide(self, SC_IN, SC_OUT)"
       on-enter="if (sc_behavior == 'enter'): slide(self, SC_IN, SC_OUT)"
       on-leave="if (sc_behavior == 'enter'): slide(self, SC_IN, SC_OUT)"
       on-scroll="scroll_me(self.event.direction)">