phoenix_title 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.

styles 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 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 Class Hierarchy

Inheritance diagram for class ComboBox:

appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


sub_classes Known Subclasses

wx.adv.BitmapComboBox


method_summary 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.


api Class API

class wx.ComboBox(Control, ItemContainer, TextEntry)

Possible constructors:

ComboBox()

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

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


Methods

__init__(self, *args, **kw)

overload 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 (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.





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.

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 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

long

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.

Note

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



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



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_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)

overload Overloaded Implementations:



SetSelection (self, from_, to_)

Same as wx.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) –



SetTextSelection(self, from_, to_)

Same as wx.TextEntry.SetSelection .

Parameters
  • from_ (long) –

  • to_ (long) –



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.

Parameters

text (string) – The text to set.


Properties

Count

See GetCount



CurrentSelection

See GetCurrentSelection



InsertionPoint

See GetInsertionPoint



Selection

See GetSelection and SetSelection



StringSelection

See GetStringSelection