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