1\section{\class{wxListBox}}\label{wxlistbox} 2 3A listbox is used to select one or more of a list of strings. The 4strings are displayed in a scrolling box, with the selected string(s) 5marked in reverse video. A listbox can be single selection (if an item 6is selected, the previous selection is removed) or multiple selection 7(clicking an item toggles the item on or off independently of other 8selections). 9 10List box elements are numbered from zero. Their number may be limited 11under some platforms. 12 13A listbox callback gets an event wxEVT\_COMMAND\_LISTBOX\_SELECTED for single clicks, and 14wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED for double clicks. 15 16\wxheading{Derived from} 17 18\helpref{wxControlWithItems}{wxcontrolwithitems}\\ 19\helpref{wxControl}{wxcontrol}\\ 20\helpref{wxWindow}{wxwindow}\\ 21\helpref{wxEvtHandler}{wxevthandler}\\ 22\helpref{wxObject}{wxobject} 23 24\wxheading{Include files} 25 26<wx/listbox.h> 27 28\wxheading{Window styles} 29 30\twocolwidtha{5cm}% 31\begin{twocollist}\itemsep=0pt 32\twocolitem{\windowstyle{wxLB\_SINGLE}}{Single-selection list.} 33\twocolitem{\windowstyle{wxLB\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple 34items on and off.} 35\twocolitem{\windowstyle{wxLB\_EXTENDED}}{Extended-selection list: the user can 36select multiple items using the SHIFT key and the mouse or special key combinations.} 37\twocolitem{\windowstyle{wxLB\_HSCROLL}}{Create horizontal scrollbar if contents are too wide (Windows only).} 38\twocolitem{\windowstyle{wxLB\_ALWAYS\_SB}}{Always show a vertical scrollbar.} 39\twocolitem{\windowstyle{wxLB\_NEEDED\_SB}}{Only create a vertical scrollbar if needed.} 40\twocolitem{\windowstyle{wxLB\_SORT}}{The listbox contents are sorted in alphabetical order.} 41\end{twocollist} 42 43Note that {\tt wxLB\_SINGLE}, {\tt wxLB\_MULTIPLE} and {\tt wxLB\_EXTENDED} 44styles are mutually exclusive and you can specify at most one of them (single 45selection is the default). 46 47See also \helpref{window styles overview}{windowstyles}. 48 49\wxheading{Event handling} 50 51\twocolwidtha{7cm} 52\begin{twocollist}\itemsep=0pt 53\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED event, 54when an item on the list is selected or the selection changes.} 55\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event, 56when the listbox is double-clicked.} 57\end{twocollist} 58 59\wxheading{See also} 60 61\helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxListCtrl}{wxlistctrl}, 62\rtfsp\helpref{wxCommandEvent}{wxcommandevent} 63 64\latexignore{\rtfignore{\wxheading{Members}}} 65 66\membersection{wxListBox::wxListBox}\label{wxlistboxctor} 67 68\func{}{wxListBox}{\void} 69 70Default constructor. 71 72\func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 73\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp 74\param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp 75\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} 76 77\func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 78\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp 79\param{const wxArrayString\& }{choices},\rtfsp 80\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} 81 82Constructor, creating and showing a list box. 83 84\wxheading{Parameters} 85 86\docparam{parent}{Parent window. Must not be NULL.} 87 88\docparam{id}{Window identifier. A value of -1 indicates a default value.} 89 90\docparam{pos}{Window position.} 91 92\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized 93appropriately.} 94 95\docparam{n}{Number of strings with which to initialise the control.} 96 97\docparam{choices}{An array of strings with which to initialise the control.} 98 99\docparam{style}{Window style. See \helpref{wxListBox}{wxlistbox}.} 100 101\docparam{validator}{Window validator.} 102 103\docparam{name}{Window name.} 104 105\wxheading{See also} 106 107\helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator} 108 109\pythonnote{The wxListBox constructor in wxPython reduces the {\tt n} 110and {\tt choices} arguments are to a single argument, which is 111a list of strings.} 112 113\perlnote{In wxPerl there is just an array reference in place of {\tt n} 114and {\tt choices}.} 115 116\membersection{wxListBox::\destruct{wxListBox}}\label{wxlistboxdtor} 117 118\func{void}{\destruct{wxListBox}}{\void} 119 120Destructor, destroying the list box. 121 122\membersection{wxListBox::Create}\label{wxlistboxcreate} 123 124\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 125\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp 126\param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp 127\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} 128 129\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp 130\param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp 131\param{const wxArrayString\& }{choices},\rtfsp 132\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} 133 134Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxctor}\rtfsp 135for further details. 136 137\membersection{wxListBox::Deselect}\label{wxlistboxdeselect} 138 139\func{void}{Deselect}{\param{int}{ n}} 140 141Deselects an item in the list box. 142 143\wxheading{Parameters} 144 145\docparam{n}{The zero-based item to deselect.} 146 147\wxheading{Remarks} 148 149This applies to multiple selection listboxes only. 150 151\membersection{wxListBox::GetSelections}\label{wxlistboxgetselections} 152 153\constfunc{int}{GetSelections}{\param{wxArrayInt\& }{selections}} 154 155Fill an array of ints with the positions of the currently selected items. 156 157\wxheading{Parameters} 158 159\docparam{selections}{A reference to an wxArrayInt instance that is used to store the result of the query.} 160 161\wxheading{Return value} 162 163The number of selections. 164 165\wxheading{Remarks} 166 167Use this with a multiple selection listbox. 168 169\wxheading{See also} 170 171\helpref{wxControlWithItems::GetSelection}{wxcontrolwithitemsgetselection},\rtfsp 172\helpref{wxControlWithItems::GetStringSelection}{wxcontrolwithitemsgetstringselection},\rtfsp 173\helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection} 174 175\pythonnote{The wxPython version of this method takes no parameters 176and returns a tuple of the selected items.} 177 178\perlnote{In wxPerl this method takes no parameters and return the 179selected items as a list.} 180 181\membersection{wxListBox::InsertItems}\label{wxlistboxinsertitems} 182 183\func{void}{InsertItems}{\param{int}{ nItems}, \param{const wxString}{ *items}, \param{unsigned int}{ pos}} 184 185\func{void}{InsertItems}{\param{const wxArrayString\&}{ nItems}, \param{unsigned int}{ pos}} 186 187Insert the given number of strings before the specified position. 188 189\wxheading{Parameters} 190 191\docparam{nItems}{Number of items in the array {\it items}} 192 193\docparam{items}{Labels of items to be inserted} 194 195\docparam{pos}{Position before which to insert the items: for example, if {\it pos} is 0 the items 196will be inserted in the beginning of the listbox} 197 198\pythonnote{The first two parameters are collapsed into a single 199parameter for wxPython, which is a list of strings.} 200 201\perlnote{In wxPerl there is just an array reference in place of {\tt nItems} 202and {\tt items}.} 203 204\membersection{wxListBox::HitTest}\label{wxlistboxhittest} 205 206\constfunc{int}{HitTest}{\param{const wxPoint&}{ point}} 207 208Returns the item located at \arg{point}, or \texttt{wxNOT\_FOUND} if there 209is no item located at \arg{point}. 210 211\newsince{2.7.0}. It is currently implemented for wxMSW, wxMac and wxGTK2 212ports. 213 214\wxheading{Parameters} 215 216\docparam{point}{Point of item (in client coordinates) to obtain} 217 218\wxheading{Return value} 219 220Item located at \arg{point}, or \texttt{wxNOT\_FOUND} if unimplemented 221or the item does not exist. 222 223\membersection{wxListBox::IsSelected}\label{wxlistboxisselected} 224 225\constfunc{bool}{IsSelected}{\param{int}{ n}} 226 227Determines whether an item is selected. 228 229\wxheading{Parameters} 230 231\docparam{n}{The zero-based item index.} 232 233\wxheading{Return value} 234 235true if the given item is selected, false otherwise. 236 237\membersection{wxListBox::Set}\label{wxlistboxset} 238 239\func{void}{Set}{\param{int}{ n}, \param{const wxString*}{ choices}, \param{void}{ **clientData = {\tt NULL}}} 240 241\func{void}{Set}{\param{const wxArrayString\&}{ choices}, \param{void}{ **clientData = {\tt NULL}}} 242 243Clears the list box and adds the given strings to it. 244 245\wxheading{Parameters} 246 247\docparam{n}{The number of strings to set.} 248 249\docparam{choices}{An array of strings to set.} 250 251\docparam{clientData}{Options array of client data pointers} 252 253\wxheading{Remarks} 254 255You may free the array from the calling program after this function has been 256called. 257 258\membersection{wxListBox::SetFirstItem}\label{wxlistboxsetfirstitem} 259 260\func{void}{SetFirstItem}{\param{int}{ n}} 261 262\func{void}{SetFirstItem}{\param{const wxString\& }{string}} 263 264Set the specified item to be the first visible item. 265 266\wxheading{Parameters} 267 268\docparam{n}{The zero-based item index.} 269 270\docparam{string}{The string that should be visible.} 271 272