fixed syntax errors (incorrect use of _)

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

diff --git a/docs/latex/wx/listbox.tex b/docs/latex/wx/listbox.tex
index 75e7037afc6216ab8e224a22a470ee0039156318..de3946a5136f2457c0d42e241c50464b145c4f6f 100644 (file)
--- a/docs/latex/wx/listbox.tex
+++ b/docs/latex/wx/listbox.tex
@@ -7,19 +7,24 @@ is selected, the previous selection is removed) or multiple selection
 (clicking an item toggles the item on or off independently of other
 selections).
 
 (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}.
+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}
 
 
 \wxheading{Derived from}
 

+\helpref{wxControlWithItems}{wxcontrolwithitems}\\

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

+\wxheading{Include files}
+
+<wx/listbox.h>
+

 \wxheading{Window styles}
 
 \twocolwidtha{5cm}%
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}%


@@ -35,24 +40,44 @@ select multiple items using the SHIFT key and the mouse or special key combinati
 \twocolitem{\windowstyle{wxLB\_SORT}}{The listbox contents are sorted in alphabetical order.}
 \end{twocollist}
 
 \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}.
 
 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 double-clicked.}
+\end{twocollist}
+

 \wxheading{See also}
 
 \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}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxListBox::wxListBox}\label{wxlistboxconstr}
+\membersection{wxListBox::wxListBox}\label{wxlistboxctor}

 
 \func{}{wxListBox}{\void}
 
 Default constructor.
 
 
 \func{}{wxListBox}{\void}
 
 Default constructor.
 

-\func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{const wxWindowID}{ id},\rtfsp
+\func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp

 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp

-\param{const int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp
-\param{const long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}}
+\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.
 
 
 Constructor, creating and showing a list box.
 


@@ -81,54 +106,33 @@ appropriately.}
 
 \helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator}
 
 
 \helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator}
 

-\membersection{wxListBox::\destruct{wxListBox}}
-
-\func{void}{\destruct{wxListBox}}{\void}
-
-Destructor, destroying the list box.
-
-\membersection{wxListBox::Append}\label{wxlistboxappend}
+\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.}

 
 

-\func{void}{Append}{\param{const wxString\& }{ item}}
+\perlnote{In wxPerl there is just an array reference in place of {\tt n}
+and {\tt choices}.}

 
 

-Adds the item to the end of the list box.
+\membersection{wxListBox::\destruct{wxListBox}}\label{wxlistboxdtor}

 
 

-\func{void}{Append}{\param{const wxString\& }{ item}, \param{char* }{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}
+\func{void}{\destruct{wxListBox}}{\void}

 
 

-Clears all strings from the list box.
+Destructor, destroying the list box.

 
 \membersection{wxListBox::Create}\label{wxlistboxcreate}
 
 
 \membersection{wxListBox::Create}\label{wxlistboxcreate}
 

-\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{const wxWindowID}{ id},\rtfsp
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp

 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp

-\param{const int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp
-\param{const 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}
+\param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}}

 
 

-\func{void}{Delete}{\param{int}{ n}}
+\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"}}

 
 

-Deletes an item from the listbox.
-
-\wxheading{Parameters}
-
-\docparam{n}{The zero-based item index.}
+Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxctor}\rtfsp
+for further details.

 
 \membersection{wxListBox::Deselect}\label{wxlistboxdeselect}
 
 
 \membersection{wxListBox::Deselect}\label{wxlistboxdeselect}
 


@@ -144,116 +148,81 @@ Deselects an item in the list box.
 
 This applies to multiple selection listboxes only.
 
 
 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}
+\membersection{wxListBox::GetSelections}\label{wxlistboxgetselections}

 
 

-\constfunc{char*}{GetClientData}{\param{const int}{ n}}
+\constfunc{int}{GetSelections}{\param{wxArrayInt\& }{selections}}

 
 

-Returns a pointer to the client data associated with the given item (if any).
+Fill an array of ints with the positions of the currently selected items.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{n}{The zero-based position of the item.}
+\docparam{selections}{A reference to an wxArrayInt instance that is used to store the result of the query.}

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-A pointer to the client data, or NULL if not present.
-
-\membersection{wxListBox::GetSelection}\label{wxlistboxgetselection}
-
-\constfunc{int}{GetSelection}{\void}
+The number of selections.

 
 

-Gets the position of the selected item.
+\wxheading{Remarks}

 
 

-\wxheading{Return value}
+Use this with a multiple selection listbox.

 
 

-The position of the current selection.
+\wxheading{See also}

 
 

-\wxheading{Remarks}
+\helpref{wxControlWithItems::GetSelection}{wxcontrolwithitemsgetselection},\rtfsp
+\helpref{wxControlWithItems::GetStringSelection}{wxcontrolwithitemsgetstringselection},\rtfsp
+\helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}

 
 

-Applicable to single selection list boxes only.
+\pythonnote{The wxPython version of this method takes no parameters
+and returns a tuple of the selected items.}

 
 

-\wxheading{See also}
+\perlnote{In wxPerl this method takes no parameters and return the
+selected items as a list.}

 
 

