wxPerl documentation updates

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

diff --git a/docs/latex/wx/combobox.tex b/docs/latex/wx/combobox.tex
index 93adf5361c83e8cd7fa0cccabbeff20ac091ffad..7b780e526cfc52f0a59fad73236f13e58185f0af 100644 (file)
--- a/docs/latex/wx/combobox.tex
+++ b/docs/latex/wx/combobox.tex
@@ -14,21 +14,37 @@ A combobox permits a single selection only. Combobox items are numbered from zer
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
+\wxheading{Include files}
+
+<wx/combobox.h>
+
 \wxheading{Window styles}
 
 \begin{twocollist}\itemsep=0pt
-\twocolitem{\windowstyle{wxCB\_SIMPLE}}{Creates a combobox with a permanently displayed list.}
+\twocolitem{\windowstyle{wxCB\_SIMPLE}}{Creates a combobox with a permanently displayed list. Windows only. }
 \twocolitem{\windowstyle{wxCB\_DROPDOWN}}{Creates a combobox with a drop-down list.}
-\twocolitem{\windowstyle{wxCB\_READONLY}}{Creates a combo box consisting of a drop-down list and static text item
-displaying the current selection.}
+\twocolitem{\windowstyle{wxCB\_READONLY}}{Same as wxCB\_DROPDOWN but only the
+strings specified as the combobox choices can be selected, it is impossible to
+select (even from a program) a string which is not in the choices list.}
 \twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.}
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.
 
+\wxheading{Event handling}
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
+when an item on the list is selected.}
+\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event,
+when the combobox text changes.}
+\end{twocollist}
+
 \wxheading{See also}
 
-\helpref{wxListBox}{wxlistbox}, \helpref{wxTextCtrl}{wxtextctrl}, \helpref{wxChoice}{wxchoice}
+\helpref{wxListBox}{wxlistbox}, \helpref{wxTextCtrl}{wxtextctrl}, \helpref{wxChoice}{wxchoice},
+\rtfsp\helpref{wxCommandEvent}{wxcommandevent}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -38,10 +54,10 @@ See also \helpref{window styles overview}{windowstyles}.
 
 Default constructor.
 
-\func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{const wxWindowID}{ id},\rtfsp
+\func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
-\param{const int}{ n}, \param{const wxString }{choices[]},\rtfsp
-\param{const long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+\param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 
 Constructor, creating and showing a combobox.
 
@@ -70,6 +86,13 @@ appropriately.}
 
 \helpref{wxComboBox::Create}{wxcomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 
+\pythonnote{The wxComboBox 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{wxComboBox::\destruct{wxComboBox}}
 
 \func{}{\destruct{wxComboBox}}{\void}
@@ -82,7 +105,7 @@ Destructor, destroying the combobox.
 
 Adds the item to the end of the combobox.
 
-\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 combobox, associating the given data
 with the item.
@@ -101,10 +124,10 @@ Clears all strings from the combobox.
 
 \membersection{wxComboBox::Create}\label{wxcomboboxcreate}
 
-\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{const wxWindowID}{ id},\rtfsp
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
-\param{const int}{ n}, \param{const wxString }{choices[]},\rtfsp
-\param{const long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+\param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 
 Creates the combobox for two-step construction. Derived classes
 should call or replace this function. See \helpref{wxComboBox::wxComboBox}{wxcomboboxconstr}\rtfsp
@@ -124,7 +147,7 @@ Copies the selected text to the clipboard and removes the selection.
 
 \membersection{wxComboBox::Delete}\label{wxcomboboxdelete}
 
-\func{void}{Delete}{\param{const int}{ n}}
+\func{void}{Delete}{\param{int}{ n}}
 
 Deletes an item from the combobox.
 
@@ -148,7 +171,7 @@ The position if found, or -1 if not found.
 
 \membersection{wxComboBox::GetClientData}\label{wxcomboboxgetclientdata}
 
-\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).
 
@@ -209,8 +232,7 @@ Returns the current value in the combobox text field.
 \constfunc{int}{Number}{\void}
 
 Returns the number of items in the combobox list.
-
-TODO: make this GetNumber or GetCount?
+%TODO: make this GetNumber or GetCount?
 
 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 
@@ -220,7 +242,7 @@ Pastes text from the clipboard to the text field.
 
 \membersection{wxComboBox::Replace}\label{wxcomboboxreplace}
 
-\func{void}{Replace}{\param{const long}{ from}, \param{const long}{ to}, \param{const wxString\& }{text}}
+\func{void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{text}}
 
 Replaces the text between two positions with the given text, in the combobox text field.
 
@@ -234,7 +256,7 @@ Replaces the text between two positions with the given text, in the combobox tex
 
 \membersection{wxComboBox::Remove}\label{wxcomboboxremove}
 
-\func{void}{Remove}{\param{const long}{ from}, \param{const long}{ to}}
+\func{void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 
 Removes the text between the two positions in the combobox text field.
 
@@ -246,7 +268,7 @@ Removes the text between the two positions in the combobox text field.
 
 \membersection{wxComboBox::SetClientData}\label{wxcomboboxsetclientdata}
 
-\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.
 
@@ -258,7 +280,7 @@ Associates the given client data pointer with the given item.
 
 \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint}
 
-\func{void}{SetInsertionPoint}{\param{const long}{ pos}}
+\func{void}{SetInsertionPoint}{\param{long}{ pos}}
 
 Sets the insertion point in the combobox text field.
 
@@ -274,11 +296,12 @@ Sets the insertion point at the end of the combobox text field.
 
 \membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}
 
-\func{void}{SetSelection}{\param{const int}{ n}}
+\func{void}{SetSelection}{\param{int}{ n}}
 
-Selects the given item in the combobox list.
+Selects the given item in the combobox list. This does not cause a
+wxEVT\_COMMAND\_COMBOBOX\_SELECTED event to get emitted.
 
-\func{void}{SetSelection}{\param{const long}{ from}, \param{const long}{ to}}
+\func{void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 
 Selects the text between the two positions, in the combobox text field.
 
@@ -290,12 +313,18 @@ Selects the text between the two positions, in the combobox text field.
 
 \docparam{to}{The second position.}
 
+\pythonnote{The second form of this method is called {\tt SetMark} in
+wxPython.}
+
 \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue}
 
 \func{void}{SetValue}{\param{const wxString\& }{text}}
 
 Sets the text for the combobox text field.
 
+{\bf NB:} For a combobox with {\tt wxCB\_READONLY} style the string must be in
+the combobox choices list, otherwise the call to SetValue() is ignored.
+
 \wxheading{Parameters}
 
 \docparam{text}{The text to set.}