Next Previous Contents

4. Object Reference

4.1 Label

Label widgets are for displaying text.

Properties

Label widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_labelnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetNoYesNoneYes
heightHeight of the widgetNoYesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
fontTruetype font file to useYes*YesN/AYes
fontcolorColour to use for the textNoYes#FFFFFFYes
fontsizeThe size of the text (in points)NoYes16No
textalignText alignmentNoYesleftYes
autosizeAutosize the widget to the text or notNoYesfalseYes
wordwrapAutomatically wrap the text to multiple linesNoYesfalseYes

*: Must be specified either in the template or in widget itself

4.2 Picture

Picture widgets are for displaying static images loaded from a file. Their width and height are set to the size of the image file.

Properties

Picture widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_picturennRead-only
xHorizontal screen positionYesN/AN/AYes
yVertical screen positionYesN/AN/AYes
imageThe image file to displayYesN/ANoneYes

Methods

The following methods are supported by picture widgets:

MethodDescription
reloadimage()Reloads the image file from disk.

4.3 Button

Buttons provide a way for a user to carry out an action.

Properties

Button widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_buttonnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetNo*YesNoneYes
heightHeight of the widgetNo*YesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
fontTruetype font file to useNoYesN/AYes
fontcolorColour to use for the textNoYes#FFFFFFYes
fontfocuscolorColour to use for the text when the button has the focusNoYesfontcolorYes
fontpressedcolorColour to use for the text when the button is pressedNoYesfontfocuscolorYes
fontdisabledcolorColour to use for the text when the button is disabledNoYesfontcolorYes
fontsizeThe size of the text (in points)NoYes16No
imageThe image file to display in the normal stateNoYesNoneYes
selectedimageThe image file to display when the button has the focusNoYesNoneYes
pressedimageThe image file to display when the button is pressedNoYesNoneYes
disabledimageThe image file to display when the button is disabledNoYesNoneYes
captionThe caption to display on the buttonNoYesNoneYes
captionxThe horizontal position of the caption from centreNoYes0Yes
captionyThe vertical position of the caption from centreNoYes0Yes
captiondropxThe amount the caption drops horizontally when the button is pressedNoYes2Yes
captiondropyThe amount the caption drops vertically when the button is pressedNoYes2Yes
enabledWhether or not the button is enabledNoNotrueYes
actionUser action to bind to the buttonNoNoNoneNo

*: Must be specified if image attribute is not specified

Methods

The following methods are supported by button widgets:

MethodDescription
click()Click the button (as if the user had clicked on it).
setfocus()Give focus to the button (if it is enabled).

Events

The following events are triggered by button widgets:

EventDescription
OnClickOccurs when the button is clicked.
OnGotFocusOccurs when the button receives focus.
OnLostFocusOccurs when the button loses focus.

4.4 ToggleButton

Togglebuttons provide a way for a user to set a boolean value (also known as checkboxes in other systems).

Properties

Togglebutton widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_togglebuttonnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetNoYesNoneYes
heightHeight of the widgetNoYesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
normalimageThe image file to display when the togglebutton is uncheckedNoYesNoneYes
normalfocusimageThe image file to display when the togglebutton is unchecked and has the focusNoYesNoneYes
checkedimageThe image file to display when the togglebutton is checkedNoYesNoneYes
checkedfocusimageThe image file to display when the togglebutton is checked and has the focusNoYesNoneYes
enabledWhether or not the button is enabled (not currently used)NoNotrueYes
checkedWhether or not the togglebutton is checkedNoNofalseYes
actionUser action to bind to the togglebuttonNoNoNoneNo

Methods

The following methods are supported by togglebutton widgets:

MethodDescription
setfocus()Give focus to the togglebutton.

Events

The following events are triggered by togglebutton widgets:

EventDescription
OnClickOccurs when the button is clicked.
OnGotFocusOccurs when the button receives focus.
OnLostFocusOccurs when the button loses focus.

4.5 ScrollBar

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).

Properties

Scrollbar widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_scrollbarnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetYesYesNoneYes
heightHeight of the widgetYesYesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
backgroundThe image file to display as the scrollbar backgroundNoYesNoneYes
backgroundstyleHow to draw the image (tiled/normal)NoYesnormalYes
knobThe image file to display as the scrollbar knobNoYesNoneYes
knobfocusThe 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.NoYesNoneYes
reversedWhether or not to reverse the normal displayNoYesfalseYes
maximumThe maximum value of the scrollbarNoYes100Yes
minimumThe minimum value of the scrollbarNoYes0Yes
pagestepThe amount to step the value by when paging up/downNoYes10Yes
valueThe position of the scrollbarNot in XMLN/A0Yes

Methods

The following methods are supported by scrollbar widgets:

MethodDescription
setfocus()Give focus to the scrollbar.

Events

The following events are triggered by scrollbar widgets:

EventDescription
OnChangeOccurs when the value of the scrollbar is changed.
OnGotFocusOccurs when the scrollbar receives focus.
OnLostFocusOccurs when the scrollbar loses focus.

4.6 TextField

Textfield widgets allow the user to enter text.

Properties

