Navigation

Phoenix Logo

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 (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls).

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. Also note that only wxMSW and OSX/Cocoa support adding or deleting items in this event.

See also

wx.ListBox, wx.TextCtrl, wx.Choice, wx.CommandEvent


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

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.

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

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.

Notice that this method will generate a wxEVT_TEXT event, use wx.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