(clicking an item toggles the item on or off independently of other
selections).
-List box elements are numbered from zero.
+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. Another way of intercepting
-double clicks is to override \helpref{wxWindow::OnDefaultAction}{wxwindowondefaultaction}.
+wxEVT\_COMMAND\_LISTBOX\_DOUBLE\_CLICKED for double clicks.
\wxheading{Derived from}
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/listbox.h>
+
\wxheading{Window styles}
\twocolwidtha{5cm}%
\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.}
+\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event,
+when the listbox is doubleclicked.}
+\end{twocollist}
+
\wxheading{See also}
-\helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxListCtrl}{wxlistctrl}
+\helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxListCtrl}{wxlistctrl},
+\rtfsp\helpref{wxCommandEvent}{wxcommandevent}
\latexignore{\rtfignore{\wxheading{Members}}}
\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}}
\func{void}{\destruct{wxListBox}}{\void}
Adds the item to the end of the list box.
-\func{void}{Append}{\param{const wxString\& }{ item}, \param{char* }{clientData}}
+\func{void}{Append}{\param{const wxString\& }{ item}, \param{void* }{clientData}}
Adds the item to the end of the list box, associating the given data
with the item.
\membersection{wxListBox::GetClientData}\label{wxlistboxgetclientdata}
-\constfunc{char*}{GetClientData}{\param{int}{ n}}
+\constfunc{void*}{GetClientData}{\param{int}{ n}}
Returns a pointer to the client data associated with the given item (if any).
A pointer to the client data, or NULL if not present.
+\membersection{wxListBox::GetCount}\label{wxlistboxgetcount}
+
+\constfunc{int}{GetCount}{\void}
+
+Returns the number of items in the listbox.
+
\membersection{wxListBox::GetSelection}\label{wxlistboxgetselection}
\constfunc{int}{GetSelection}{\void}
\membersection{wxListBox::GetSelections}\label{wxlistboxgetselections}
-\constfunc{int}{GetSelections}{\param{int **}{selections}}
+\constfunc{int}{GetSelections}{\param{wxArrayInt\& }{selections}}
-Gets an array containing the positions of the selected strings.
+Fill an array of ints with the positions of the currently selected items.
\wxheading{Parameters}
-\docparam{selections}{A pointer to an integer array, which will be allocated by the function if
-selects are present. Do not deallocate the returned array - it will be deallocated by the listbox.}
+\docparam{selections}{A reference to an wxArrayInt instance that is used to store the result of the query.}
\wxheading{Return value}
\helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp
\helpref{wxListBox::SetSelection}{wxlistboxsetselection}
+\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 returna the
+selected items as a list.}
+
\membersection{wxListBox::GetString}\label{wxlistboxgetstring}
\constfunc{wxString}{GetString}{\param{int}{ n}}
\helpref{wxListBox::GetSelections}{wxlistboxgetselections},\rtfsp
\helpref{wxListBox::SetSelection}{wxlistboxsetselection}
+\membersection{wxListBox::InsertItems}\label{wxlistboxinsertitems}
+
+\func{void}{InsertItems}{\param{int}{ nItems}, \param{const wxString}{ items}, \param{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::Number}\label{wxlistboxnumber}
\constfunc{int}{Number}{\void}
+{\bf Obsolescence note:} This method is obsolete and was replaced with
+\helpref{GetCount}{wxlistboxgetcount}, please use the new method in the new
+code. This method is only available if wxWindows was compiled with
+{\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
+future versions.
+
Returns the number of items in the listbox.
\membersection{wxListBox::Selected}\label{wxlistboxselected}
\func{void}{Set}{\param{int}{ n}, \param{const wxString*}{ choices}}
-Clears the list box and adds the given strings.
+Clears the list box and adds the given strings. Not implemented for GTK.
\wxheading{Parameters}
\membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata}
-\func{void}{SetClientData}{\param{int}{ n}, \param{char* }{data}}
+\func{void}{SetClientData}{\param{int}{ n}, \param{void* }{data}}
Associates the given client data pointer with the given item.
\func{void}{SetFirstItem}{\param{const wxString\& }{string}}
-Set the specified item to be the first visible item.
+Set the specified item to be the first visible item. Windows only.
\wxheading{Parameters}
\func{void}{SetSelection}{\param{int}{ n}, \param{const bool }{select = TRUE}}
-Selects or deselects the given item.
+Selects or deselects the given item. This does not cause a
+wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted.
\wxheading{Parameters}
\func{void}{SetStringSelection}{\param{const wxString\& }{ string}, \param{const bool}{ select = TRUE}}
-Sets the current selection.
+Sets the current selection. This does not cause a
+wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted.
\wxheading{Parameters}
projects / wxWidgets.git / blobdiff