ComboBox

A combobox is like a combination of an edit control and a listbox.

It can be displayed as static list with editable or read-only text field; or a drop-down list with text field; or a drop-down list without a text field depending on the platform and presence of CB_READONLY style.

A combobox permits a single selection only. Combobox items are numbered from zero.

If you need a customized combobox, have a look at ComboCtrl, OwnerDrawnComboBox, ComboPopup and the ready-to-use BitmapComboBox.

Please refer to TextEntry documentation for the description of methods operating with the text entry part of the combobox and to ItemContainer for the methods operating with the list of strings. Notice that at least under MSW ComboBox doesn’t behave correctly if it contains strings differing in case only so portable programs should avoid adding such strings to this control.

Window Styles

This class supports the following styles:

• CB_SIMPLE: Creates a combobox with a permanently displayed list. Windows only.
• CB_DROPDOWN: Creates a combobox with a drop-down list. MSW and Motif only.
• CB_READONLY: A combobox with this style behaves like a Choice (and may look in the same way as well, although this is platform-dependent), i.e. it allows the user to choose from the list of options but doesn’t allow to enter a value not present in the list.
• CB_SORT: Sorts the entries in the list alphabetically.
• TE_PROCESS_ENTER: The control will generate the event wxEVT_COMMAND_TEXT_ENTER (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls). Windows only.

Events Emitted by this Class

Handlers bound for the following event types will receive a CommandEvent parameter.

• EVT_COMBOBOX: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on the list is selected. Note that calling GetValue returns the new value of selection.
• EVT_TEXT: Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.
• EVT_TEXT_ENTER: Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in the combobox (notice that the combobox must have been created with TE_PROCESS_ENTER style to receive this event).
• EVT_COMBOBOX_DROPDOWN: Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated when the list box part of the combo box is shown (drops down). Notice that this event is currently only supported by wxMSW and wxGTK with GTK+ 2.10 or later.
• EVT_COMBOBOX_CLOSEUP: Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated when the list box of the combo box disappears (closes up). This event is only generated for the same platforms as wxEVT_COMMAND_COMBOBOX_DROPDOWN above. Also note that only wxMSW supports adding or deleting items in this event.

See also

ListBox, TextCtrl, Choice, CommandEvent

Inheritance Diagram

Inheritance diagram for class ComboBox

Control Appearance

wxMSW

wxMAC

wxGTK

Known Subclasses

BitmapComboBox

Methods Summary

__init__	Default constructor.
Create	Creates the combobox for two-step construction.
Dismiss	Hides the list box portion of the combo box.
FindString	Finds an item whose label matches the given string.
GetCount	Returns the number of items in the control.
GetCurrentSelection	Returns the item being selected right now.
GetInsertionPoint	Same as TextEntry.GetInsertionPoint .
GetSelection	Returns the index of the selected item or NOT_FOUND if no item is selected.
GetString	Returns the label of the item with the given index.
GetStringSelection	Gets the text currently selected in the control.
IsListEmpty	Returns True if the list of combobox choices is empty.
IsTextEmpty	Returns True if the text of the combobox is empty.
Popup	Shows the list box portion of the combo box.
SetSelection	Same as TextEntry.SetSelection .
SetString	Changes the text of the specified combobox item.
SetValue	Sets the text for the combobox text field.

Properties Summary

Count	See GetCount
CurrentSelection	See GetCurrentSelection
InsertionPoint	See GetInsertionPoint
Selection	See GetSelection and SetSelection
StringSelection	See GetStringSelection

Class API

---

class ComboBox(Control, ItemContainer, TextEntry)

A combobox is like a combination of an edit control and a listbox.

Possible constructors:

ComboBox()

ComboBox(parent, id=ID_ANY, value='', pos=DefaultPosition,
         size=DefaultSize, choices=[], style=0,
         validator=DefaultValidator, name=ComboBoxNameStr)

Methods

---

__init__(self, *args, **kw)

Overloaded Implementations:

---

__init__ (self)

Default constructor.

---

__init__ (self, parent, id=ID_ANY, value=’‘, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ComboBoxNameStr)

Constructor, creating and showing a combobox.

Parameters:

