remove C++ comment

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

diff --git a/docs/latex/wx/combobox.tex b/docs/latex/wx/combobox.tex
index 93adf5361c83e8cd7fa0cccabbeff20ac091ffad..413bed234cada9a236e5326487cdd696ae8cd5d7 100644 (file)
--- a/docs/latex/wx/combobox.tex
+++ b/docs/latex/wx/combobox.tex
@@ -6,42 +6,79 @@ text field; or a drop-down list without a text field.
 
 A combobox permits a single selection only. Combobox items are numbered from zero.
 
 
 A combobox permits a single selection only. Combobox items are numbered from zero.
 

+If you need a customized combobox, have a look at \helpref{wxComboCtrl}{wxcomboctrl},
+\helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}, \helpref{wxComboPopup}{wxcombopopup}
+and the ready-to-use \helpref{wxBitmapComboBox}{wxbitmapcombobox}.
+

 \wxheading{Derived from}
 
 \wxheading{Derived from}
 

-\helpref{wxChoice}{wxchoice}\\
+\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/combobox.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Window styles}
 
 \begin{twocollist}\itemsep=0pt
 \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\_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.}
 \twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.}

+\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
+the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
+is either processed internally by the control or used for navigation between
+dialog controls). Windows only.}

 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.
 
 \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. Note that calling
+\helpref{GetValue}{wxcomboboxgetvalue} returns the new value of selection.}
+\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event,
+when the combobox text changes.}
+\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER event,
+when <RETURN> is pressed in the combobox.}
+\end{twocollist}
+

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

-\membersection{wxComboBox::wxComboBox}\label{wxcomboboxconstr}
+
+\membersection{wxComboBox::wxComboBox}\label{wxcomboboxctor}

 
 \func{}{wxComboBox}{\void}
 
 Default constructor.
 
 
 \func{}{wxComboBox}{\void}
 
 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 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 = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
+
+\func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value}, \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 = ``comboBox"}}

 
 Constructor, creating and showing a combobox.
 
 
 Constructor, creating and showing a combobox.
 


@@ -51,6 +88,8 @@ Constructor, creating and showing a combobox.
 
 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 
 
 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 

+\docparam{value}{Initial selection string. An empty string indicates no selection.}
+

 \docparam{pos}{Window position.}
 
 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 \docparam{pos}{Window position.}
 
 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized


@@ -70,95 +109,101 @@ appropriately.}
 
 \helpref{wxComboBox::Create}{wxcomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 
 
 \helpref{wxComboBox::Create}{wxcomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 

-\membersection{wxComboBox::\destruct{wxComboBox}}
+\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}}\label{wxcomboboxdtor}

 
 \func{}{\destruct{wxComboBox}}{\void}
 
 Destructor, destroying the combobox.
 
 
 \func{}{\destruct{wxComboBox}}{\void}
 
 Destructor, destroying the combobox.
 

-\membersection{wxComboBox::Append}\label{wxcomboboxappend}

 
 

-\func{void}{Append}{\param{const wxString\& }{item}}
-
-Adds the item to the end of the combobox.
+\membersection{wxComboBox::Create}\label{wxcomboboxcreate}

 
 

-\func{void}{Append}{\param{const wxString\& }{ item}, \param{char* }{clientData}}
+\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{int}{ n}, \param{const wxString }{choices[]},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}

 
 

-Adds the item to the end of the combobox, associating the given data
-with the item.
+\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
+\param{const wxString\& }{value}, \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 = ``comboBox"}}

 
 

-\wxheading{Parameters}
+Creates the combobox for two-step construction. Derived classes
+should call or replace this function. See \helpref{wxComboBox::wxComboBox}{wxcomboboxctor}\rtfsp
+for further details.

 
 

-\docparam{item}{The string to add.}

 
 

-\docparam{clientData}{Client data to associate with the item.}
+\membersection{wxComboBox::CanCopy}\label{wxcomboboxcancopy}

 
 

-\membersection{wxComboBox::Clear}\label{wxcomboboxclear}
+\constfunc{bool}{CanCopy}{\void}

 
 

-\func{void}{Clear}{\void}
+Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
+Only available on Windows.

 
 

-Clears all strings from the combobox.

 
 

-\membersection{wxComboBox::Create}\label{wxcomboboxcreate}
+\membersection{wxComboBox::CanCut}\label{wxcomboboxcancut}

 
 

