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::GetValue}\label{wxcomboboxgetvalue}
 222
 223 \constfunc{wxString}{GetValue}{\void}
 224
 225 Returns the current value in the combobox text field.
 226
 227
 228 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 229
 230 \func{void}{Paste}{\void}
 231
 232 Pastes text from the clipboard to the text field.
 233
 234
 235 \membersection{wxComboBox::Redo}\label{wxcomboboxredo}
 236
 237 \func{void}{Redo}{\void}
 238
 239 Redoes the last undo in the text field. Windows only.
 240
 241
 242 \membersection{wxComboBox::Replace}\label{wxcomboboxreplace}
 243
 244 \func{void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{text}}
 245
 246 Replaces the text between two positions with the given text, in the combobox text field.
 247
 248 \wxheading{Parameters}
 249
 250 \docparam{from}{The first position.}
 251
 252 \docparam{to}{The second position.}
 253
 254 \docparam{text}{The text to insert.}
 255
 256
 257 \membersection{wxComboBox::Remove}\label{wxcomboboxremove}
 258
 259 \func{void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 260
 261 Removes the text between the two positions in the combobox text field.
 262
 263 \wxheading{Parameters}
 264
 265 \docparam{from}{The first position.}
 266
 267 \docparam{to}{The last position.}
 268
 269
 270 \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint}
 271
 272 \func{void}{SetInsertionPoint}{\param{long}{ pos}}
 273
 274 Sets the insertion point in the combobox text field.
 275
 276 \wxheading{Parameters}
 277
 278 \docparam{pos}{The new insertion point.}
 279
 280
 281 \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend}
 282
 283 \func{void}{SetInsertionPointEnd}{\void}
 284
 285 Sets the insertion point at the end of the combobox text field.
 286
 287
 288 \membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}
 289
 290 \func{void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 291
 292 Selects the text between the two positions, in the combobox text field.
 293
 294 \wxheading{Parameters}
 295
 296 \docparam{from}{The first position.}
 297
 298 \docparam{to}{The second position.}
 299
 300 \pythonnote{This method is called {\tt SetMark} in wxPython, {\tt SetSelection}
 301 name is kept for
 302 \helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}.}
 303
 304
 305 \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue}
 306
 307 \func{void}{SetValue}{\param{const wxString\& }{text}}
 308
 309 Sets the text for the combobox text field.
 310
 311 {\bf NB:} For a combobox with {\tt wxCB\_READONLY} style the string must be in
 312 the combobox choices list, otherwise the call to SetValue() is ignored.
 313
 314 \wxheading{Parameters}
 315
 316 \docparam{text}{The text to set.}
 317
 318
 319 \membersection{wxComboBox::Undo}\label{wxcomboboxundo}
 320
 321 \func{void}{Undo}{\void}
 322
 323 Undoes the last edit in the text field. Windows only.
 324