\section{\class{wxListBox}}\label{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. \wxheading{Derived from} \helpref{wxControlWithItems}{wxcontrolwithitems}\\ \helpref{wxControl}{wxcontrol}\\ \helpref{wxWindow}{wxwindow}\\ \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} \wxheading{Include files} \wxheading{Library} \helpref{wxCore}{librarieslist} \wxheading{Window styles} \twocolwidtha{5cm}% \begin{twocollist}\itemsep=0pt \twocolitem{\windowstyle{wxLB\_SINGLE}}{Single-selection list.} \twocolitem{\windowstyle{wxLB\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple items on and off.} \twocolitem{\windowstyle{wxLB\_EXTENDED}}{Extended-selection list: the user can select multiple items using the SHIFT key and the mouse or special key combinations.} \twocolitem{\windowstyle{wxLB\_HSCROLL}}{Create horizontal scrollbar if contents are too wide (Windows only).} \twocolitem{\windowstyle{wxLB\_ALWAYS\_SB}}{Always show a vertical scrollbar.} \twocolitem{\windowstyle{wxLB\_NEEDED\_SB}}{Only create a vertical scrollbar if needed.} \twocolitem{\windowstyle{wxLB\_SORT}}{The listbox contents are sorted in alphabetical order.} \end{twocollist} Note that {\tt wxLB\_SINGLE}, {\tt wxLB\_MULTIPLE} and {\tt wxLB\_EXTENDED} styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also \helpref{window styles overview}{windowstyles}. \wxheading{Event handling} \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt \twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED event, when an item on the list is selected or the selection changes.} \twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event, when the listbox is double-clicked.} \end{twocollist} \wxheading{See also} \helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxListCtrl}{wxlistctrl}, \rtfsp\helpref{wxCommandEvent}{wxcommandevent} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxListBox::wxListBox}\label{wxlistboxctor} \func{}{wxListBox}{\void} Default constructor. \func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} \func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp \param{const wxArrayString\& }{choices},\rtfsp \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} Constructor, creating and showing a list box. \wxheading{Parameters} \docparam{parent}{Parent window. Must not be NULL.} \docparam{id}{Window identifier. A value of -1 indicates a default value.} \docparam{pos}{Window position.} \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized appropriately.} \docparam{n}{Number of strings with which to initialise the control.} \docparam{choices}{An array of strings with which to initialise the control.} \docparam{style}{Window style. See \helpref{wxListBox}{wxlistbox}.} \docparam{validator}{Window validator.} \docparam{name}{Window name.} \wxheading{See also} \helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator} \pythonnote{The wxListBox constructor in wxPython reduces the {\tt n} and {\tt choices} arguments are to a single argument, which is a list of strings.} \perlnote{In wxPerl there is just an array reference in place of {\tt n} and {\tt choices}.} \membersection{wxListBox::\destruct{wxListBox}}\label{wxlistboxdtor} \func{void}{\destruct{wxListBox}}{\void} Destructor, destroying the list box. \membersection{wxListBox::Create}\label{wxlistboxcreate} \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp \param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp \param{const wxArrayString\& }{choices},\rtfsp \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxctor}\rtfsp for further details. \membersection{wxListBox::Deselect}\label{wxlistboxdeselect} \func{void}{Deselect}{\param{int}{ n}} Deselects an item in the list box. \wxheading{Parameters} \docparam{n}{The zero-based item to deselect.} \wxheading{Remarks} This applies to multiple selection listboxes only. \membersection{wxListBox::GetSelections}\label{wxlistboxgetselections} \constfunc{int}{GetSelections}{\param{wxArrayInt\& }{selections}} Fill an array of ints with the positions of the currently selected items. \wxheading{Parameters} \docparam{selections}{A reference to an wxArrayInt instance that is used to store the result of the query.} \wxheading{Return value} The number of selections. \wxheading{Remarks} Use this with a multiple selection listbox. \wxheading{See also} \helpref{wxControlWithItems::GetSelection}{wxcontrolwithitemsgetselection},\rtfsp \helpref{wxControlWithItems::GetStringSelection}{wxcontrolwithitemsgetstringselection},\rtfsp \helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection} \pythonnote{The wxPython version of this method takes no parameters and returns a tuple of the selected items.} \perlnote{In wxPerl this method takes no parameters and return the selected items as a list.} \membersection{wxListBox::InsertItems}\label{wxlistboxinsertitems} \func{void}{InsertItems}{\param{int}{ nItems}, \param{const wxString}{ *items}, \param{unsigned int}{ pos}} \func{void}{InsertItems}{\param{const wxArrayString\&}{ nItems}, \param{unsigned int}{ pos}} Insert the given number of strings before the specified position. \wxheading{Parameters} \docparam{nItems}{Number of items in the array {\it items}} \docparam{items}{Labels of items to be inserted} \docparam{pos}{Position before which to insert the items: for example, if {\it pos} is 0 the items will be inserted in the beginning of the listbox} \pythonnote{The first two parameters are collapsed into a single parameter for wxPython, which is a list of strings.} \perlnote{In wxPerl there is just an array reference in place of {\tt nItems} and {\tt items}.} \membersection{wxListBox::HitTest}\label{wxlistboxhittest} \constfunc{int}{HitTest}{\param{const wxPoint&}{ point}} Returns the item located at \arg{point}, or \texttt{wxNOT\_FOUND} if there is no item located at \arg{point}. \newsince{2.7.0}. It is currently implemented for wxMSW, wxMac and wxGTK2 ports. \wxheading{Parameters} \docparam{point}{Point of item (in client coordinates) to obtain} \wxheading{Return value} Item located at \arg{point}, or \texttt{wxNOT\_FOUND} if unimplemented or the item does not exist. \membersection{wxListBox::IsSelected}\label{wxlistboxisselected} \constfunc{bool}{IsSelected}{\param{int}{ n}} Determines whether an item is selected. \wxheading{Parameters} \docparam{n}{The zero-based item index.} \wxheading{Return value} true if the given item is selected, false otherwise. \membersection{wxListBox::Set}\label{wxlistboxset} \func{void}{Set}{\param{int}{ n}, \param{const wxString*}{ choices}, \param{void}{ **clientData = {\tt NULL}}} \func{void}{Set}{\param{const wxArrayString\&}{ choices}, \param{void}{ **clientData = {\tt NULL}}} Clears the list box and adds the given strings to it. \wxheading{Parameters} \docparam{n}{The number of strings to set.} \docparam{choices}{An array of strings to set.} \docparam{clientData}{Options array of client data pointers} \wxheading{Remarks} You may free the array from the calling program after this function has been called. \membersection{wxListBox::SetFirstItem}\label{wxlistboxsetfirstitem} \func{void}{SetFirstItem}{\param{int}{ n}} \func{void}{SetFirstItem}{\param{const wxString\& }{string}} Set the specified item to be the first visible item. \wxheading{Parameters} \docparam{n}{The zero-based item index.} \docparam{string}{The string that should be visible.}