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