Some work on GTK focus handling and events.

[wxWidgets.git] / docs / latex / wx / listbox.tex

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

\wxheading{Derived from}

\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/listbox.h>

\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.}
\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},
\rtfsp\helpref{wxCommandEvent}{wxcommandevent}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxListBox::wxListBox}\label{wxlistboxconstr}

\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}, \param{const wxString }{choices[] = NULL},\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}}

\func{void}{\destruct{wxListBox}}{\void}

Destructor, destroying the list box.

\membersection{wxListBox::Append}\label{wxlistboxappend}

\func{void}{Append}{\param{const wxString\& }{ item}}

Adds the item to the end of the list box.

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

\wxheading{Parameters}

\docparam{item}{String to add.}

\docparam{clientData}{Client data to associate with the item.}

\membersection{wxListBox::Clear}\label{wxlistboxclear}

\func{void}{Clear}{\void}

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

Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxconstr}\rtfsp
for further details.

\membersection{wxListBox::Delete}\label{wxlistboxdelete}

\func{void}{Delete}{\param{int}{ n}}

Deletes an item from the listbox.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\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::FindString}\label{wxlistboxfindstring}

\func{int}{FindString}{\param{const wxString\& }{string}}

Finds an item matching the given string.

\wxheading{Parameters}

\docparam{string}{String to find.}

\wxheading{Return value}

The zero-based position of the item, or -1 if the string was not found.

\membersection{wxListBox::GetClientData}\label{wxlistboxgetclientdata}

\constfunc{void*}{GetClientData}{\param{int}{ n}}

Returns a pointer to the client data associated with the given item (if any).

\wxheading{Parameters}

\docparam{n}{The zero-based position of the item.}

\wxheading{Return value}

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}

Gets the position of the selected item.

\wxheading{Return value}

The position of the current selection.

\wxheading{Remarks}

Applicable to single selection list boxes only.

\wxheading{See also}

\helpref{wxListBox::SetSelection}{wxlistboxsetselection},\rtfsp
\helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp
\helpref{wxListBox::GetSelections}{wxlistboxgetselections}

\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{wxListBox::GetSelection}{wxlistboxgetselection},\rtfsp
\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}}

Returns the string at the given position.

\wxheading{Parameters}

\docparam{n}{The zero-based position.}

\wxheading{Return value}

The string, or an empty string if the position was invalid.

\membersection{wxListBox::GetStringSelection}\label{wxlistboxgetstringselection}

\constfunc{wxString}{GetStringSelection}{\void}

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.

\wxheading{See also}

\helpref{wxListBox::GetSelection}{wxlistboxgetselection},\rtfsp
\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}

\constfunc{bool}{Selected}{\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}}

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

\wxheading{Parameters}

\docparam{n}{The number of strings to set.}

\docparam{choices}{An array of strings to set.}

\wxheading{Remarks}

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

\membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata}

\func{void}{SetClientData}{\param{int}{ n}, \param{void* }{data}}

Associates the given client data pointer with the given item.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{data}{The client data to associate with the item.}

\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. Windows only.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{string}{The string that should be visible.}

\membersection{wxListBox::SetSelection}\label{wxlistboxsetselection}

\func{void}{SetSelection}{\param{int}{ n}, \param{const bool }{select = TRUE}}

Selects or deselects the given item. This does not cause a
wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{select}{If TRUE, will select the item. If FALSE, will deselect it.}

\membersection{wxListBox::SetString}\label{wxlistboxsetstring}

\func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}

Sets the string value of an item.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{string}{The string to set.}

\membersection{wxListBox::SetStringSelection}\label{wxlistboxsetstringselection}

\func{void}{SetStringSelection}{\param{const wxString\& }{ string}, \param{const bool}{ select = TRUE}}

Sets the current selection. This does not cause a
wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted.

\wxheading{Parameters}

\docparam{string}{The item to select.}

\docparam{select}{If TRUE, will select the item. If FALSE, will deselect it.}