docs/latex/wx/combobox.tex

   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 \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
  31 the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
  32 is either processed internally by the control or used for navigation between
  33 dialog controls). Windows only.}
  34 \end{twocollist}
  35
  36 See also \helpref{window styles overview}{windowstyles}.
  37
  38 \wxheading{Event handling}
  39
  40 \twocolwidtha{7cm}
  41 \begin{twocollist}\itemsep=0pt
  42 \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
  43 when an item on the list is selected. Note that calling
  44 \helpref{GetValue}{wxcomboboxgetvalue} returns the new value of selection.}
  45 \twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event,
  46 when the combobox text changes.}
  47 \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER event,
  48 when <RETURN> is pressed in the combobox.}
  49 \end{twocollist}
  50
  51 \wxheading{See also}
  52
  53 \helpref{wxListBox}{wxlistbox}, \helpref{wxTextCtrl}{wxtextctrl}, \helpref{wxChoice}{wxchoice},
  54 \rtfsp\helpref{wxCommandEvent}{wxcommandevent}
  55
  56 \latexignore{\rtfignore{\wxheading{Members}}}
  57
  58
  59 \membersection{wxComboBox::wxComboBox}\label{wxcomboboxctor}
  60
  61 \func{}{wxComboBox}{\void}
  62
  63 Default constructor.
  64
  65 \func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  66 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  67 \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
  68 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  69
  70 \func{}{wxComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  71 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
  72 \param{const wxArrayString\& }{choices},\rtfsp
  73 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  74
  75 Constructor, creating and showing a combobox.
  76
  77 \wxheading{Parameters}
  78
  79 \docparam{parent}{Parent window. Must not be NULL.}
  80
  81 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  82
  83 \docparam{value}{Initial selection string. An empty string indicates no selection.}
  84
  85 \docparam{pos}{Window position.}
  86
  87 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
  88 appropriately.}
  89
  90 \docparam{n}{Number of strings with which to initialise the control.}
  91
  92 \docparam{choices}{An array of strings with which to initialise the control.}
  93
  94 \docparam{style}{Window style. See \helpref{wxComboBox}{wxcombobox}.}
  95
  96 \docparam{validator}{Window validator.}
  97
  98 \docparam{name}{Window name.}
  99
 100 \wxheading{See also}
 101
 102 \helpref{wxComboBox::Create}{wxcomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 103
 104 \pythonnote{The wxComboBox constructor in wxPython reduces the {\tt n}
 105 and {\tt choices} arguments are to a single argument, which is
 106 a list of strings.}
 107
 108 \perlnote{In wxPerl there is just an array reference in place of {\tt n}
 109 and {\tt choices}.}
 110
 111
 112 \membersection{wxComboBox::\destruct{wxComboBox}}\label{wxcomboboxdtor}
 113
 114 \func{}{\destruct{wxComboBox}}{\void}
 115
 116 Destructor, destroying the combobox.
 117
 118
 119 \membersection{wxComboBox::Create}\label{wxcomboboxcreate}
 120
 121 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 122 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 123 \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
 124 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 125
 126 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 127 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
 128 \param{const wxArrayString\& }{choices},\rtfsp
 129 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 130
 131 Creates the combobox for two-step construction. Derived classes
 132 should call or replace this function. See \helpref{wxComboBox::wxComboBox}{wxcomboboxctor}\rtfsp
 133 for further details.
 134
 135
 136 \membersection{wxComboBox::CanCopy}\label{wxcomboboxcancopy}
 137
 138 \constfunc{bool}{CanCopy}{\void}
 139
 140 Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
 141 Only available on Windows.
 142
 143
 144 \membersection{wxComboBox::CanCut}\label{wxcomboboxcancut}
 145
 146 \constfunc{bool}{CanCut}{\void}
 147
 148 Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
 149 Only available on Windows.
 150
 151
 152 \membersection{wxComboBox::CanPaste}\label{wxcomboboxcanpaste}
 153
 154 \constfunc{bool}{CanPaste}{\void}
 155
 156 Returns true if the combobox is editable and there is text on the clipboard that can be pasted into the
 157 text field. Only available on Windows.
 158
 159
 160 \membersection{wxComboBox::CanRedo}\label{wxcomboboxcanredo}
 161
 162 \constfunc{bool}{CanRedo}{\void}
 163
 164 Returns true if the combobox is editable and the last undo can be redone.
 165 Only available on Windows.
 166
 167
 168 \membersection{wxComboBox::CanUndo}\label{wxcomboboxcanundo}
 169
 170 \constfunc{bool}{CanUndo}{\void}
 171
 172 Returns true if the combobox is editable and the last edit can be undone.
 173 Only available on Windows.
 174
 175
 176 \membersection{wxComboBox::Copy}\label{wxcomboboxcopy}
 177
 178 \func{void}{Copy}{\void}
 179
 180 Copies the selected text to the clipboard.
 181
 182
 183 \membersection{wxComboBox::Cut}\label{wxcomboboxcut}
 184
 185 \func{void}{Cut}{\void}
 186
 187 Copies the selected text to the clipboard and removes the selection.
 188
 189
 190 \membersection{wxComboBox::GetInsertionPoint}\label{wxcomboboxgetinsertionpoint}
 191
 192 \constfunc{long}{GetInsertionPoint}{\void}
 193
 194 Returns the insertion point for the combobox's text field.
 195
 196 \textbf{Note:} Under wxMSW, this function always returns $0$ if the combobox
 197 doesn't have the focus.
 198
 199
 200 \membersection{wxComboBox::GetLastPosition}\label{wxcomboboxgetlastposition}
 201
 202 \constfunc{virtual wxTextPos}{GetLastPosition}{\void}
 203
 204 Returns the last position in the combobox text field.
 205
 206
 207 \membersection{wxComboBox::GetValue}\label{wxcomboboxgetvalue}
 208
 209 \constfunc{wxString}{GetValue}{\void}
 210
 211 Returns the current value in the combobox text field.
 212
 213
 214 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 215
 216 \func{void}{Paste}{\void}
 217
 218 Pastes text from the clipboard to the text field.
 219
 220
 221 \membersection{wxComboBox::Redo}\label{wxcomboboxredo}
 222
 223 \func{void}{Redo}{\void}
 224
 225 Redoes the last undo in the text field. Windows only.
 226
 227
 228 \membersection{wxComboBox::Replace}\label{wxcomboboxreplace}
 229
 230 \func{void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{text}}
 231
 232 Replaces the text between two positions with the given text, in the combobox text field.
 233
 234 \wxheading{Parameters}
 235
 236 \docparam{from}{The first position.}
 237
 238 \docparam{to}{The second position.}
 239
 240 \docparam{text}{The text to insert.}
 241
 242
 243 \membersection{wxComboBox::Remove}\label{wxcomboboxremove}
 244
 245 \func{void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 246
 247 Removes the text between the two positions in the combobox text field.
 248
 249 \wxheading{Parameters}
 250
 251 \docparam{from}{The first position.}
 252
 253 \docparam{to}{The last position.}
 254
 255
 256 \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint}
 257
 258 \func{void}{SetInsertionPoint}{\param{long}{ pos}}
 259
 260 Sets the insertion point in the combobox text field.
 261
 262 \wxheading{Parameters}
 263
 264 \docparam{pos}{The new insertion point.}
 265
 266
 267 \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend}
 268
 269 \func{void}{SetInsertionPointEnd}{\void}
 270
 271 Sets the insertion point at the end of the combobox text field.
 272
 273
 274 \membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}
 275
 276 \func{void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 277
 278 Selects the text between the two positions, in the combobox text field.
 279
 280 \wxheading{Parameters}
 281
 282 \docparam{from}{The first position.}
 283
 284 \docparam{to}{The second position.}
 285
 286 \pythonnote{This method is called {\tt SetMark} in wxPython, {\tt SetSelection}
 287 name is kept for
 288 \helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}.}
 289
 290
 291 \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue}
 292
 293 \func{void}{SetValue}{\param{const wxString\& }{text}}
 294
 295 Sets the text for the combobox text field.
 296
 297 {\bf NB:} For a combobox with {\tt wxCB\_READONLY} style the string must be in
 298 the combobox choices list, otherwise the call to SetValue() is ignored.
 299
 300 \wxheading{Parameters}
 301
 302 \docparam{text}{The text to set.}
 303
 304
 305 \membersection{wxComboBox::Undo}\label{wxcomboboxundo}
 306
 307 \func{void}{Undo}{\void}
 308
 309 Undoes the last edit in the text field. Windows only.
 310