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