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