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 is limited in some platforms (e.g. ca. 2000 on GTK).
A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECT for single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.
Derived from
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. |
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::~wxListBox
wxListBox::Append
wxListBox::Clear
wxListBox::Create
wxListBox::Delete
wxListBox::Deselect
wxListBox::FindString
wxListBox::GetClientData
wxListBox::GetCount
wxListBox::GetSelection
wxListBox::GetSelections
wxListBox::GetString
wxListBox::GetStringSelection
wxListBox::InsertItems
wxListBox::Number
wxListBox::Selected
wxListBox::Set
wxListBox::SetClientData
wxListBox::SetFirstItem
wxListBox::SetSelection
wxListBox::SetString
wxListBox::SetStringSelection
wxListBox()
Default constructor.
wxListBox(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")
Constructor, creating and showing a list box.
Parameters
parent
id
pos
size
n
choices
style
validator
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.
void ~wxListBox()
Destructor, destroying the list box.
void Append(const wxString& item)
Adds the item to the end of the list box.
void Append(const wxString& item, void* clientData)
Adds the item to the end of the list box, associating the given data with the item.
Parameters
item
clientData
void Clear()
Clears all strings from the list box.
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")
Creates the listbox for two-step construction. See wxListBox::wxListBox for further details.
void Delete(int n)
Deletes an item from the listbox.
Parameters
n
void Deselect(int n)
Deselects an item in the list box.
Parameters
n
Remarks
This applies to multiple selection listboxes only.
int FindString(const wxString& string)
Finds an item matching the given string.
Parameters
string
Return value
The zero-based position of the item, or -1 if the string was not found.
void* GetClientData(int n) const
Returns a pointer to the client data associated with the given item (if any).
Parameters
n
Return value
A pointer to the client data, or NULL if not present.
int GetCount() const
Returns the number of items in the listbox.
int GetSelection() const
Gets the position of the selected item.
Return value
The position of the current selection.
Remarks
Applicable to single selection list boxes only.
See also
wxListBox::SetSelection, wxListBox::GetStringSelection, wxListBox::GetSelections
int GetSelections(wxArrayInt& selections) const
Fill an array of ints with the positions of the currently selected items.
Parameters
selections
Return value
The number of selections.
Remarks
Use this with a multiple selection listbox.
See also
wxListBox::GetSelection, wxListBox::GetStringSelection, wxListBox::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.
wxString GetString(int n) const
Returns the string at the given position.
Parameters
n
Return value
The string, or an empty string if the position was invalid.
wxString GetStringSelection() const
Gets the selected string - for single selection list boxes only. This must be copied by the calling program if long term use is to be made of it.
See also
wxListBox::GetSelection, wxListBox::GetSelections, wxListBox::SetSelection
void InsertItems(int nItems, const wxString *items, int pos)
Insert the given number of strings before the specified position.
Parameters
nItems
items
pos
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.
int Number() const
Obsolescence note: This method is obsolete and was replaced with GetCount, please use the new method in the new code. This method is only available if wxWindows was compiled with WXWIN_COMPATIBILITY_2_2 defined and will disappear completely in future versions.
Returns the number of items in the listbox.
bool Selected(int n) const
Determines whether an item is selected.
Parameters
n
Return value
TRUE if the given item is selected, FALSE otherwise.
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
choices
clientData
Remarks
You may free the array from the calling program after this function has been called.
void SetClientData(int n, void* data)
Associates the given client data pointer with the given item.
Parameters
n
data
void SetFirstItem(int n)
void SetFirstItem(const wxString& string)
Set the specified item to be the first visible item. Windows only.
Parameters
n
string
void SetSelection(int n, const bool select = TRUE)
Selects or deselects the given item. This does not cause a wxEVT_COMMAND_LISTBOX_SELECT event to get emitted.
Parameters
n
select
void SetString(int n, const wxString& string)
Sets the string value of an item.
Parameters
n
string
void SetStringSelection(const wxString& string, const bool select = TRUE)
Sets the current selection. This does not cause a wxEVT_COMMAND_LISTBOX_SELECT event to get emitted.
Parameters
string
select