Contents Up Previous Next

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 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. No effect for GTK.

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 doubleclicked.

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::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::wxListBox

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.


wxListBox::~wxListBox

void ~wxListBox()

Destructor, destroying the list box.


wxListBox::Append

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


wxListBox::Clear

void Clear()

Clears all strings from 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")

Creates the listbox for two-step construction. See wxListBox::wxListBox for further details.


wxListBox::Delete

void Delete(int n)

Deletes an item from the listbox.

Parameters

n


wxListBox::Deselect

void Deselect(int n)

Deselects an item in the list box.

Parameters

n

Remarks

This applies to multiple selection listboxes only.


wxListBox::FindString

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.


wxListBox::GetClientData

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.


wxListBox::GetSelection

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


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.


wxListBox::GetString

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.


wxListBox::GetStringSelection

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


wxListBox::InsertItems

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.


wxListBox::Number

int Number() const

Returns the number of items in the listbox.


wxListBox::Selected

bool Selected(int n) const

Determines whether an item is selected.

Parameters

n

Return value

TRUE if the given item is selected, FALSE otherwise.


wxListBox::Set

void Set(int n, const wxString* choices)

Clears the list box and adds the given strings. Not implemented for GTK.

Parameters

n

choices

Remarks

Deallocate the array from the calling program after this function has been called.


wxListBox::SetClientData

void SetClientData(int n, void* data)

Associates the given client data pointer with the given item.

Parameters

n

data


wxListBox::SetFirstItem

void SetFirstItem(int n)

void SetFirstItem(const wxString& string)

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

Parameters

n

string


wxListBox::SetSelection

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


wxListBox::SetString

void SetString(int n, const wxString& string)

Sets the string value of an item.

Parameters

n

string


wxListBox::SetStringSelection

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