Textfield widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_textfieldnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetNoYesNoneYes
heightHeight of the widgetNoYesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
backgroundThe image file to display as the textfield backgroundNoYesNoneYes
backgroundfocusThe image file to display as the textfield background when the textfield has the focusNoYesNoneYes
backgroundstyleHow to draw the image (tiled/normal)NoYesnormalYes
fontTruetype font file to useYes*YesN/AYes
fontcolorColour to use for the textNoYes#FFFFFFYes
fontsizeThe size of the text (in points)NoYes16No
borderxHorizontal amount of border to leave around the outside of the textfieldNoYes0Yes
borderyVertical amount of border to leave around the outside of the textfieldNoYes0Yes
maxlengthThe maximum length of the textNoYes255Read-only
textThe text entered into the textfieldNot in XMLN/A(empty)Yes
cursorposCursor 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 XMLN/AN/AYes

*: Must be specified either in the template or in widget itself

Methods

The following methods are supported by textfield widgets:

MethodDescription
setfocus()Give focus to the textfield.

Events

The following events are triggered by textfield widgets:

EventDescription
OnChangeOccurs when the text is changed.
OnGotFocusOccurs when the textfield receives focus.
OnLostFocusOccurs when the textfield loses focus.

4.7 ListBox

Listboxes are for providing the user with a choice from a list of text items.

Properties

Listbox widgets have the following attributes/properties:

PropertyDescriptionRequiredIn templateDefaultScript
nameThe name of the widgetNoN/A_listboxnnRead-only
xHorizontal screen positionYesNoN/AYes
yVertical screen positionYesNoN/AYes
widthWidth of the widgetNoYesNoneYes
heightHeight of the widgetNoYesNoneYes
templateTemplate to base the widget onNoN/AN/ANo
fontTruetype font file to use for the list itemsYes*YesN/AYes
fontcolorColour to use for the textNoYes#FFFFFFYes
fontsizeThe size of the text (in points)NoYes16No
backgroundThe image file to display behind the listNoYesNoneYes
backgroundfocusThe image file to display behind the list when the listbox has the focusNoYesNoneYes
backgroundstyleHow to draw the image (tiled/normal)NoYesnormalYes
selitembackgroundThe image file to display behind the selected itemNoYesNoneYes
selitembackgroundfocusThe image file to display behind the selected item when the list has the focusNoYesNoneYes
selitembackgroundstyleHow to draw the image (tiled/normal)NoYesnormalYes
selitemfontcolorThe colour of the selected item's textNoYes#FFFF00Yes
scrollbarWhether or not to show the scrollbar (on/off/auto)NoYesautoYes
scrollbarbackgroundThe image file to use for the scrollbar backgroundNoYesNoneYes
scrollbarbackgroundstyleHow to draw the image (tiled/normal)NoYesnormalYes
scrollbarknobThe image file to use as the knob (handle) of the scrollbarNoYesNoneYes
scrollbarwidthThe width of the scrollbarNoYes16Yes
borderxHorizontal amount of border to leave around the outside of the listNoYes0Yes
borderyVertical amount of border to leave around the outside of the listNoYes0Yes
itemborderxHorizontal amount of border to leave around the text of each itemNoYes0Yes
itemborderyVertical amount of border to leave around the text of each itemNoYes0Yes
itemheightHeight of each item in the listNoYes(height of text)Yes
selectedindexIndex of selected itemNot in XMLN/AN/AYes
selectedtextText of selected itemNot in XMLN/AN/ARead-only
countNumber of items in listNot in XMLN/AN/ARead-only

*: Must be specified either in the template or in widget itself

Methods

The following methods are supported by listbox widgets:

MethodDescription
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

Events

The following events are triggered by listbox widgets:

EventDescription
OnSelectionChangeOccurs when the selected item changes in the listbox.
OnEmptyOccurs when the listbox becomes empty.
OnChooseOccurs when the user chooses an item from the list (by pressing the enter key or double-clicking with an item selected).
OnGotFocusOccurs when the listbox receives focus.
OnLostFocusOccurs when the listbox loses focus.

4.8 Timer

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.

Properties

Timers have the following attributes/properties:

PropertyDescriptionRequiredDefaultScript
nameThe name of the timerNo_timernnRead-only
intervalNumber of milliseconds between each eventYesN/AYes
enabledAutomatically start the timerNofalseYes

Methods

The following methods are supported by timers:

MethodDescription
start()Start the timer
stop()Stop the timer

Events

The following events are triggered by timers:

EventDescription
OnTimerOccurs each time the specified interval has elapsed (when the timer is enabled/started).

4.9 Page

Pages are the "screens" or "forms" of eboxy. The current page is accessible to scripts using the currentpage special object.

Properties

Pages have the following attributes/properties:

PropertyDescriptionRequiredDefaultScript
nameThe name of the pageYesN/ARead-only
backgroundThe image file to display in the backgroundNoNoneNo

Events

The following events are triggered by pages:

EventDescription
OnLoadOccurs when the page is loaded
OnShowOccurs just after the page has been displayed
OnUnloadOccurs just before the page is unloaded

4.10 System

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.

Properties

The System object has the following properties:

PropertyDescriptionScript
nameThe name of the object (always "System")Read-only
screenwidthWidth of the eboxy screenRead-only
screenheightHeight of the eboxy screenRead-only
currentfileCurrently loaded XML skin fileRead-only
versioneboxy version string (eg. 0.3.6)Read-only

Methods

The following methods are supported by the system object:

MethodDescription
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

Events

The following events are triggered by the system object:

EventDescription
OnLoadOccurs when the file is loaded (just before the first page is shown)
OnShowOccurs just after the first page has been displayed, and after eboxy is unhidden
OnHideOccurs just before eboxy is hidden (with the exechide script command)
OnUnloadOccurs just before eboxy is unloaded


Next Previous Contents