wxListBox

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).
List box elements are numbered from zero. Their number may be limited under some platforms.
A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.

Derived from

wxControlWithItems
wxControl
wxWindow
wxEvtHandler
wxObject

Include files

<wx/listbox.h>

Window styles

wxLB_SINGLE
Single-selection list.
wxLB_MULTIPLE
Multiple-selection list: the user can toggle multiple items on and off.
wxLB_EXTENDED
Extended-selection list: the user can select multiple items using the SHIFT key and the mouse or special key combinations.
wxLB_HSCROLL
Create horizontal scrollbar if contents are too wide (Windows only).
wxLB_ALWAYS_SB
Always show a vertical scrollbar.
wxLB_NEEDED_SB
Only create a vertical scrollbar if needed.
wxLB_SORT
The listbox contents are sorted in alphabetical order.
Note that wxLB_SINGLE, wxLB_MULTIPLE and wxLB_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, func)
Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the list is selected or the selection changes.
EVT_LISTBOX_DCLICK(id, func)
Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox is double-clicked.

See also

wxChoice, wxComboBox, wxListCtrl, wxCommandEvent

Members


wxListBox::wxListBox

wxListBox()
Default constructor.
wxListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox")
wxListBox(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, const wxArrayString& choices, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& 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.
n
Number of strings with which to initialise the control.
choices
An array of strings with which to initialise the control.
style
Window style. See wxListBox.
validator
Window validator.
name
Window name.

See also

wxListBox::Create, wxValidator
wxPython note: The wxListBox constructor in wxPython reduces the n and choices arguments are to a single argument, which is a list of strings.
wxPerl note: In wxPerl there is just an array reference in place of n and choices.

wxListBox::~wxListBox

void ~wxListBox()
Destructor, destroying the list box.

wxListBox::Create

bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n, const wxString choices[] = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox")
bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos, const wxSize& size, const wxArrayString& choices, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "listBox")
Creates the listbox for two-step construction. See wxListBox::wxListBox for further details.

wxListBox::Deselect

void Deselect(int n)
Deselects an item in the list box.

Parameters

n
The zero-based item to deselect.

Remarks

This applies to multiple selection listboxes only.

wxListBox::GetSelections

int GetSelections(wxArrayInt& selections) const
Fill an array of ints with the positions of the currently selected items.

Parameters

selections
A reference to an wxArrayInt instance that is used to store the result of the query.

Return value

The number of selections.

Remarks

Use this with a multiple selection listbox.

See also

wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, wxControlWithItems::SetSelection
wxPython note: The wxPython version of this method takes no parameters and returns a tuple of the selected items.
wxPerl note: In wxPerl this method takes no parameters and return the selected items as a list.

wxListBox::InsertItems

void InsertItems(int nItems, const wxString *items, unsigned int pos)
void InsertItems(const wxArrayString& nItems, unsigned int pos)
Insert the given number of strings before the specified position.

Parameters

nItems
Number of items in the array items
items
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
wxPython note: The first two parameters are collapsed into a single parameter for wxPython, which is a list of strings.
wxPerl note: In wxPerl there is just an array reference in place of nItems and items.

wxListBox::HitTest

int HitTest(const wxPoint&amp; point) const
Returns the item located at point, or wxNOT_FOUND if there is no item located at point.
2.7.0. It is currently implemented for wxMSW, wxMac and wxGTK2 ports.

Parameters

point
Point of item (in client coordinates) to obtain

Return value

Item located at point, or wxNOT_FOUND if unimplemented or the item does not exist.

wxListBox::IsSelected

bool IsSelected(int n) const
Determines whether an item is selected.

Parameters

n
The zero-based item index.

Return value

true if the given item is selected, false otherwise.

wxListBox::Set

void Set(int n, const wxString* choices, void **clientData = NULL)
void Set(const wxArrayString& choices, void **clientData = NULL)
Clears the list box and adds the given strings to it.

Parameters

n
The number of strings to set.
choices
An array of strings to set.
clientData
Options array of client data pointers

Remarks

You may free the array from the calling program after this function has been called.

wxListBox::SetFirstItem

void SetFirstItem(int n)
void SetFirstItem(const wxString& string)
Set the specified item to be the first visible item.

Parameters

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