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