| 1 | \section{\class{wxComboBox}}\label{wxcombobox} |
| 2 | |
| 3 | A combobox is like a combination of an edit control and a listbox. It can be |
| 4 | displayed as static list with editable or read-only text field; or a drop-down list with |
| 5 | text field; or a drop-down list without a text field. |
| 6 | |
| 7 | A combobox permits a single selection only. Combobox items are numbered from zero. |
| 8 | |
| 9 | \wxheading{Derived from} |
| 10 | |
| 11 | \helpref{wxControlWithItems}{wxcontrolwithitems}\\ |
| 12 | \helpref{wxControl}{wxcontrol}\\ |
| 13 | \helpref{wxWindow}{wxwindow}\\ |
| 14 | \helpref{wxEvtHandler}{wxevthandler}\\ |
| 15 | \helpref{wxObject}{wxobject} |
| 16 | |
| 17 | \wxheading{Include files} |
| 18 | |
| 19 | <wx/combobox.h> |
| 20 | |
| 21 | \wxheading{Window styles} |
| 22 | |
| 23 | \begin{twocollist}\itemsep=0pt |
| 24 | \twocolitem{\windowstyle{wxCB\_SIMPLE}}{Creates a combobox with a permanently displayed list. Windows only. } |
| 25 | \twocolitem{\windowstyle{wxCB\_DROPDOWN}}{Creates a combobox with a drop-down list.} |
| 26 | \twocolitem{\windowstyle{wxCB\_READONLY}}{Same as wxCB\_DROPDOWN but only the |
| 27 | strings specified as the combobox choices can be selected, it is impossible to |
| 28 | select (even from a program) a string which is not in the choices list.} |
| 29 | \twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.} |
| 30 | \end{twocollist} |
| 31 | |
| 32 | See also \helpref{window styles overview}{windowstyles}. |
| 33 | |
| 34 | \wxheading{Event handling} |
| 35 | |
| 36 | \twocolwidtha{7cm} |
| 37 | \begin{twocollist}\itemsep=0pt |
| 38 | \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event, |
| 39 | when an item on the list is selected.} |
| 40 | \twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event, |
| 41 | when the combobox text changes.} |
| 42 | \end{twocollist} |
| 43 | |
| 44 | \wxheading{See also} |
| 45 | |
| 46 | \helpref{wxListBox}{wxlistbox}, \helpref{wxTextCtrl}{wxtextctrl}, \helpref{wxChoice}{wxchoice}, |
| 47 | \rtfsp\helpref{wxCommandEvent}{wxcommandevent} |
| 48 | |
| 49 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 50 | |
| 51 | \membersection{wxComboBox::wxComboBox}\label{wxcomboboxconstr} |
| 52 | |
| 53 | \func{}{wxComboBox}{\void} |
| 54 | |
| 55 | Default constructor. |
| 56 | |
| 57 | \func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
| 58 | \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp |
| 59 | \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp |
| 60 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} |
| 61 | |
| 62 | \func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
| 63 | \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp |
| 64 | \param{const wxArrayString\& }{choices},\rtfsp |
| 65 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} |
| 66 | |
| 67 | Constructor, creating and showing a combobox. |
| 68 | |
| 69 | \wxheading{Parameters} |
| 70 | |
| 71 | \docparam{parent}{Parent window. Must not be NULL.} |
| 72 | |
| 73 | \docparam{id}{Window identifier. A value of -1 indicates a default value.} |
| 74 | |
| 75 | \docparam{value}{Initial selection string. An empty string indicates no selection.} |
| 76 | |
| 77 | \docparam{pos}{Window position.} |
| 78 | |
| 79 | \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized |
| 80 | appropriately.} |
| 81 | |
| 82 | \docparam{n}{Number of strings with which to initialise the control.} |
| 83 | |
| 84 | \docparam{choices}{An array of strings with which to initialise the control.} |
| 85 | |
| 86 | \docparam{style}{Window style. See \helpref{wxComboBox}{wxcombobox}.} |
| 87 | |
| 88 | \docparam{validator}{Window validator.} |
| 89 | |
| 90 | \docparam{name}{Window name.} |
| 91 | |
| 92 | \wxheading{See also} |
| 93 | |
| 94 | \helpref{wxComboBox::Create}{wxcomboboxcreate}, \helpref{wxValidator}{wxvalidator} |
| 95 | |
| 96 | \pythonnote{The wxComboBox constructor in wxPython reduces the {\tt n} |
| 97 | and {\tt choices} arguments are to a single argument, which is |
| 98 | a list of strings.} |
| 99 | |
| 100 | \perlnote{In wxPerl there is just an array reference in place of {\tt n} |
| 101 | and {\tt choices}.} |
| 102 | |
| 103 | \membersection{wxComboBox::\destruct{wxComboBox}} |
| 104 | |
| 105 | \func{}{\destruct{wxComboBox}}{\void} |
| 106 | |
| 107 | Destructor, destroying the combobox. |
| 108 | |
| 109 | \membersection{wxComboBox::Create}\label{wxcomboboxcreate} |
| 110 | |
| 111 | \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
| 112 | \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp |
| 113 | \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp |
| 114 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} |
| 115 | |
| 116 | \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
| 117 | \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp |
| 118 | \param{const wxArrayString\& }{choices},\rtfsp |
| 119 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} |
| 120 | |
| 121 | Creates the combobox for two-step construction. Derived classes |
| 122 | should call or replace this function. See \helpref{wxComboBox::wxComboBox}{wxcomboboxconstr}\rtfsp |
| 123 | for further details. |
| 124 | |
| 125 | \membersection{wxComboBox::Copy}\label{wxcomboboxcopy} |
| 126 | |
| 127 | \func{void}{Copy}{\void} |
| 128 | |
| 129 | Copies the selected text to the clipboard. |
| 130 | |
| 131 | \membersection{wxComboBox::Cut}\label{wxcomboboxcut} |
| 132 | |
| 133 | \func{void}{Cut}{\void} |
| 134 | |
| 135 | Copies the selected text to the clipboard and removes the selection. |
| 136 | |
| 137 | \membersection{wxComboBox::GetInsertionPoint}\label{wxcomboboxgetinsertionpoint} |
| 138 | |
| 139 | \constfunc{long}{GetInsertionPoint}{\void} |
| 140 | |
| 141 | Returns the insertion point for the combobox's text field. |
| 142 | |
| 143 | \membersection{wxComboBox::GetLastPosition}\label{wxcomboboxgetlastposition} |
| 144 | |
| 145 | \constfunc{long}{GetLastPosition}{\void} |
| 146 | |
| 147 | Returns the last position in the combobox text field. |
| 148 | |
| 149 | \membersection{wxComboBox::GetValue}\label{wxcomboboxgetvalue} |
| 150 | |
| 151 | \constfunc{wxString}{GetValue}{\void} |
| 152 | |
| 153 | Returns the current value in the combobox text field. |
| 154 | |
| 155 | \membersection{wxComboBox::Paste}\label{wxcomboboxpaste} |
| 156 | |
| 157 | \func{void}{Paste}{\void} |
| 158 | |
| 159 | Pastes text from the clipboard to the text field. |
| 160 | |
| 161 | \membersection{wxComboBox::Replace}\label{wxcomboboxreplace} |
| 162 | |
| 163 | \func{void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{text}} |
| 164 | |
| 165 | Replaces the text between two positions with the given text, in the combobox text field. |
| 166 | |
| 167 | \wxheading{Parameters} |
| 168 | |
| 169 | \docparam{from}{The first position.} |
| 170 | |
| 171 | \docparam{to}{The second position.} |
| 172 | |
| 173 | \docparam{text}{The text to insert.} |
| 174 | |
| 175 | \membersection{wxComboBox::Remove}\label{wxcomboboxremove} |
| 176 | |
| 177 | \func{void}{Remove}{\param{long}{ from}, \param{long}{ to}} |
| 178 | |
| 179 | Removes the text between the two positions in the combobox text field. |
| 180 | |
| 181 | \wxheading{Parameters} |
| 182 | |
| 183 | \docparam{from}{The first position.} |
| 184 | |
| 185 | \docparam{to}{The last position.} |
| 186 | |
| 187 | \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint} |
| 188 | |
| 189 | \func{void}{SetInsertionPoint}{\param{long}{ pos}} |
| 190 | |
| 191 | Sets the insertion point in the combobox text field. |
| 192 | |
| 193 | \wxheading{Parameters} |
| 194 | |
| 195 | \docparam{pos}{The new insertion point.} |
| 196 | |
| 197 | \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend} |
| 198 | |
| 199 | \func{void}{SetInsertionPointEnd}{\void} |
| 200 | |
| 201 | Sets the insertion point at the end of the combobox text field. |
| 202 | |
| 203 | \membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection} |
| 204 | |
| 205 | \func{void}{SetSelection}{\param{long}{ from}, \param{long}{ to}} |
| 206 | |
| 207 | Selects the text between the two positions, in the combobox text field. |
| 208 | |
| 209 | \wxheading{Parameters} |
| 210 | |
| 211 | \docparam{from}{The first position.} |
| 212 | |
| 213 | \docparam{to}{The second position.} |
| 214 | |
| 215 | \pythonnote{This method is called {\tt SetMark} in wxPython, {\tt SetSelection} |
| 216 | name is kept for |
| 217 | \helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}.} |
| 218 | |
| 219 | \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue} |
| 220 | |
| 221 | \func{void}{SetValue}{\param{const wxString\& }{text}} |
| 222 | |
| 223 | Sets the text for the combobox text field. |
| 224 | |
| 225 | {\bf NB:} For a combobox with {\tt wxCB\_READONLY} style the string must be in |
| 226 | the combobox choices list, otherwise the call to SetValue() is ignored. |
| 227 | |
| 228 | \wxheading{Parameters} |
| 229 | |
| 230 | \docparam{text}{The text to set.} |
| 231 | |
| 232 | |