Listbox¶
Note
Listbox is derived from Control class.
A listbox is used to select one or more of a list of strings.
The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video. A listbox can be single selection (if an item is selected, the previous selection is removed) or multiple selection (clicking an item toggles the item on or off independently of other selections).
Listbox elements are numbered from zero and while the maximal number of elements is unlimited, it is usually better to use a virtual control, not requiring to add all the items to it at once, such as wxDataViewCtrl or wxListCtrl with wxLC_VIRTUAL style, once more than a few hundreds items need to be displayed because this control is not optimized, neither from performance nor from user interface point of view, for large number of items.
Notice that currently TAB characters in list box items text are not handled consistently under all platforms, so they should be replaced by spaces to display strings properly everywhere. The listbox doesn’t support any other control characters at all.
Constructor¶
Listbox class has a complex constructor:
object Listbox:new {
object Parent, string Name,
table Choices = { "item 1", "item 2", "item3" }
}
Events¶
The following events are emitted by this class:
| Event name | Description |
|---|---|
| Widget.onEnter | When the mouse moves onto this widget. |
| Widget.onLeave | When the mouse moves out to this widget. |
| Listbox.onSelected_ | When an item on the list is selected or the selection changes. |
Inherited Methods¶
These methods are inherited from its super classes:
| Class Method | Description |
|---|---|
| Object:getName | Returns object’s name. |
| Object:setName | Sets the object name. |
| Widget:getParent | Returns object’s parent. |
| Widget:setParent | Sets the object parent. |
| Widget:getPosX | Returns object’s position related to X. |
| Widget:setPosX | Sets the object position related to X. |
| Widget:getPosY | Returns object’s position related to Y. |
| Widget:setPosY | Sets the object position related to Y. |
| Widget:getWidth | Returns object’s width. |
| Widget:setWidth | Sets the object width. |
| Widget:getHeight | Returns object’s height. |
| Widget:setHeight | Sets the object height. |
| Widget:getwxObj | Returns the wxWidgets object. |
Class Methods¶
These methods are defined by this class.
Listbox:initListboxEvents¶
Initialize listbox control related events. See Widget:initWidgetEvents for more info.
Returns: true or false, string_ error_message
| bool | Listbox:initListboxEvents ( table tEvents ) |
Listbox:insertItems¶
Insert the given number of strings before the specified position.
| nil | Listbox:insertItems ( table tItems, number nPosition ) |
Listbox:deselect¶
Deselects an item in the list box.
Returns: This applies to multiple selection listboxes onlys
| nil | Listbox:deselect( number nItem ) |
Listbox:setChoices¶
Replaces the current control contents with the given items.
Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.
| nil | Listbox:setChoices( table tChoices ) |
Listbox:setSelection¶
Sets the selection to the given item nSelect or removes the selection entirely if
nSelect == wx.wxNOT_FOUNDNote that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections.
| nil | Listbox:setSelection( number nSelect ) |
Listbox:getSelection¶
Returns the index of the selected item or
wx.wxNOT_FOUNDif no item is selected.Returns: The position of the current selection
This method can be used with single selection list boxes only, you should use
Listbox:getSelections()for the listboxes withLB_MULTIPLEstyle.
| number | Listbox:getSelection() |
Listbox:isSelected¶
Determines whether an item is selected.
Returns: true if the given item is selected, false otherwise
| bool | Listbox:isSelected( number nItem ) |