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