• parent (Window) – Parent window. Must not be None.
• id (int) – Window identifier. The value ID_ANY indicates a default value.
• value (string) – Initial selection string. An empty string indicates no selection.
• pos (Point) – Window position.
• size (Size) – Window size. If DefaultSize is specified then the window is sized appropriately.
• choices (list of strings) – An array of strings with which to initialise the control.
• style (long) – Window style. See ComboBox.
• validator (Validator) – Window validator.
• name (string) – Window name.

See also

Create , Validator

---

---

Create(self, *args, **kw)

Creates the combobox for two-step construction.

Derived classes should call or replace this function. See ComboBox for further details.

---

Dismiss(self)

Hides the list box portion of the combo box.

Currently this method is implemented in wxMSW, wxGTK and OSX/Cocoa.

Notice that calling this function will generate a wxEVT_COMMAND_COMBOBOX_CLOSEUP event except under wxOSX where generation of this event is not supported at all.

New in version 2.9.1.

---

FindString(self, string, caseSensitive=False)

Finds an item whose label matches the given string.

Parameters:

• string (string) – String to find.
• caseSensitive (bool) – Whether search is case sensitive (default is not).

Return type:

int

Returns:

The zero-based position of the item, or NOT_FOUND if the string was not found.

---

GetCount(self)

Returns the number of items in the control.

Return type:int

See also

IsEmpty

---

GetCurrentSelection(self)

Returns the item being selected right now.

This function does the same things as Choice.GetCurrentSelection and returns the item currently selected in the dropdown list if it’s open or the same thing as ControlWithItems.GetSelection otherwise.

Return type:int

---

GetInsertionPoint(self)

Same as TextEntry.GetInsertionPoint .

Return type:long

Note

Under wxMSW, this function always returns 0 if the combobox doesn’t have the focus.

---

GetSelection(self, *args, **kw)

Returns the index of the selected item or NOT_FOUND if no item is selected.

Returns:The position of the current selection.

Note

This method can be used with single selection list boxes only, you should use ListBox.GetSelections for the list boxes with LB_MULTIPLE style.

See also

SetSelection , GetStringSelection

---

GetString(self, n)

Returns the label of the item with the given index.

Parameters:n (int) – The zero-based index. Return type:string Returns:The label of the item or an empty string if the position was invalid.

---

GetStringSelection(self)

Gets the text currently selected in the control.

If there is no selection, the returned string is empty.

Return type:string

---

IsListEmpty(self)

Returns True if the list of combobox choices is empty.

Use this method instead of (not available in this class) IsEmpty to test if the list of items is empty.

Return type:bool

New in version 2.9.3.

---

IsTextEmpty(self)

Returns True if the text of the combobox is empty.

Use this method instead of (not available in this class) IsEmpty to test if the text currently entered into the combobox is empty.

Return type:bool

New in version 2.9.3.

---

Popup(self)

Shows the list box portion of the combo box.

Currently this method is implemented in wxMSW, wxGTK and OSX/Cocoa.

Notice that calling this function will generate a wxEVT_COMMAND_COMBOBOX_DROPDOWN event except under wxOSX where generation of this event is not supported at all.

New in version 2.9.1.

---

SetSelection(self, *args, **kw)

Overloaded Implementations:

---

SetSelection (self, from, to)

Same as TextEntry.SetSelection .

Parameters:

• from (long) –
• to (long) –

---

SetSelection (self, n)

Sets the selection to the given item n or removes the selection entirely if n == NOT_FOUND .

Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections.

Parameters:n (int) – The string position to select, starting from zero.

See also

SetString , SetStringSelection

---

---

SetString(self, n, text)

Changes the text of the specified combobox item.

Notice that if the item is the currently selected one, i.e. if its text is displayed in the text part of the combobox, then the text is also replaced with the new text.

Parameters:

• n (int) –
• text (string) –

---

SetValue(self, text)

Sets the text for the combobox text field.

Notice that this method will generate a wxEVT_COMMAND_TEXT_UPDATED event, use TextEntry.ChangeValue if this is undesirable.

Parameters:text (string) – The text to set.

Note

For a combobox with CB_READONLY style the string must be in the combobox choices list, otherwise the call to SetValue is ignored. This is case insensitive.

Properties

---

Count

See GetCount

---

CurrentSelection

See GetCurrentSelection

---

InsertionPoint

See GetInsertionPoint

---

Selection

See GetSelection and SetSelection

---

StringSelection

See GetStringSelection