added wxEVT_COMMAND_LIST_ITEM_FOCUSED event and implemented it for the generic version

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

diff --git a/docs/latex/wx/listbox.tex b/docs/latex/wx/listbox.tex
index 75e7037afc6216ab8e224a22a470ee0039156318..c7707cb4aac196b638bcce5ee4d53f87a0f9956c 100644 (file)
--- a/docs/latex/wx/listbox.tex
+++ b/docs/latex/wx/listbox.tex
@@ -7,11 +7,11 @@ 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
 
 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}
 
 
 \wxheading{Derived from}
 


@@ -20,6 +20,10 @@ double clicks is to override \helpref{wxWindow::OnDefaultAction}{wxwindowondefau
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 

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

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


@@ -35,11 +39,26 @@ 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 doubleclicked.}
+\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}}}
 


@@ -49,10 +68,10 @@ See also \helpref{window styles overview}{windowstyles}.
 
 Default constructor.
 
 
 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}, \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.
 
 
 Constructor, creating and showing a list box.
 


@@ -81,6 +100,13 @@ appropriately.}
 
 \helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator}
 
 
 \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}
 \membersection{wxListBox::\destruct{wxListBox}}
 
 \func{void}{\destruct{wxListBox}}{\void}


@@ -93,7 +119,7 @@ Destructor, destroying the list box.
 
 Adds the item to the end of the list box.
 
 
 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.
 
 Adds the item to the end of the list box, associating the given data
 with the item.


@@ -112,10 +138,10 @@ Clears all strings from 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"}}
+\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.
 
 Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxconstr}\rtfsp
 for further details.


@@ -160,7 +186,7 @@ The zero-based position of the item, or -1 if the string was not found.
 
 \membersection{wxListBox::GetClientData}\label{wxlistboxgetclientdata}
 
 
 \membersection{wxListBox::GetClientData}\label{wxlistboxgetclientdata}
 

-\constfunc{char*}{GetClientData}{\param{const int}{ n}}
+\constfunc{void*}{GetClientData}{\param{int}{ n}}

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


@@ -194,14 +220,13 @@ Applicable to single selection list boxes only.
 
 \membersection{wxListBox::GetSelections}\label{wxlistboxgetselections}
 
 
 \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}
 
 
 \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}
 
 
 \wxheading{Return value}
 


@@ -217,9 +242,15 @@ Use this with a multiple selection listbox.
 \helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp
 \helpref{wxListBox::SetSelection}{wxlistboxsetselection}
 
 \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}
 
 \membersection{wxListBox::GetString}\label{wxlistboxgetstring}
 

-\constfunc{wxString}{GetString}{\param{const int}{ n}}
+\constfunc{wxString}{GetString}{\param{int}{ n}}

 
 Returns the string at the given position.
 
 
 Returns the string at the given position.
 


@@ -245,6 +276,27 @@ it.
 \helpref{wxListBox::GetSelections}{wxlistboxgetselections},\rtfsp
 \helpref{wxListBox::SetSelection}{wxlistboxsetselection}
 
 \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}
 \membersection{wxListBox::Number}\label{wxlistboxnumber}
 
 \constfunc{int}{Number}{\void}


@@ -253,7 +305,7 @@ Returns the number of items in the listbox.
 
 \membersection{wxListBox::Selected}\label{wxlistboxselected}
 
 
 \membersection{wxListBox::Selected}\label{wxlistboxselected}
 

-\constfunc{bool}{Selected}{\param{const int}{ n}}
+\constfunc{bool}{Selected}{\param{int}{ n}}

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


@@ -267,9 +319,9 @@ 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}}

 
 

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

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -284,7 +336,7 @@ after this function has been called.
 
 \membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata}
 
 
 \membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata}
 

-\func{void}{SetClientData}{\param{const int}{ n}, \param{char* }{data}}
+\func{void}{SetClientData}{\param{int}{ n}, \param{void* }{data}}

 
 Associates the given client data pointer with the given item.
 
 
 Associates the given client data pointer with the given item.
 


@@ -300,7 +352,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}
 


@@ -310,9 +362,10 @@ Set the specified item to be the first visible item.
 
 \membersection{wxListBox::SetSelection}\label{wxlistboxsetselection}
 
 
 \membersection{wxListBox::SetSelection}\label{wxlistboxsetselection}
 

-\func{void}{SetSelection}{\param{const int}{ n}, \param{const bool }{select = TRUE}}
+\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}
 
 
 \wxheading{Parameters}
 


@@ -322,7 +375,7 @@ Selects or deselects the given item.
 
 \membersection{wxListBox::SetString}\label{wxlistboxsetstring}
 
 
 \membersection{wxListBox::SetString}\label{wxlistboxsetstring}
 

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

 
 Sets the string value of an item.
 
 
 Sets the string value of an item.
 


@@ -336,7 +389,8 @@ Sets the string value of an item.
 
 \func{void}{SetStringSelection}{\param{const wxString\& }{ string}, \param{const bool}{ select = TRUE}}
 
 
 \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}
 
 
 \wxheading{Parameters}