]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: combobox.h | |
e54c96f1 | 3 | // Purpose: interface of wxComboBox |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
9 | /** | |
10 | @class wxComboBox | |
7c913512 | 11 | |
2e7789a9 VZ |
12 | A combobox is like a combination of an edit control and a listbox. |
13 | ||
14 | It can be displayed as static list with editable or read-only text field; | |
15 | or a drop-down list with text field; or a drop-down list without a text | |
1db02a5e | 16 | field depending on the platform and presence of wxCB_READONLY style. |
7c913512 | 17 | |
bd0812fe BP |
18 | A combobox permits a single selection only. Combobox items are numbered |
19 | from zero. | |
7c913512 | 20 | |
bd0812fe BP |
21 | If you need a customized combobox, have a look at wxComboCtrl, |
22 | wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox. | |
7c913512 | 23 | |
2e7789a9 | 24 | Please refer to wxTextEntry documentation for the description of methods |
1db02a5e | 25 | operating with the text entry part of the combobox and to wxItemContainer |
32564189 VZ |
26 | for the methods operating with the list of strings. Notice that at least |
27 | under MSW wxComboBox doesn't behave correctly if it contains strings | |
28 | differing in case only so portable programs should avoid adding such | |
29 | strings to this control. | |
2e7789a9 | 30 | |
23324ae1 | 31 | @beginStyleTable |
8c6791e4 | 32 | @style{wxCB_SIMPLE} |
23324ae1 | 33 | Creates a combobox with a permanently displayed list. Windows only. |
8c6791e4 | 34 | @style{wxCB_DROPDOWN} |
1db02a5e | 35 | Creates a combobox with a drop-down list. MSW and Motif only. |
8c6791e4 | 36 | @style{wxCB_READONLY} |
1db02a5e VZ |
37 | A combobox with this style behaves like a wxChoice (and may look in |
38 | the same way as well, although this is platform-dependent), i.e. it | |
39 | allows the user to choose from the list of options but doesn't allow | |
40 | to enter a value not present in the list. | |
8c6791e4 | 41 | @style{wxCB_SORT} |
23324ae1 | 42 | Sorts the entries in the list alphabetically. |
8c6791e4 | 43 | @style{wxTE_PROCESS_ENTER} |
3a194bda | 44 | The control will generate the event @c wxEVT_COMMAND_TEXT_ENTER |
23324ae1 FM |
45 | (otherwise pressing Enter key is either processed internally by the |
46 | control or used for navigation between dialog controls). Windows | |
47 | only. | |
48 | @endStyleTable | |
7c913512 | 49 | |
3051a44a | 50 | @beginEventEmissionTable{wxCommandEvent} |
8c6791e4 | 51 | @event{EVT_COMBOBOX(id, func)} |
3a194bda | 52 | Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on |
bd0812fe | 53 | the list is selected. Note that calling GetValue() returns the new |
23324ae1 | 54 | value of selection. |
8c6791e4 | 55 | @event{EVT_TEXT(id, func)} |
3a194bda | 56 | Process a @c wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text |
23324ae1 | 57 | changes. |
8c6791e4 | 58 | @event{EVT_TEXT_ENTER(id, func)} |
3a194bda | 59 | Process a @c wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in |
23324ae1 FM |
60 | the combobox (notice that the combobox must have been created with |
61 | wxTE_PROCESS_ENTER style to receive this event). | |
23d74d89 | 62 | @event{EVT_COMBOBOX_DROPDOWN(id, func)} |
3a194bda | 63 | Process a @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated |
8933fbc6 VZ |
64 | when the list box part of the combo box is shown (drops down). |
65 | Notice that this event is currently only supported by wxMSW and | |
66 | wxGTK with GTK+ 2.10 or later. | |
23d74d89 | 67 | @event{EVT_COMBOBOX_CLOSEUP(id, func)} |
3a194bda | 68 | Process a @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated |
8933fbc6 VZ |
69 | when the list box of the combo box disappears (closes up). This |
70 | event is only generated for the same platforms as | |
3a194bda | 71 | @c wxEVT_COMMAND_COMBOBOX_DROPDOWN above. Also note that only wxMSW |
bb3400a8 | 72 | supports adding or deleting items in this event. |
23324ae1 | 73 | @endEventTable |
7c913512 | 74 | |
23324ae1 FM |
75 | @library{wxcore} |
76 | @category{ctrl} | |
7e59b885 | 77 | @appearance{combobox.png} |
7c913512 | 78 | |
e54c96f1 | 79 | @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent |
23324ae1 | 80 | */ |
2e7789a9 VZ |
81 | class wxComboBox : public wxControl, |
82 | public wxItemContainer, | |
83 | public wxTextEntry | |
23324ae1 FM |
84 | { |
85 | public: | |
bd0812fe BP |
86 | /** |
87 | Default constructor. | |
88 | */ | |
89 | wxComboBox(); | |
90 | ||
23324ae1 FM |
91 | /** |
92 | Constructor, creating and showing a combobox. | |
3c4f71cc | 93 | |
7c913512 | 94 | @param parent |
4cc4bfaf | 95 | Parent window. Must not be @NULL. |
7c913512 | 96 | @param id |
4cc4bfaf | 97 | Window identifier. The value wxID_ANY indicates a default value. |
7c913512 | 98 | @param value |
4cc4bfaf | 99 | Initial selection string. An empty string indicates no selection. |
a3281dbc VZ |
100 | Notice that for the controls with @c wxCB_READONLY style this |
101 | string must be one of the valid choices if it is not empty. | |
7c913512 | 102 | @param pos |
4cc4bfaf | 103 | Window position. |
dc1b07fd | 104 | If ::wxDefaultPosition is specified then a default position is chosen. |
7c913512 | 105 | @param size |
dc1b07fd FM |
106 | Window size. |
107 | If ::wxDefaultSize is specified then the window is sized appropriately. | |
7c913512 | 108 | @param n |
4cc4bfaf | 109 | Number of strings with which to initialise the control. |
7c913512 | 110 | @param choices |
4cc4bfaf | 111 | An array of strings with which to initialise the control. |
7c913512 | 112 | @param style |
4cc4bfaf | 113 | Window style. See wxComboBox. |
7c913512 | 114 | @param validator |
4cc4bfaf | 115 | Window validator. |
7c913512 | 116 | @param name |
4cc4bfaf | 117 | Window name. |
3c4f71cc | 118 | |
bd0812fe BP |
119 | @beginWxPythonOnly |
120 | The wxComboBox constructor in wxPython reduces the @a n and @a choices | |
121 | arguments are to a single argument, which is a list of strings. | |
122 | @endWxPythonOnly | |
123 | ||
1058f652 MB |
124 | @beginWxPerlOnly |
125 | Not supported by wxPerl. | |
126 | @endWxPerlOnly | |
127 | ||
4cc4bfaf | 128 | @see Create(), wxValidator |
23324ae1 | 129 | */ |
7c913512 | 130 | wxComboBox(wxWindow* parent, wxWindowID id, |
e9c3992c | 131 | const wxString& value = wxEmptyString, |
7c913512 FM |
132 | const wxPoint& pos = wxDefaultPosition, |
133 | const wxSize& size = wxDefaultSize, | |
134 | int n = 0, | |
4cc4bfaf | 135 | const wxString choices[] = NULL, |
7c913512 FM |
136 | long style = 0, |
137 | const wxValidator& validator = wxDefaultValidator, | |
882678eb | 138 | const wxString& name = wxComboBoxNameStr); |
792255cc VZ |
139 | /** |
140 | Constructor, creating and showing a combobox. | |
141 | ||
142 | @param parent | |
143 | Parent window. Must not be @NULL. | |
144 | @param id | |
145 | Window identifier. The value wxID_ANY indicates a default value. | |
146 | @param value | |
147 | Initial selection string. An empty string indicates no selection. | |
148 | @param pos | |
149 | Window position. | |
150 | @param size | |
151 | Window size. If wxDefaultSize is specified then the window is sized | |
152 | appropriately. | |
153 | @param choices | |
154 | An array of strings with which to initialise the control. | |
155 | @param style | |
156 | Window style. See wxComboBox. | |
157 | @param validator | |
158 | Window validator. | |
159 | @param name | |
160 | Window name. | |
161 | ||
162 | @beginWxPythonOnly | |
163 | The wxComboBox constructor in wxPython reduces the @a n and @a choices | |
164 | arguments are to a single argument, which is a list of strings. | |
165 | @endWxPythonOnly | |
166 | ||
1058f652 MB |
167 | @beginWxPerlOnly |
168 | Use an array reference for the @a choices parameter. | |
169 | @endWxPerlOnly | |
170 | ||
792255cc VZ |
171 | @see Create(), wxValidator |
172 | */ | |
7c913512 FM |
173 | wxComboBox(wxWindow* parent, wxWindowID id, |
174 | const wxString& value, | |
175 | const wxPoint& pos, | |
176 | const wxSize& size, | |
177 | const wxArrayString& choices, | |
178 | long style = 0, | |
179 | const wxValidator& validator = wxDefaultValidator, | |
882678eb | 180 | const wxString& name = wxComboBoxNameStr); |
23324ae1 FM |
181 | |
182 | /** | |
183 | Destructor, destroying the combobox. | |
184 | */ | |
b7e94bd7 | 185 | virtual ~wxComboBox(); |
23324ae1 | 186 | |
bd0812fe | 187 | //@{ |
23324ae1 | 188 | /** |
bd0812fe BP |
189 | Creates the combobox for two-step construction. Derived classes should |
190 | call or replace this function. See wxComboBox() for further details. | |
191 | */ | |
57bf907d FM |
192 | bool Create(wxWindow *parent, wxWindowID id, |
193 | const wxString& value = wxEmptyString, | |
bd0812fe BP |
194 | const wxPoint& pos = wxDefaultPosition, |
195 | const wxSize& size = wxDefaultSize, | |
57bf907d | 196 | int n = 0, const wxString choices[] = (const wxString *) NULL, |
bd0812fe BP |
197 | long style = 0, |
198 | const wxValidator& validator = wxDefaultValidator, | |
57bf907d FM |
199 | const wxString& name = wxComboBoxNameStr); |
200 | bool Create(wxWindow *parent, wxWindowID id, | |
bd0812fe BP |
201 | const wxString& value, |
202 | const wxPoint& pos, | |
203 | const wxSize& size, | |
204 | const wxArrayString& choices, | |
205 | long style = 0, | |
206 | const wxValidator& validator = wxDefaultValidator, | |
57bf907d | 207 | const wxString& name = wxComboBoxNameStr); |
bd0812fe BP |
208 | //@} |
209 | ||
210 | /** | |
2e7789a9 | 211 | Returns the item being selected right now. |
23324ae1 | 212 | |
bd0812fe BP |
213 | This function does the same things as wxChoice::GetCurrentSelection() |
214 | and returns the item currently selected in the dropdown list if it's | |
215 | open or the same thing as wxControlWithItems::GetSelection() otherwise. | |
23324ae1 | 216 | */ |
b7e94bd7 | 217 | virtual int GetCurrentSelection() const; |
23324ae1 FM |
218 | |
219 | /** | |
2e7789a9 | 220 | Same as wxTextEntry::GetInsertionPoint(). |
bd0812fe | 221 | |
cdbcf4c2 | 222 | @note Under wxMSW, this function always returns 0 if the combobox |
bd0812fe | 223 | doesn't have the focus. |
23324ae1 | 224 | */ |
0004982c | 225 | virtual long GetInsertionPoint() const; |
23324ae1 | 226 | |
36a96421 VZ |
227 | /** |
228 | IsEmpty() is not available in this class. | |
229 | ||
230 | This method is documented here only to notice that it can't be used | |
231 | with this class because of the ambiguity between the methods with the | |
232 | same name inherited from wxItemContainer and wxTextEntry base classes. | |
233 | ||
234 | Because of this, any attempt to call it results in a compilation error | |
235 | and you should use either IsListEmpty() or IsTextEmpty() depending on | |
236 | what exactly do you want to test. | |
237 | */ | |
238 | bool IsEmpty() const; | |
239 | ||
240 | /** | |
241 | Returns true if the list of combobox choices is empty. | |
242 | ||
243 | Use this method instead of (not available in this class) IsEmpty() to | |
244 | test if the list of items is empty. | |
245 | ||
246 | @since 2.9.3 | |
247 | */ | |
248 | bool IsListEmpty() const; | |
249 | ||
250 | /** | |
251 | Returns true if the text of the combobox is empty. | |
252 | ||
253 | Use this method instead of (not available in this class) IsEmpty() to | |
254 | test if the text currently entered into the combobox is empty. | |
255 | ||
256 | @since 2.9.3 | |
257 | */ | |
258 | bool IsTextEmpty() const; | |
259 | ||
23324ae1 | 260 | /** |
2e7789a9 | 261 | Same as wxTextEntry::SetSelection(). |
bd0812fe BP |
262 | |
263 | @beginWxPythonOnly | |
264 | This method is called SetMark() in wxPython, "SetSelection" is kept for | |
265 | wxControlWithItems::SetSelection(). | |
266 | @endWxPythonOnly | |
23324ae1 | 267 | */ |
b7e94bd7 | 268 | virtual void SetSelection(long from, long to); |
23324ae1 FM |
269 | |
270 | /** | |
271 | Sets the text for the combobox text field. | |
1f1d2182 | 272 | |
3a194bda | 273 | Notice that this method will generate a @c wxEVT_COMMAND_TEXT_UPDATED |
35b9a078 VZ |
274 | event, use wxTextEntry::ChangeValue() if this is undesirable. |
275 | ||
1f1d2182 | 276 | @note For a combobox with @c wxCB_READONLY style the string must be in |
bd0812fe | 277 | the combobox choices list, otherwise the call to SetValue() is |
232fdc63 | 278 | ignored. This is case insensitive. |
3c4f71cc | 279 | |
7c913512 | 280 | @param text |
4cc4bfaf | 281 | The text to set. |
23324ae1 | 282 | */ |
0004982c | 283 | virtual void SetValue(const wxString& text); |
d1d1f817 VZ |
284 | |
285 | /** | |
286 | Shows the list box portion of the combo box. | |
287 | ||
ff8cb900 | 288 | Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa. |
d1d1f817 | 289 | |
73c997ba | 290 | Notice that calling this function will generate a |
ff8cb900 VZ |
291 | @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event except under wxOSX where |
292 | generation of this event is not supported at all. | |
73c997ba | 293 | |
d1d1f817 VZ |
294 | @since 2.9.1 |
295 | */ | |
296 | virtual void Popup(); | |
297 | ||
298 | /** | |
299 | Hides the list box portion of the combo box. | |
300 | ||
ff8cb900 | 301 | Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa. |
d1d1f817 | 302 | |
73c997ba | 303 | Notice that calling this function will generate a |
ff8cb900 VZ |
304 | @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event except under wxOSX where |
305 | generation of this event is not supported at all. | |
73c997ba | 306 | |
d1d1f817 VZ |
307 | @since 2.9.1 |
308 | */ | |
309 | virtual void Dismiss(); | |
ff8cb900 | 310 | |
e9321277 RD |
311 | virtual int GetSelection() const; |
312 | virtual void GetSelection(long *from, long *to) const; | |
313 | virtual void SetSelection(int n); | |
314 | virtual void SetSelection(long from, long to); | |
315 | virtual int FindString(const wxString& s, bool bCase = false) const; | |
316 | virtual wxString GetString(unsigned int n) const; | |
317 | virtual wxString GetStringSelection() const; | |
318 | virtual void SetString(unsigned int n, const wxString& s); | |
319 | ||
320 | virtual unsigned int GetCount() const; | |
23324ae1 | 321 | }; |
e54c96f1 | 322 |