1 \section{\class{wxComboBox
}}\label{wxcombobox
}
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.
7 A combobox permits a single selection only. Combobox items are numbered from zero.
9 \wxheading{Derived from
}
11 \helpref{wxControlWithItems
}{wxcontrolwithitems
}\\
12 \helpref{wxControl
}{wxcontrol
}\\
13 \helpref{wxWindow
}{wxwindow
}\\
14 \helpref{wxEvtHandler
}{wxevthandler
}\\
15 \helpref{wxObject
}{wxobject
}
17 \wxheading{Include files
}
21 \wxheading{Window styles
}
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.
}
39 See also
\helpref{window styles overview
}{windowstyles
}.
41 \wxheading{Event handling
}
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.
}
56 \helpref{wxListBox
}{wxlistbox
},
\helpref{wxTextCtrl
}{wxtextctrl
},
\helpref{wxChoice
}{wxchoice
},
57 \rtfsp\helpref{wxCommandEvent
}{wxcommandevent
}
59 \latexignore{\rtfignore{\wxheading{Members
}}}
62 \membersection{wxComboBox::wxComboBox
}\label{wxcomboboxctor
}
64 \func{}{wxComboBox
}{\void}
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"
}}
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"
}}
78 Constructor, creating and showing a combobox.
80 \wxheading{Parameters
}
82 \docparam{parent
}{Parent window. Must not be NULL.
}
84 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
86 \docparam{value
}{Initial selection string. An empty string indicates no selection.
}
88 \docparam{pos
}{Window position.
}
90 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
93 \docparam{n
}{Number of strings with which to initialise the control.
}
95 \docparam{choices
}{An array of strings with which to initialise the control.
}
97 \docparam{style
}{Window style. See
\helpref{wxComboBox
}{wxcombobox
}.
}
99 \docparam{validator
}{Window validator.
}
101 \docparam{name
}{Window name.
}
105 \helpref{wxComboBox::Create
}{wxcomboboxcreate
},
\helpref{wxValidator
}{wxvalidator
}
107 \pythonnote{The wxComboBox constructor in wxPython reduces the
{\tt n
}
108 and
{\tt choices
} arguments are to a single argument, which is
111 \perlnote{In wxPerl there is just an array reference in place of
{\tt n
}
115 \membersection{wxComboBox::
\destruct{wxComboBox
}}\label{wxcomboboxdtor
}
117 \func{}{\destruct{wxComboBox
}}{\void}
119 Destructor, destroying the combobox.
122 \membersection{wxComboBox::Create
}\label{wxcomboboxcreate
}
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"
}}
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"
}}
134 Creates the combobox for two-step construction. Derived classes
135 should call or replace this function. See
\helpref{wxComboBox::wxComboBox
}{wxcomboboxctor
}\rtfsp
139 \membersection{wxComboBox::CanCopy
}\label{wxcomboboxcancopy
}
141 \constfunc{bool
}{CanCopy
}{\void}
143 Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
144 Only available on Windows.
147 \membersection{wxComboBox::CanCut
}\label{wxcomboboxcancut
}
149 \constfunc{bool
}{CanCut
}{\void}
151 Returns true if the combobox is editable and there is a text selection to copy to the clipboard.
152 Only available on Windows.
155 \membersection{wxComboBox::CanPaste
}\label{wxcomboboxcanpaste
}
157 \constfunc{bool
}{CanPaste
}{\void}
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.
163 \membersection{wxComboBox::CanRedo
}\label{wxcomboboxcanredo
}
165 \constfunc{bool
}{CanRedo
}{\void}
167 Returns true if the combobox is editable and the last undo can be redone.
168 Only available on Windows.
171 \membersection{wxComboBox::CanUndo
}\label{wxcomboboxcanundo
}
173 \constfunc{bool
}{CanUndo
}{\void}
175 Returns true if the combobox is editable and the last edit can be undone.
176 Only available on Windows.
179 \membersection{wxComboBox::Copy
}\label{wxcomboboxcopy
}
181 \func{void
}{Copy
}{\void}
183 Copies the selected text to the clipboard.
186 \membersection{wxComboBox::Cut
}\label{wxcomboboxcut
}
188 \func{void
}{Cut
}{\void}
190 Copies the selected text to the clipboard and removes the selection.
193 \membersection{wxComboBox::GetInsertionPoint
}\label{wxcomboboxgetinsertionpoint
}
195 \constfunc{long
}{GetInsertionPoint
}{\void}
197 Returns the insertion point for the combobox's text field.
199 \textbf{Note:
} Under wxMSW, this function always returns $
0$ if the combobox
200 doesn't have the focus.
203 \membersection{wxComboBox::GetLastPosition
}\label{wxcomboboxgetlastposition
}
205 \constfunc{virtual wxTextPos
}{GetLastPosition
}{\void}
207 Returns the last position in the combobox text field.
210 \membersection{wxComboBox::GetValue
}\label{wxcomboboxgetvalue
}
212 \constfunc{wxString
}{GetValue
}{\void}
214 Returns the current value in the combobox text field.
217 \membersection{wxComboBox::Paste
}\label{wxcomboboxpaste
}
219 \func{void
}{Paste
}{\void}
221 Pastes text from the clipboard to the text field.
224 \membersection{wxComboBox::Redo
}\label{wxcomboboxredo
}
226 \func{void
}{Redo
}{\void}
228 Redoes the last undo in the text field. Windows only.
231 \membersection{wxComboBox::Replace
}\label{wxcomboboxreplace
}
233 \func{void
}{Replace
}{\param{long
}{ from
},
\param{long
}{ to
},
\param{const wxString\&
}{text
}}
235 Replaces the text between two positions with the given text, in the combobox text field.
237 \wxheading{Parameters
}
239 \docparam{from
}{The first position.
}
241 \docparam{to
}{The second position.
}
243 \docparam{text
}{The text to insert.
}
246 \membersection{wxComboBox::Remove
}\label{wxcomboboxremove
}
248 \func{void
}{Remove
}{\param{long
}{ from
},
\param{long
}{ to
}}
250 Removes the text between the two positions in the combobox text field.
252 \wxheading{Parameters
}
254 \docparam{from
}{The first position.
}
256 \docparam{to
}{The last position.
}
259 \membersection{wxComboBox::SetInsertionPoint
}\label{wxcomboboxsetinsertionpoint
}
261 \func{void
}{SetInsertionPoint
}{\param{long
}{ pos
}}
263 Sets the insertion point in the combobox text field.
265 \wxheading{Parameters
}
267 \docparam{pos
}{The new insertion point.
}
270 \membersection{wxComboBox::SetInsertionPointEnd
}\label{wxcomboboxsetinsertionpointend
}
272 \func{void
}{SetInsertionPointEnd
}{\void}
274 Sets the insertion point at the end of the combobox text field.
277 \membersection{wxComboBox::SetSelection
}\label{wxcomboboxsetselection
}
279 \func{void
}{SetSelection
}{\param{long
}{ from
},
\param{long
}{ to
}}
281 Selects the text between the two positions, in the combobox text field.
283 \wxheading{Parameters
}
285 \docparam{from
}{The first position.
}
287 \docparam{to
}{The second position.
}
289 \pythonnote{This method is called
{\tt SetMark
} in wxPython,
{\tt SetSelection
}
291 \helpref{wxControlWithItems::SetSelection
}{wxcontrolwithitemssetselection
}.
}
294 \membersection{wxComboBox::SetValue
}\label{wxcomboboxsetvalue
}
296 \func{void
}{SetValue
}{\param{const wxString\&
}{text
}}
298 Sets the text for the combobox text field.
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.
303 \wxheading{Parameters
}
305 \docparam{text
}{The text to set.
}
308 \membersection{wxComboBox::Undo
}\label{wxcomboboxundo
}
310 \func{void
}{Undo
}{\void}
312 Undoes the last edit in the text field. Windows only.