-\helpref{wxListBox::SetSelection}{wxlistboxsetselection},\rtfsp
-\helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp
-\helpref{wxListBox::GetSelections}{wxlistboxgetselections}
+\membersection{wxListBox::InsertItems}\label{wxlistboxinsertitems}

 
 

-\membersection{wxListBox::GetSelections}\label{wxlistboxgetselections}
+\func{void}{InsertItems}{\param{int}{ nItems}, \param{const wxString}{ *items}, \param{unsigned int}{ pos}}

 
 

-\constfunc{int}{GetSelections}{\param{int **}{selections}}
+\func{void}{InsertItems}{\param{const wxArrayString\&}{ nItems}, \param{unsigned int}{ pos}}

 
 

-Gets an array containing the positions of the selected strings.
+Insert the given number of strings before the specified position.

 
 \wxheading{Parameters}
 
 
 \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{nItems}{Number of items in the array {\it items}}

 
 

-\wxheading{Return value}
+\docparam{items}{Labels of items to be inserted}

 
 

-The number of selections.
+\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}

 
 

-\wxheading{Remarks}
+\pythonnote{The first two parameters are collapsed into a single
+parameter for wxPython, which is a list of strings.}

 
 

-Use this with a multiple selection listbox.
-
-\wxheading{See also}
+\perlnote{In wxPerl there is just an array reference in place of {\tt nItems}
+and {\tt items}.}

 
 

-\helpref{wxListBox::GetSelection}{wxlistboxgetselection},\rtfsp
-\helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp
-\helpref{wxListBox::SetSelection}{wxlistboxsetselection}
+\membersection{wxListBox::HitTest}\label{wxlistboxhittest}

 
 

-\membersection{wxListBox::GetString}\label{wxlistboxgetstring}
+\constfunc{int}{HitTest}{\param{const wxPoint&}{ point}}

 
 

-\constfunc{wxString}{GetString}{\param{const int}{ n}}
+Returns the item located at \arg{point}, or \texttt{wxNOT\_FOUND} if there
+is no item located at \arg{point}.

 
 

-Returns the string at the given position.
+\newsince{2.7.0}. It is currently implemented for wxMSW, wxMac and wxGTK2
+ports.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{n}{The zero-based position.}
+\docparam{point}{Point of item (in client coordinates) to obtain}

 
 \wxheading{Return value}
 
 
 \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}
+Item located at \arg{point}, or \texttt{wxNOT\_FOUND} if unimplemented
+or the item does not exist.

 
 

-\membersection{wxListBox::Number}\label{wxlistboxnumber}
+\membersection{wxListBox::IsSelected}\label{wxlistboxisselected}

 
 

-\constfunc{int}{Number}{\void}
-
-Returns the number of items in the listbox.
-
-\membersection{wxListBox::Selected}\label{wxlistboxselected}
-
-\constfunc{bool}{Selected}{\param{const int}{ n}}
+\constfunc{bool}{IsSelected}{\param{int}{ n}}

 
 Determines whether an item is selected.
 
 
 Determines whether an item is selected.
 


@@ -263,13 +232,15 @@ Determines whether an item is selected.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if the given item is selected, FALSE otherwise.
+true if the given item is selected, false otherwise.

 
 \membersection{wxListBox::Set}\label{wxlistboxset}
 
 
 \membersection{wxListBox::Set}\label{wxlistboxset}
 

-\func{void}{Set}{\param{const int}{ n}, \param{const wxString*}{ choices}}
+\func{void}{Set}{\param{int}{ n}, \param{const wxString*}{ choices}, \param{void}{ **clientData = {\tt NULL}}}

 
 

-Clears the list box and adds the given strings.
+\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}
 
 
 \wxheading{Parameters}
 


@@ -277,22 +248,12 @@ Clears the list box and adds the given strings.
 
 \docparam{choices}{An array 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.
+\docparam{clientData}{Options array of client data pointers}

 
 

-\membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata}
-
-\func{void}{SetClientData}{\param{const int}{ n}, \param{char* }{data}}
-
-Associates the given client data pointer with the given item.
-
-\wxheading{Parameters}
-
-\docparam{n}{The zero-based item index.}
+\wxheading{Remarks}

 
 

-\docparam{data}{The client data to associate with the item.}
+You may free the array from the calling program after this function has been
+called.

 
 \membersection{wxListBox::SetFirstItem}\label{wxlistboxsetfirstitem}
 
 
 \membersection{wxListBox::SetFirstItem}\label{wxlistboxsetfirstitem}
 


@@ -300,7 +261,7 @@ Associates the given client data pointer with the given item.
 
 \func{void}{SetFirstItem}{\param{const wxString\& }{string}}
 
 
 \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}
 
 
 \wxheading{Parameters}
 


@@ -308,39 +269,3 @@ Set the specified item to be the first visible item.
 
 \docparam{string}{The string that should be visible.}
 
 
 \docparam{string}{The string that should be visible.}
 

-\membersection{wxListBox::SetSelection}\label{wxlistboxsetselection}
-
-\func{void}{SetSelection}{\param{const int}{ n}, \param{const bool }{select = TRUE}}
-
-Selects or deselects the given item.
-
-\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{const 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.
-
-\wxheading{Parameters}
-
-\docparam{string}{The item to select.}
-
-\docparam{select}{If TRUE, will select the item. If FALSE, will deselect it.}
-