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 |
visible | Whether or not the widget is shown | No | N/A | True | Yes |
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. |