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::GetInsertionPoint}\label{wxcomboboxgetinsertionpoint}
 195
 196 \constfunc{long}{GetInsertionPoint}{\void}
 197
 198 Returns the insertion point for the combobox's text field.
 199
 200 \textbf{Note:} Under wxMSW, this function always returns $0$ if the combobox
 201 doesn't have the focus.
 202
 203
 204 \membersection{wxComboBox::GetLastPosition}\label{wxcomboboxgetlastposition}
 205
 206 \constfunc{virtual wxTextPos}{GetLastPosition}{\void}
 207
 208 Returns the last position in the combobox text field.
 209
 210
 211 \membersection{wxComboBox::GetValue}\label{wxcomboboxgetvalue}
 212
 213 \constfunc{wxString}{GetValue}{\void}
 214
 215 Returns the current value in the combobox text field.
 216
 217
 218 \membersection{wxComboBox::Paste}\label{wxcomboboxpaste}
 219
 220 \func{void}{Paste}{\void}
 221
 222 Pastes text from the clipboard to the text field.
 223
 224
 225 \membersection{wxComboBox::Redo}\label{wxcomboboxredo}
 226
 227 \func{void}{Redo}{\void}
 228
 229 Redoes the last undo in the text field. Windows only.
 230
 231
 232 \membersection{wxComboBox::Replace}\label{wxcomboboxreplace}
 233
 234 \func{void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{text}}
 235
 236 Replaces the text between two positions with the given text, in the combobox text field.
 237
 238 \wxheading{Parameters}
 239
 240 \docparam{from}{The first position.}
 241
 242 \docparam{to}{The second position.}
 243
 244 \docparam{text}{The text to insert.}
 245
 246
 247 \membersection{wxComboBox::Remove}\label{wxcomboboxremove}
 248
 249 \func{void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 250
 251 Removes the text between the two positions in the combobox text field.
 252
 253 \wxheading{Parameters}
 254
 255 \docparam{from}{The first position.}
 256
 257 \docparam{to}{The last position.}
 258
 259
 260 \membersection{wxComboBox::SetInsertionPoint}\label{wxcomboboxsetinsertionpoint}
 261
 262 \func{void}{SetInsertionPoint}{\param{long}{ pos}}
 263
 264 Sets the insertion point in the combobox text field.
 265
 266 \wxheading{Parameters}
 267
 268 \docparam{pos}{The new insertion point.}
 269
 270
 271 \membersection{wxComboBox::SetInsertionPointEnd}\label{wxcomboboxsetinsertionpointend}
 272
 273 \func{void}{SetInsertionPointEnd}{\void}
 274
 275 Sets the insertion point at the end of the combobox text field.
 276
 277
 278 \membersection{wxComboBox::SetSelection}\label{wxcomboboxsetselection}
 279
 280 \func{void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 281
 282 Selects the text between the two positions, in the combobox text field.
 283
 284 \wxheading{Parameters}
 285
 286 \docparam{from}{The first position.}
 287
 288 \docparam{to}{The second position.}
 289
 290 \pythonnote{This method is called {\tt SetMark} in wxPython, {\tt SetSelection}
 291 name is kept for
 292 \helpref{wxControlWithItems::SetSelection}{wxcontrolwithitemssetselection}.}
 293
 294
 295 \membersection{wxComboBox::SetValue}\label{wxcomboboxsetvalue}
 296
 297 \func{void}{SetValue}{\param{const wxString\& }{text}}
 298
 299 Sets the text for the combobox text field.
 300
 301 {\bf NB:} For a combobox with {\tt wxCB\_READONLY} style the string must be in
 302 the combobox choices list, otherwise the call to SetValue() is ignored.
 303
 304 \wxheading{Parameters}
 305
 306 \docparam{text}{The text to set.}
 307
 308
 309 \membersection{wxComboBox::Undo}\label{wxcomboboxundo}
 310
 311 \func{void}{Undo}{\void}
 312
 313 Undoes the last edit in the text field. Windows only.
 314