]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/combobox.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxComboBox
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
12 A combobox is like a combination of an edit control and a listbox.
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
16 field depending on the platform and presence of wxCB_READONLY style.
18 A combobox permits a single selection only. Combobox items are numbered
21 If you need a customized combobox, have a look at wxComboCtrl,
22 wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
24 Please refer to wxTextEntry documentation for the description of methods
25 operating with the text entry part of the combobox and to wxItemContainer
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.
33 Creates a combobox with a permanently displayed list. Windows only.
35 Creates a combobox with a drop-down list. MSW and Motif only.
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.
42 Sorts the entries in the list alphabetically.
43 @style{wxTE_PROCESS_ENTER}
44 The control will generate the event wxEVT_COMMAND_TEXT_ENTER
45 (otherwise pressing Enter key is either processed internally by the
46 control or used for navigation between dialog controls). Windows
50 @beginEventEmissionTable{wxCommandEvent}
51 @event{EVT_COMBOBOX(id, func)}
52 Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
53 the list is selected. Note that calling GetValue() returns the new
55 @event{EVT_TEXT(id, func)}
56 Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
58 @event{EVT_TEXT_ENTER(id, func)}
59 Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
60 the combobox (notice that the combobox must have been created with
61 wxTE_PROCESS_ENTER style to receive this event).
62 @event{EVT_COMBOBOX_DROPDOWN(id, func)}
63 Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
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.
67 @event{EVT_COMBOBOX_CLOSEUP(id, func)}
68 Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
69 when the list box of the combo box disappears (closes up). This
70 event is only generated for the same platforms as
71 wxEVT_COMMAND_COMBOBOX_DROPDOWN above. Also note that only wxMSW
72 supports adding or deleting items in this event.
77 @appearance{combobox.png}
79 @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
81 class wxComboBox
: public wxControl
,
82 public wxItemContainer
,
92 Constructor, creating and showing a combobox.
95 Parent window. Must not be @NULL.
97 Window identifier. The value wxID_ANY indicates a default value.
99 Initial selection string. An empty string indicates no selection.
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.
104 If ::wxDefaultPosition is specified then a default position is chosen.
107 If ::wxDefaultSize is specified then the window is sized appropriately.
109 Number of strings with which to initialise the control.
111 An array of strings with which to initialise the control.
113 Window style. See wxComboBox.
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.
125 Not supported by wxPerl.
128 @see Create(), wxValidator
130 wxComboBox(wxWindow
* parent
, wxWindowID id
,
131 const wxString
& value
= wxEmptyString
,
132 const wxPoint
& pos
= wxDefaultPosition
,
133 const wxSize
& size
= wxDefaultSize
,
135 const wxString choices
[] = NULL
,
137 const wxValidator
& validator
= wxDefaultValidator
,
138 const wxString
& name
= wxComboBoxNameStr
);
140 Constructor, creating and showing a combobox.
143 Parent window. Must not be @NULL.
145 Window identifier. The value wxID_ANY indicates a default value.
147 Initial selection string. An empty string indicates no selection.
151 Window size. If wxDefaultSize is specified then the window is sized
154 An array of strings with which to initialise the control.
156 Window style. See wxComboBox.
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.
168 Use an array reference for the @a choices parameter.
171 @see Create(), wxValidator
173 wxComboBox(wxWindow
* parent
, wxWindowID id
,
174 const wxString
& value
,
177 const wxArrayString
& choices
,
179 const wxValidator
& validator
= wxDefaultValidator
,
180 const wxString
& name
= wxComboBoxNameStr
);
183 Destructor, destroying the combobox.
185 virtual ~wxComboBox();
189 Creates the combobox for two-step construction. Derived classes should
190 call or replace this function. See wxComboBox() for further details.
192 bool Create(wxWindow
*parent
, wxWindowID id
,
193 const wxString
& value
= wxEmptyString
,
194 const wxPoint
& pos
= wxDefaultPosition
,
195 const wxSize
& size
= wxDefaultSize
,
196 int n
= 0, const wxString choices
[] = (const wxString
*) NULL
,
198 const wxValidator
& validator
= wxDefaultValidator
,
199 const wxString
& name
= wxComboBoxNameStr
);
200 bool Create(wxWindow
*parent
, wxWindowID id
,
201 const wxString
& value
,
204 const wxArrayString
& choices
,
206 const wxValidator
& validator
= wxDefaultValidator
,
207 const wxString
& name
= wxComboBoxNameStr
);
211 Returns the item being selected right now.
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.
217 virtual int GetCurrentSelection() const;
220 Same as wxTextEntry::GetInsertionPoint().
222 @note Under wxMSW, this function always returns 0 if the combobox
223 doesn't have the focus.
225 virtual long GetInsertionPoint() const;
228 Same as wxTextEntry::SetSelection().
231 This method is called SetMark() in wxPython, "SetSelection" is kept for
232 wxControlWithItems::SetSelection().
235 virtual void SetSelection(long from
, long to
);
238 Sets the text for the combobox text field.
240 Notice that this method will generate a wxEVT_COMMAND_TEXT_UPDATED
241 event, use wxTextEntry::ChangeValue() if this is undesirable.
243 @note For a combobox with @c wxCB_READONLY style the string must be in
244 the combobox choices list, otherwise the call to SetValue() is
245 ignored. This is case insensitive.
250 virtual void SetValue(const wxString
& text
);
253 Shows the list box portion of the combo box.
255 Currently only implemented in wxMSW and wxGTK.
257 Notice that calling this function will generate a
258 wxEVT_COMMAND_COMBOBOX_DROPDOWN event.
262 virtual void Popup();
265 Hides the list box portion of the combo box.
267 Currently only implemented in wxMSW and wxGTK.
269 Notice that calling this function will generate a
270 wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
274 virtual void Dismiss();