Label widgets are for displaying text.
Label widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _labelnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | No | Yes | None | Yes |
height | Height of the widget | No | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
font | Truetype font file to use | Yes* | Yes | N/A | Yes |
fontcolor | Colour to use for the text | No | Yes | #FFFFFF | Yes |
fontsize | The size of the text (in points) | No | Yes | 16 | No |
textalign | Text alignment | No | Yes | left | Yes |
autosize | Autosize the widget to the text or not | No | Yes | false | Yes |
wordwrap | Automatically wrap the text to multiple lines | No | Yes | false | Yes |
*: Must be specified either in the template or in widget itself
Picture widgets are for displaying static images loaded from a file. Their width and height are set to the size of the image file.
Picture widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _picturenn | Read-only |
x | Horizontal screen position | Yes | N/A | N/A | Yes |
y | Vertical screen position | Yes | N/A | N/A | Yes |
image | The image file to display | Yes | N/A | None | Yes |
The following methods are supported by picture widgets:
Method | Description |
reloadimage() | Reloads the image file from disk. |
Buttons provide a way for a user to carry out an action.
Button widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _buttonnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | No* | Yes | None | Yes |
height | Height of the widget | No* | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
font | Truetype font file to use | No | Yes | N/A | Yes |
fontcolor | Colour to use for the text | No | Yes | #FFFFFF | Yes |
fontfocuscolor | Colour to use for the text when the button has the focus | No | Yes | fontcolor | Yes |
fontpressedcolor | Colour to use for the text when the button is pressed | No | Yes | fontfocuscolor | Yes |
fontdisabledcolor | Colour to use for the text when the button is disabled | No | Yes | fontcolor | Yes |
fontsize | The size of the text (in points) | No | Yes | 16 | No |
image | The image file to display in the normal state | No | Yes | None | Yes |
selectedimage | The image file to display when the button has the focus | No | Yes | None | Yes |
pressedimage | The image file to display when the button is pressed | No | Yes | None | Yes |
disabledimage | The image file to display when the button is disabled | No | Yes | None | Yes |
caption | The caption to display on the button | No | Yes | None | Yes |
captionx | The horizontal position of the caption from centre | No | Yes | 0 | Yes |
captiony | The vertical position of the caption from centre | No | Yes | 0 | Yes |
captiondropx | The amount the caption drops horizontally when the button is pressed | No | Yes | 2 | Yes |
captiondropy | The amount the caption drops vertically when the button is pressed | No | Yes | 2 | Yes |
enabled | Whether or not the button is enabled | No | No | true | Yes |
action | User action to bind to the button | No | No | None | No |
*: Must be specified if image attribute is not specified
The following methods are supported by button widgets:
Method | Description |
click() | Click the button (as if the user had clicked on it). |
setfocus() | Give focus to the button (if it is enabled). |
The following events are triggered by button widgets:
Event | Description |
OnClick | Occurs when the button is clicked. |
OnGotFocus | Occurs when the button receives focus. |
OnLostFocus | Occurs when the button loses focus. |
Togglebuttons provide a way for a user to set a boolean value (also known as checkboxes in other systems).
Togglebutton widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _togglebuttonnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | No | Yes | None | Yes |
height | Height of the widget | No | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
normalimage | The image file to display when the togglebutton is unchecked | No | Yes | None | Yes |
normalfocusimage | The image file to display when the togglebutton is unchecked and has the focus | No | Yes | None | Yes |
checkedimage | The image file to display when the togglebutton is checked | No | Yes | None | Yes |
checkedfocusimage | The image file to display when the togglebutton is checked and has the focus | No | Yes | None | Yes |
enabled | Whether or not the button is enabled (not currently used) | No | No | true | Yes |
checked | Whether or not the togglebutton is checked | No | No | false | Yes |
action | User action to bind to the togglebutton | No | No | None | No |
The following methods are supported by togglebutton widgets:
Method | Description |
setfocus() | Give focus to the togglebutton. |
The following events are triggered by togglebutton widgets:
Event | Description |
OnClick | Occurs when the button is clicked. |
OnGotFocus | Occurs when the button receives focus. |
OnLostFocus | Occurs when the button loses focus. |
Scrollbar widgets allow the user to slide a knob along a vertical or horizontal track in order to select a numeric value. eboxy scrollbars currently do not have buttons, so they are equivalent to "sliders" in some other systems. The combination of the width and height attributes determines if the scrollbar behaves horizontally or vertically (horizontally if the scrollbar is wider than it is high, vertically if it is higher than it is wide).
Scrollbar widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _scrollbarnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | Yes | Yes | None | Yes |
height | Height of the widget | Yes | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
background | The image file to display as the scrollbar background | No | Yes | None | Yes |
backgroundstyle | How to draw the image (tiled/normal) | No | Yes | normal | Yes |
knob | The image file to display as the scrollbar knob | No | Yes | None | Yes |
knobfocus | The image file to display as the scrollbar knob when the scrollbar has the focus. If specified, must be the same size as the normal knob image. | No | Yes | None | Yes |
reversed | Whether or not to reverse the normal display | No | Yes | false | Yes |
maximum | The maximum value of the scrollbar | No | Yes | 100 | Yes |
minimum | The minimum value of the scrollbar | No | Yes | 0 | Yes |
pagestep | The amount to step the value by when paging up/down | No | Yes | 10 | Yes |
value | The position of the scrollbar | Not in XML | N/A | 0 | Yes |
The following methods are supported by scrollbar widgets:
Method | Description |
setfocus() | Give focus to the scrollbar. |
The following events are triggered by scrollbar widgets:
Event | Description |
OnChange | Occurs when the value of the scrollbar is changed. |
OnGotFocus | Occurs when the scrollbar receives focus. |
OnLostFocus | Occurs when the scrollbar loses focus. |
Textfield widgets allow the user to enter text.
Textfield widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _textfieldnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | No | Yes | None | Yes |
height | Height of the widget | No | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
background | The image file to display as the textfield background | No | Yes | None | Yes |
backgroundfocus | The image file to display as the textfield background when the textfield has the focus | No | Yes | None | Yes |
backgroundstyle | How to draw the image (tiled/normal) | No | Yes | normal | Yes |
font | Truetype font file to use | Yes* | Yes | N/A | Yes |
fontcolor | Colour to use for the text | No | Yes | #FFFFFF | Yes |
fontsize | The size of the text (in points) | No | Yes | 16 | No |
borderx | Horizontal amount of border to leave around the outside of the textfield | No | Yes | 0 | Yes |
bordery | Vertical amount of border to leave around the outside of the textfield | No | Yes | 0 | Yes |
maxlength | The maximum length of the text | No | Yes | 255 | Read-only |
text | The text entered into the textfield | Not in XML | N/A | (empty) | Yes |
cursorpos | Cursor position (0 to length of text). If set to greater than the length of the text, the cursor will be placed at the end of the text. | Not in XML | N/A | N/A | Yes |
*: Must be specified either in the template or in widget itself
The following methods are supported by textfield widgets:
Method | Description |
setfocus() | Give focus to the textfield. |
The following events are triggered by textfield widgets:
Event | Description |
OnChange | Occurs when the text is changed. |
OnGotFocus | Occurs when the textfield receives focus. |
OnLostFocus | Occurs when the textfield loses focus. |
Listboxes are for providing the user with a choice from a list of text items.
Listbox widgets have the following attributes/properties:
Property | Description | Required | In template | Default | Script |
name | The name of the widget | No | N/A | _listboxnn | Read-only |
x | Horizontal screen position | Yes | No | N/A | Yes |
y | Vertical screen position | Yes | No | N/A | Yes |
width | Width of the widget | No | Yes | None | Yes |
height | Height of the widget | No | Yes | None | Yes |
template | Template to base the widget on | No | N/A | N/A | No |
font | Truetype font file to use for the list items | Yes* | Yes | N/A | Yes |
fontcolor | Colour to use for the text | No | Yes | #FFFFFF | Yes |
fontsize | The size of the text (in points) | No | Yes | 16 | No |
background | The image file to display behind the list | No | Yes | None | Yes |
backgroundfocus | The image file to display behind the list when the listbox has the focus | No | Yes | None | Yes |
backgroundstyle | How to draw the image (tiled/normal) | No | Yes | normal | Yes |
selitembackground | The image file to display behind the selected item | No | Yes | None | Yes |
selitembackgroundfocus | The image file to display behind the selected item when the list has the focus | No | Yes | None | Yes |
selitembackgroundstyle | How to draw the image (tiled/normal) | No | Yes | normal | Yes |
selitemfontcolor | The colour of the selected item's text | No | Yes | #FFFF00 | Yes |
scrollbar | Whether or not to show the scrollbar (on/off/auto) | No | Yes | auto | Yes |
scrollbarbackground | The image file to use for the scrollbar background | No | Yes | None | Yes |
scrollbarbackgroundstyle | How to draw the image (tiled/normal) | No | Yes | normal | Yes |
scrollbarknob | The image file to use as the knob (handle) of the scrollbar | No | Yes | None | Yes |
scrollbarwidth | The width of the scrollbar | No | Yes | 16 | Yes |
borderx | Horizontal amount of border to leave around the outside of the list | No | Yes | 0 | Yes |
bordery | Vertical amount of border to leave around the outside of the list | No | Yes | 0 | Yes |
itemborderx | Horizontal amount of border to leave around the text of each item | No | Yes | 0 | Yes |
itembordery | Vertical amount of border to leave around the text of each item | No | Yes | 0 | Yes |
itemheight | Height of each item in the list | No | Yes | (height of text) | Yes |
selectedindex | Index of selected item | Not in XML | N/A | N/A | Yes |
selectedtext | Text of selected item | Not in XML | N/A | N/A | Read-only |
count | Number of items in list | Not in XML | N/A | N/A | Read-only |
*: Must be specified either in the template or in widget itself
The following methods are supported by listbox widgets:
Method | Description |
setfocus() | Give focus to the listbox. |
additem(text) | Add an item to the list |
removeitem(index) | Remove an item from the list |
removelastitem() | Remove the last item from the list |
clear() | Remove all items from the list |
setitemtext(index, text) | Set the text of an item in the list |
The following events are triggered by listbox widgets:
Event | Description |
OnSelectionChange | Occurs when the selected item changes in the listbox. |
OnEmpty | Occurs when the listbox becomes empty. |
OnChoose | Occurs when the user chooses an item from the list (by pressing the enter key or double-clicking with an item selected). |
OnGotFocus | Occurs when the listbox receives focus. |
OnLostFocus | Occurs when the listbox loses focus. |
Timers, while not widgets strictly speaking, are defined in the same way as widgets. They allow you to define a recurring timed event. Timers may be associated with pages or the system object - the difference being that timers associated with pages are only available when that page is visible.
Timers have the following attributes/properties:
Property | Description | Required | Default | Script |
name | The name of the timer | No | _timernn | Read-only |
interval | Number of milliseconds between each event | Yes | N/A | Yes |
enabled | Automatically start the timer | No | false | Yes |
The following methods are supported by timers:
Method | Description |
start() | Start the timer |
stop() | Stop the timer |
The following events are triggered by timers:
Event | Description |
OnTimer | Occurs each time the specified interval has elapsed (when the timer is enabled/started). |
Pages are the "screens" or "forms" of eboxy. The current page is accessible to scripts
using the currentpage
special object.
Pages have the following attributes/properties:
Property | Description | Required | Default | Script |
name | The name of the page | Yes | N/A | Read-only |
background | The image file to display in the background | No | None | No |
The following events are triggered by pages:
Event | Description |
OnLoad | Occurs when the page is loaded |
OnShow | Occurs just after the page has been displayed |
OnUnload | Occurs just before the page is unloaded |
System is a special object, of which there is only one instance. It provides access to some global functions in eboxy. The System object has a section in the XML, but no attributes.
The System object has the following properties:
Property | Description | Script |
name | The name of the object (always "System") | Read-only |
screenwidth | Width of the eboxy screen | Read-only |
screenheight | Height of the eboxy screen | Read-only |
currentfile | Currently loaded XML skin file | Read-only |
version | eboxy version string (eg. 0.3.6) | Read-only |
The following methods are supported by the system object:
Method | Description |
focusnext() | Jumps to the next widget |
focusprevious() | Jumps to the previous widget |
performaction(actionname) | Perform the specified action. Accepts the same actions as for used for key bindings. |
printpluginlist() | Prints out a list of loaded plugins to the console |
quit() | Quits eboxy |
selectfocused() | Presses the focused button/chooses the selected item in a listbox |
The following events are triggered by the system object:
Event | Description |
OnLoad | Occurs when the file is loaded (just before the first page is shown) |
OnShow | Occurs just after the first page has been displayed, and after eboxy is unhidden |
OnHide | Occurs just before eboxy is hidden (with the exechide script command) |
OnUnload | Occurs just before eboxy is unloaded |