# wxListBox Class Reference
[Controls]

`#include <wx/listbox.h>`

Inheritance diagram for wxListBox:
[legend]

## Detailed Description

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_DOUBLECLICKED` for double clicks.

## Styles

This class supports the following styles:

- wxLB_SINGLE:
  Single-selection list.
- wxLB_MULTIPLE:
  Multiple-selection list: the user can toggle multiple items on and off. This is the same as wxLB_EXTENDED in wxGTK2 port.
- wxLB_EXTENDED:
  Extended-selection list: the user can extend the selection by using `SHIFT` or `CTRL` keys together with the cursor movement keys or the mouse.
- 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_NO_SB:
  Don't create vertical scrollbar (wxMSW only).
- 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.

## Events emitted by this class

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCommandEvent& event)
Event macros for events emitted by this class:

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

##

Library: wxCore

Category: Controls
Appearance:

wxMSW appearance | wxGTK appearance | wxMac appearance

See also:
  wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent

## Public Member Functions
| 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=wxListBoxNameStr)
| Constructor, creating and showing a list box.
| wxListBox (wxWindow *parent, wxWindowID id, const wxPoint &pos, const wxSize &size, const wxArrayString &choices, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxListBoxNameStr)
| Constructor, creating and showing a list box.
virtual | ~wxListBox ()
| Destructor, destroying the list box.
void | Deselect (int n)
| Deselects an item in the list box.
virtual int | GetSelections (wxArrayInt &selections) const
| Fill an array of ints with the positions of the currently selected items.
int | HitTest (const wxPoint &point) const
| Returns the item located at point, or `wxNOT_FOUND` if there is no item located at point.
int | HitTest (int x, int y) const
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | InsertItems (unsigned int nItems, const wxString *items, unsigned int pos)
| Insert the given number of strings before the specified position.
void | InsertItems (const wxArrayString &items, unsigned int pos)
| Insert the given number of strings before the specified position.
virtual bool | IsSelected (int n) const
| Determines whether an item is selected.
void | Set (unsigned int n, const wxString *choices, void *clientData)
| Clears the list box and adds the given strings to it.
void | Set (const wxArrayString &choices, void *clientData)
| Clears the list box and adds the given strings to it.
void | SetFirstItem (int n)
| Set the specified item to be the first visible item.
void | SetFirstItem (const wxString &string)
| Set the specified item to be the first visible item.
bool | Create (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=wxListBoxNameStr)
| Creates the listbox for two-step construction.
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=wxListBoxNameStr)
| Creates the listbox for two-step construction.

List of all members.

## Constructor & Destructor Documentation

wxListBox::wxListBox | ( |  | ) |

Default constructor.

wxListBox::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 = `wxListBoxNameStr` |
| ) |  |  |

Constructor, creating and showing a list box.

Parameters:

  | parent | The parent window.
  | id | The ID of this control. A value of `wxID_ANY` indicates a default value.
  | pos | The initial position. If wxDefaultPosition is specified then a default position is chosen.
  | size | The initial size. If wxDefaultSize is specified then the window is sized appropriately.
  | n | Number of strings with which to initialise the control.
  | choices | The strings to use to initialize the control.
  | style | Window style. See wxListBox.
  | validator | The validator for this control.
  | name | The name of this class.

wxPerl Note: Not supported by wxPerl.

wxListBox::wxListBox | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxPoint & | pos,
|  | const wxSize & | size,
|  | const wxArrayString & | choices,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxListBoxNameStr` |
| ) |  |  |

Constructor, creating and showing a list box.

See the other wxListBox() constructor; the only difference is that this overload takes a wxArrayString instead of a pointer to an array of wxString.

wxPerl Note: Use an array reference for the choices parameter.

virtual wxListBox::~wxListBox | ( |  | ) | `[virtual]`

Destructor, destroying the list box.

## Member Function Documentation

bool wxListBox::Create | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxPoint & | pos,
|  | const wxSize & | size,
|  | const wxArrayString & | choices,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxListBoxNameStr` |
| ) |  |  |

Creates the listbox for two-step construction.

See wxListBox() for further details.

bool wxListBox::Create | ( | 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 = `wxListBoxNameStr` |
| ) |  |  |

Creates the listbox for two-step construction.

See wxListBox() for further details.

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

virtual int wxListBox::GetSelections | ( | wxArrayInt & | selections | ) | const`[virtual]`

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.

Returns:
  The number of selections.

Remarks:
  Use this with a multiple selection listbox.

wxPerl Note: In wxPerl this method takes no parameters and return the selected items as a list.

See also:
  wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, wxControlWithItems::SetSelection

int wxListBox::HitTest | ( | int | x,
|  | int | y |
| ) |  |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Reimplemented from wxWindow.

int wxListBox::HitTest | ( | const wxPoint & | point | ) | const

Returns the item located at point, or `wxNOT_FOUND` if there is no item located at point.

It is currently implemented for wxMSW, wxMac and wxGTK2 ports.

Parameters:

  | point | Point of item (in client coordinates) to obtain

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

Since:
  2.7.0

Reimplemented from wxWindow.

void wxListBox::InsertItems | ( | const wxArrayString & | items,
|  | unsigned int | pos |
| ) |  |  |

Insert the given number of strings before the specified position.

Parameters:

  | items | Labels of items to be inserted
  | pos | Position before which to insert the items: if pos is `0` the items will be inserted in the beginning of the listbox

wxPerl Note: Use an array reference for the items parameter.

void wxListBox::InsertItems | ( | unsigned int | nItems,
|  | const wxString * | items,
|  | 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: if pos is 0 the items will be inserted in the beginning of the listbox

wxPerl Note: Not supported by wxPerl.

virtual bool wxListBox::IsSelected | ( | int | n | ) | const`[virtual]`

Determines whether an item is selected.

Parameters:

  | n | The zero-based item index.

Returns:
  true if the given item is selected, false otherwise.

void wxListBox::Set | ( | const wxArrayString & | choices,
|  | void * | clientData |
| ) |  |  |

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

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

Parameters:

  | choices | An array of strings to set.
  | clientData | Options array of client data pointers

void wxListBox::Set | ( | unsigned int | n,
|  | const wxString * | choices,
|  | void * | clientData |
| ) |  |  |

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

void wxListBox::SetFirstItem | ( | const wxString & | string | ) |

Set the specified item to be the first visible item.

Parameters:

  | string | The string that should be visible.

void wxListBox::SetFirstItem | ( | int | n | ) |

Set the specified item to be the first visible item.

Parameters:

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

|  | [ top ]