wxRuby Documentation Home

# Wx::ListBox

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

ControlWithItems

Control

Window

EvtHandler

Object

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

## Methods

- ListBox.new
- ListBox#create
- ListBox#deselect
- ListBox#get_selections
- ListBox#insert_items
- ListBox#is_selected
- ListBox#set
- ListBox#set_first_item

### ListBox.new

ListBox.new(%(arg-type)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.

#### Parameters

- parent Parent window. Must not be NULL.
- id Window identifier. A value of -1 indicates a default value.
- pos Window position.
- size Window size. If the default size (-1, -1) is specified then the window is sized
  appropriately.
- choices An array of strings with which to initialise the control.
- style Window style. See ListBox.
- validator Window validator.
- name Window name.

#### See also

ListBox#create, Validator

### ListBox#create

Boolean create(%(arg-type)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.

### ListBox#deselect

deselect(%(arg-type)Integer% n)

Deselects an item in the list box.

#### Parameters

- n The zero-based item to deselect.

#### Remarks

This applies to multiple selection listboxes only.

### ListBox#get_selections

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

### ListBox#insert_items

insert_items(%(arg-type)Array% items, Integer pos)

Insert a number of strings before the specified position.

#### Parameters

- items Array of strings for the labels of items to be inserted
- pos Position before which to insert the items: for example, if pos is 0 the items
  will be inserted in the beginning of the listbox

### ListBox#is_selected

Boolean is_selected(%(arg-type)Integer% n)

Determines whether an item is selected.

#### Parameters

- n The zero-based item index.

#### Return value

true if the given item is selected, false otherwise.

### ListBox#set

set(%(arg-type)Array% choices, Array client_data = `nil`)

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

#### Parameters

- choices An array of strings to set.
- client_data Optional array of client data pointers – not currently supported

### ListBox#set_first_item

set_first_item(%(arg-type)Integer% n) set_first_item(%(arg-type)String% string)

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

#### Parameters

- n The zero-based item index.
- string The string that should be visible.

[This page automatically generated from the Textile source at 2023-06-09 00:45:35 +0000]