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