wx.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 wx.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 wx.ComboCtrl, wx.adv.OwnerDrawnComboBox, wx.ComboPopup and the ready-to-use wx.adv.BitmapComboBox.

Please refer to wx.TextEntry documentation for the description of methods operating with the text entry part of the combobox and to wx.ItemContainer for the methods operating with the list of strings. Notice that at least under MSW wx.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:

wx.CB_SIMPLE: Creates a combobox with a permanently displayed list. Windows only.
wx.CB_DROPDOWN: Creates a combobox with a drop-down list. MSW and Motif only.
wx.CB_READONLY: A combobox with this style behaves like a wx.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.
wx.CB_SORT: Sorts the entries in the list alphabetically.
wx.TE_PROCESS_ENTER: The control will generate the event wxEVT_TEXT_ENTER that can be handled by the program. Otherwise, i.e. either if this style not specified at all, or it is used, but there is no event handler for this event or the event handler called wx.Event.Skip to avoid overriding the default handling, pressing Enter key is either processed internally by the control or used to activate the default button of the dialog, if any.

Events Emitted by this Class¶

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

EVT_COMBOBOX: Process a wxEVT_COMBOBOX event, when an item on the list is selected. Note that calling GetValue returns the new value of selection.
EVT_TEXT: Process a wxEVT_TEXT event, when the combobox text changes.
EVT_TEXT_ENTER: Process a wxEVT_TEXT_ENTER event, when RETURN is pressed in the combobox (notice that the combobox must have been created with wx.TE_PROCESS_ENTER style to receive this event).
EVT_COMBOBOX_DROPDOWN: Process a wxEVT_COMBOBOX_DROPDOWN event, which is generated when the list box part of the combo box is shown (drops down). Notice that this event is only supported by wxMSW, wxGTK with GTK+ 2.10 or later, and OSX/Cocoa.
EVT_COMBOBOX_CLOSEUP: Process a wxEVT_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_COMBOBOX_DROPDOWN above.

Class Hierarchy¶

Inheritance diagram for class ComboBox:

Control Appearance¶

Known Subclasses¶

wx.adv.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.
`GetClassDefaultAttributes`
`GetCount`	Returns the number of items in the control.
`GetCurrentSelection`	Returns the item being selected right now.
`GetInsertionPoint`	Same as `wx.TextEntry.GetInsertionPoint` .
`GetSelection`	Returns the index of the selected item or `NOT_FOUND` if no item is selected.
`GetTextSelection`	Gets the current selection span.
`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 `wx.TextEntry.SetSelection` .
`SetString`	Changes the text of the specified combobox item.
`SetTextSelection`	Same as `wx.TextEntry.SetSelection` .
`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 wx.ComboBox(Control, ItemContainer, TextEntry)¶

Possible constructors:

ComboBox() -> None

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

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

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default constructor.

Return type:: None

__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 (wx.Window) – Parent window. Must not be None.
id (wx.WindowID) – Window identifier. The value wx.ID_ANY indicates a default value.
value (string) – Initial selection string. An empty string indicates no selection.
pos (wx.Point) – Window position.
size (wx.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 wx.ComboBox.
validator (wx.Validator) – Window validator.
name (string) – Window name.

Return type:

None

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

Creates the combobox for two-step construction.

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

Parameters:

parent (wx.Window)
id (wx.WindowID)
value (string)
pos (wx.Point)
size (wx.Size)
choices (list of strings)
style (long)
validator (wx.Validator)
name (string)

Return type:

bool

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_COMBOBOX_CLOSEUP event except under wxOSX where generation of this event is not supported at all.

Return type:: None

Added 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 wx.NOT_FOUND if the string was not found.

static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)¶

Parameters:: variant (WindowVariant)
Return type:: wx.VisualAttributes

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 wx.Choice.GetCurrentSelection and returns the item currently selected in the dropdown list if it’s open or the same thing as wx.ControlWithItems.GetSelection otherwise.

Return type:: int

GetInsertionPoint(self)¶

Same as wx.TextEntry.GetInsertionPoint .

Return type:: int

Note

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

GetSelection(self)¶

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

Return type:: int
Returns:: The position of the current selection.

See also

SetSelection , GetStringSelection

GetTextSelection(self)¶

Gets the current selection span.

If the returned values are equal, there was no selection. Please note that the indices returned may be used with the other wx.TextCtrl methods but don’t necessarily represent the correct indices into the string returned by GetValue for multiline controls under Windows (at least,) you should use GetStringSelection to get the selected text.

Return type:: Tuple[int, int]

GetString(self, n)¶

Returns the label of the item with the given index.

The index must be valid, i.e. less than the value returned by GetCount , otherwise an assert is triggered. Notably, this function can’t be called if the control is empty.

Parameters:: n (int) – The zero-based index.
Return type:: str
Returns:: The label of the item.

GetStringSelection(self)¶

Gets the text currently selected in the control.

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

Return type:: str

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

Added 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

Added 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_COMBOBOX_DROPDOWN event except under wxOSX where generation of this event is not supported at all.

Return type:: None

Added in version 2.9.1.

SetSelection(self, *args, **kw)¶

Overloaded Implementations:

SetSelection (self, from_, to_)

Same as wx.TextEntry.SetSelection .

Parameters:

from_ (long)
to_ (long)

Return type:

None

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.
Return type:: None

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)

Return type:

None

SetTextSelection(self, from_, to_)¶

Same as wx.TextEntry.SetSelection .

Parameters:

from_ (long)
to_ (long)

Return type:

None

SetValue(self, text)¶

Sets the text for the combobox text field.

For normal, editable comboboxes with a text entry field calling this method will generate a wxEVT_TEXT event, consistently with wx.TextEntry.SetValue behaviour, use wx.TextEntry.ChangeValue if this is undesirable.

For controls with CB_READONLY style the method behaves somewhat differently: the string must be in the combobox choices list (the check for this is case-insensitive) and wxEVT_TEXT is not generated in this case.