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
visibleWhether or not the widget is shownNoN/ATrueYes
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.