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