-\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{const 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"}}
+\constfunc{bool}{CanCut}{\void}

 
 

-Creates the combobox for two-step construction. Derived classes
-should call or replace this function. See \helpref{wxComboBox::wxComboBox}{wxcomboboxconstr}\rtfsp
-for further details.
+Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
+Only available on Windows.

 
 

-\membersection{wxComboBox::Copy}\label{wxcomboboxcopy}

 
 

-\func{void}{Copy}{\void}
+\membersection{wxComboBox::CanPaste}\label{wxcomboboxcanpaste}

 
 

-Copies the selected text to the clipboard.
+\constfunc{bool}{CanPaste}{\void}

 
 

-\membersection{wxComboBox::Cut}\label{wxcomboboxcut}
+Returns true if the combobox is editable and there is text on the clipboard that can be pasted into the
+text field. Only available on Windows.

 
 

-\func{void}{Cut}{\void}

 
 

-Copies the selected text to the clipboard and removes the selection.
+\membersection{wxComboBox::CanRedo}\label{wxcomboboxcanredo}

 
 

-\membersection{wxComboBox::Delete}\label{wxcomboboxdelete}
+\constfunc{bool}{CanRedo}{\void}

 
 

-\func{void}{Delete}{\param{const int}{ n}}
+Returns true if the combobox is editable and the last undo can be redone.
+Only available on Windows.

 
 

-Deletes an item from the combobox.

 
 

-\wxheading{Parameters}
+\membersection{wxComboBox::CanUndo}\label{wxcomboboxcanundo}

 
 

-\docparam{n}{The item to delete, starting from zero.}
+\constfunc{bool}{CanUndo}{\void}

 
 

-\membersection{wxComboBox::FindString}\label{wxcomboboxfindstring}
+Returns true if the combobox is editable and the last edit can be undone.
+Only available on Windows.

 
 

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

 
 

-Finds a choice matching the given string.
+\membersection{wxComboBox::Copy}\label{wxcomboboxcopy}

 
 

-\wxheading{Parameters}
+\func{void}{Copy}{\void}

 
 

-\docparam{string}{The item to find.}
+Copies the selected text to the clipboard.

 
 

-\wxheading{Return value}

 
 

-The position if found, or -1 if not found.
+\membersection{wxComboBox::Cut}\label{wxcomboboxcut}

 
 

-\membersection{wxComboBox::GetClientData}\label{wxcomboboxgetclientdata}
+\func{void}{Cut}{\void}

 
 

-\constfunc{char*}{GetClientData}{\param{const int}{ n}}
+Copies the selected text to the clipboard and removes the selection.

 
 

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

 
 

-\wxheading{Parameters}
+\membersection{wxComboBox::GetCurrentSelection}\label{wxcomboboxgetcurrentselection}

 
 

-\docparam{n}{An item, starting from zero.}
+\constfunc{int}{GetCurrentSelection}{\void}

 
 

-\wxheading{Return value}
+This function does the same things as 
+\helpref{wxChoice::GetCurrentSelection}{wxchoicegetcurrentselection} and
+returns the item currently selected in the dropdown list if it's open or the
+same thing as \helpref{GetSelection}{wxcontrolwithitemsgetselection} otherwise.

 
 

-A pointer to the client data, or NULL if the item was not found.

 
 \membersection{wxComboBox::GetInsertionPoint}\label{wxcomboboxgetinsertionpoint}
 
 
 \membersection{wxComboBox::GetInsertionPoint}\label{wxcomboboxgetinsertionpoint}
 


@@ -166,37 +211,27 @@ A pointer to the client data, or NULL if the item was not found.
 
 Returns the insertion point for the combobox's text field.
 
 
 Returns the insertion point for the combobox's text field.
 

-\membersection{wxComboBox::GetLastPosition}\label{wxcomboboxgetlastposition}
-
-\constfunc{long}{GetLastPosition}{\void}
-
-Returns the last position in the combobox text field.
-
-\membersection{wxComboBox::GetSelection}\label{wxcomboboxgetselection}
-
-\constfunc{int}{GetSelection}{\void}
+\textbf{Note:} Under wxMSW, this function always returns $0$ if the combobox
+doesn't have the focus.

 
 

-Gets the position of the selected string, or -1 if there is no selection.

 
 

-\membersection{wxComboBox::GetString}\label{wxcomboboxgetstring}
-
-\constfunc{wxString}{GetString}{\param{int}{ n}}
+\membersection{wxComboBox::GetLastPosition}\label{wxcomboboxgetlastposition}

 
 

-Returns the string at position {\it n}.
+\constfunc{virtual wxTextPos}{GetLastPosition}{\void}

 
 

-\wxheading{Parameters}
+Returns the last position in the combobox text field.

 
 

-\docparam{n}{The item position, starting from zero.}

 
 

-\wxheading{Return value}
+\membersection{wxComboBox::GetSelection}\label{wxcomboboxgetselection}

 
 

-The string if the item is found, otherwise the empty string.
+\constfunc{void}{GetSelection}{\param{long *}{from}, \param{long *}{to}}

 
 

-\membersection{wxComboBox::GetStringSelection}\label{wxcomboboxgetstringselection}
+This is the same as \helpref{wxTextCtrl::GetSelection}{wxtextctrlgetselection} 
+for the text control which is part of the combobox. Notice that this is a
+different method from \helpref{wxControlWithItems::GetSelection}{wxcontrolwithitemsgetselection}.

 
 

-\constfunc{wxString}{GetStringSelection}{\void}
+Currently this method is only implemented in wxMSW and wxGTK.

 
 

-Gets the selected string.

 
 \membersection{wxComboBox::GetValue}\label{wxcomboboxgetvalue}
 
 
 \membersection{wxComboBox::GetValue}\label{wxcomboboxgetvalue}
 


@@ -204,13 +239,6 @@ Gets the selected string.
 
 Returns the current value in the combobox text field.
 
 
 Returns the current value in the combobox text field.
 

-\membersection{wxComboBox::Number}\label{wxcomboboxnumber}
-
-\constfunc{int}{Number}{\void}
-
-Returns the number of items in the combobox list.
-
-TODO: make this GetNumber or GetCount?

 
 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 
 
 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 


@@ -218,9 +246,17 @@ TODO: make this GetNumber or GetCount?
 
 Pastes text from the clipboard to the text field.
 
 
 Pastes text from the clipboard to the text field.
 

+
+\membersection{wxComboBox::Redo}\label{wxcomboboxredo}
+
+\func{void}{Redo}{\void}
+
+Redoes the last undo in the text field. Windows only.
+
+

 \membersection{wxComboBox::Replace}\label{wxcomboboxreplace}
 
 \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.
 
 
 Replaces the text between two positions with the given text, in the combobox text field.
 


@@ -232,9 +268,10 @@ Replaces the text between two positions with the given text, in the combobox tex
 
 \docparam{text}{The text to insert.}
 
 
 \docparam{text}{The text to insert.}
 

+

 \membersection{wxComboBox::Remove}\label{wxcomboboxremove}
 
 \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.
 
 
 Removes the text between the two positions in the combobox text field.
 


@@ -244,21 +281,10 @@ Removes the text between the two positions in the combobox text field.
 
 \docparam{to}{The last position.}
 
 
 \docparam{to}{The last position.}
 

-\membersection{wxComboBox::SetClientData}\label{wxcomboboxsetclientdata}
-
-\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.}
-
-\docparam{data}{The client data.}

 
 \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint}
 
 
 \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.
 
 
 Sets the insertion point in the combobox text field.
 


