wxRuby Documentation Home


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). This is controlled by changing the style passed to the constructor.

List box elements are numbered from zero. Their number is limited in some platforms – for example, around 2000 on GTK.

A listbox callback gets an event EVT_COMMAND_LISTBOX_SELECT for single clicks, and EVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.

Derived from






Window styles

LB_SINGLE Single-selection list.
LB_MULTIPLE Multiple-selection list: the user can toggle multipleitems on and off.
LB_EXTENDED Extended-selection list: the user canselect multiple items using the SHIFT key and the mouse or special key combinations.
LB_HSCROLL Create horizontal scrollbar if contents are too wide (Windows only).
LB_ALWAYS_SB Always show a vertical scrollbar.
LB_NEEDED_SB Only create a vertical scrollbar if needed.
LB_SORT The listbox contents are sorted in alphabetical order.

Note that LB_SINGLE, LB_MULTIPLE and LB_EXTENDED styles are mutually exclusive and you can specify at most one of them (single selection is the default).

See also window styles overview.

Event handling

evt_listbox(id) { | event | ... } Process a EVT_COMMAND_LISTBOX_SELECTED event,when an item on the list is selected.
evt_listbox_dclick(id) { | event | ... } Process a EVT_COMMAND_LISTBOX_DOUBLECLICKED event,when the listbox is double-clicked.

See also

Choice, ComboBox, ListCtrl, CommandEvent



ListBox.new(Window parent, Integer id, 
            Point pos = DEFAULT_POSITION, 
            Size size = DEFAULT_SIZE, 
            Array choices = nil,  
            Integer style = 0, 
            Validator validator = DEFAULT_VALIDATOR, 
            String name = "listBox")

Constructor, creating and showing a list box.


See also

ListBox#create, Validator


Boolean create(Window parent, Integer id, 
               Point pos = DEFAULT_POSITION, 
               Size size = DEFAULT_SIZE,
               String choices[] = nil, 
               Integer style = 0, 
               Validator validator = DEFAULT_VALIDATOR, 
               String name = "listBox")

Creates the listbox for two-step construction. See ListBox.new for further details.


deselect(Integer n)

Deselects an item in the list box.



This applies to multiple selection listboxes only.


Array get_selections()

Returns an array of integers corresponding to the selected items in the listbox. Use this with a multiple selection listbox.

See also

ControlWithItems#get_selection, ControlWithItems#get_string_selection, ControlWithItems#set_selection


insert_items(Array items, Integer pos)

Insert a number of strings before the specified position.



Boolean is_selected(Integer n)

Determines whether an item is selected.


Return value

true if the given item is selected, false otherwise.


set(Array choices, Array client_data = nil)

Clears the list box and adds the given strings to it.



set_first_item(Integer n)
set_first_item(String string)

Set the specified item to be the first visible item. Windows only.


[This page automatically generated from the Textile source at Wed Sep 09 02:21:15 +0100 2009]