@@ -266,38 +292,48 @@ Sets the insertion point in the combobox text field.
 
 \docparam{pos}{The new insertion point.}
 
 
 \docparam{pos}{The new insertion point.}
 

+

 \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend}
 
 \func{void}{SetInsertionPointEnd}{\void}
 
 Sets the insertion point at the end of the combobox text field.
 
 \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend}
 
 \func{void}{SetInsertionPointEnd}{\void}
 
 Sets the insertion point at the end of the combobox text field.
 

-\membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}

 
 

-\func{void}{SetSelection}{\param{const int}{ n}}
-
-Selects the given item in the combobox list.
+\membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}

 
 

-\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.
 
 \wxheading{Parameters}
 
 
 Selects the text between the two positions, in the combobox text field.
 
 \wxheading{Parameters}
 

-\docparam{n}{The zero-based item to select.}
-

 \docparam{from}{The first position.}
 
 \docparam{to}{The second position.}
 
 \docparam{from}{The first position.}
 
 \docparam{to}{The second position.}
 

+\pythonnote{This method is called {\tt SetMark} in wxPython, {\tt SetSelection}
+name is kept for
+\helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}.}
+
+

 \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue}
 
 \func{void}{SetValue}{\param{const wxString\& }{text}}
 
 Sets the text for the combobox text field.
 
 \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.}
 
 
 \wxheading{Parameters}
 
 \docparam{text}{The text to set.}
 
 

+\membersection{wxComboBox::Undo}\label{wxcomboboxundo}
+
+\func{void}{Undo}{\void}
+
+Undoes the last edit in the text field. Windows only.
+