# wxComboBox Class Reference
[Controls]

`#include </home/work/projects/wx/2.9/wx/interface/wx/combobox.h>`

Inheritance diagram for wxComboBox:
[legend]

## Detailed Description

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 wxCB_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 wxComboCtrl, wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.

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

## Styles

This class supports the following styles:

- wxCB_SIMPLE:
  Creates a combobox with a permanently displayed list. Windows only.
- wxCB_DROPDOWN:
  Creates a combobox with a drop-down list. MSW and Motif only.
- wxCB_READONLY:
  A combobox with this style behaves like a wxChoice (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.
- wxCB_SORT:
  Sorts the entries in the list alphabetically.
- wxTE_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

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCommandEvent& event)

Event macros for events emitted by this class:

- EVT_COMBOBOX(id, func):
  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(id, func):
  Process a `wxEVT_COMMAND_TEXT_UPDATED` event, when the combobox text changes.
- EVT_TEXT_ENTER(id, func):
  Process a `wxEVT_COMMAND_TEXT_ENTER` event, when RETURN is pressed in the combobox (notice that the combobox must have been created with wxTE_PROCESS_ENTER style to receive this event).
- EVT_COMBOBOX_DROPDOWN(id, func):
  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(id, func):
  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.

##

Library: wxCore
Category: Controls
Appearance:

wxMSW appearance | wxGTK appearance | wxMac appearance

See also:
  wxListBox, wxTextCtrl, wxChoice, wxCommandEvent

## Public Member Functions

| wxComboBox ()
| Default constructor.
| wxComboBox (wxWindow *parent, wxWindowID id, const wxString &value=wxEmptyString, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, int n=0, const wxString choices[]=NULL, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxComboBoxNameStr)
| Constructor, creating and showing a combobox.
| wxComboBox (wxWindow *parent, wxWindowID id, const wxString &value, const wxPoint &pos, const wxSize &size, const wxArrayString &choices, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxComboBoxNameStr)
| Constructor, creating and showing a combobox.
virtual | ~wxComboBox ()
| Destructor, destroying the combobox.
virtual int | GetCurrentSelection () const
| Returns the item being selected right now.
virtual long | GetInsertionPoint () const
| Same as wxTextEntry::GetInsertionPoint().
virtual void | SetSelection (long from, long to)
| Same as wxTextEntry::SetSelection().
virtual void | SetValue (const wxString &text)
| Sets the text for the combobox text field.
virtual void | Popup ()
| Shows the list box portion of the combo box.
virtual void | Dismiss ()
| Hides the list box portion of the combo box.
bool | Create (wxWindow *parent, wxWindowID id, const wxString &value=wxEmptyString, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, int n=0, const wxString choices[]=(const wxString *) NULL, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxComboBoxNameStr)
| Creates the combobox for two-step construction.
bool | Create (wxWindow *parent, wxWindowID id, const wxString &value, const wxPoint &pos, const wxSize &size, const wxArrayString &choices, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxComboBoxNameStr)
| Creates the combobox for two-step construction.

List of all members.

## Constructor & Destructor Documentation

wxComboBox::wxComboBox | ( |  | ) |

Default constructor.

wxComboBox::wxComboBox | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxString & | value = `wxEmptyString`,
|  | const wxPoint & | pos = `wxDefaultPosition`,
|  | const wxSize & | size = `wxDefaultSize`,
|  | int | n = `0`,
|  | const wxString | choices[] = `NULL`,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxComboBoxNameStr` |
| ) |  |  |

Constructor, creating and showing a combobox.

Parameters:

  | parent | Parent window. Must not be NULL.
  | id | Window identifier. The value wxID_ANY indicates a default value.
  | value | Initial selection string. An empty string indicates no selection. Notice that for the controls with `wxCB_READONLY` style this string must be one of the valid choices if it is not empty.
  | pos | Window position. If wxDefaultPosition is specified then a default position is chosen.
  | size | Window size. If wxDefaultSize is specified then the window is sized appropriately.
  | n | Number of strings with which to initialise the control.
  | choices | An array of strings with which to initialise the control.
  | style | Window style. See wxComboBox.
  | validator | Window validator.
  | name | Window name.

wxPython Note: The wxComboBox constructor in wxPython reduces the n and choices arguments are to a single argument, which is a list of strings.

wxPerl Note: Not supported by wxPerl.

See also:
  Create(), wxValidator

wxComboBox::wxComboBox | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxString & | value,
|  | const wxPoint & | pos,
|  | const wxSize & | size,
|  | const wxArrayString & | choices,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxComboBoxNameStr` |
| ) |  |  |

Constructor, creating and showing a combobox.

Parameters:

  | parent | Parent window. Must not be NULL.
  | id | Window identifier. The value wxID_ANY indicates a default value.
  | value | Initial selection string. An empty string indicates no selection.
  | pos | Window position.
  | size | Window size. If wxDefaultSize is specified then the window is sized appropriately.
  | choices | An array of strings with which to initialise the control.
  | style | Window style. See wxComboBox.
  | validator | Window validator.
  | name | Window name.

wxPython Note: The wxComboBox constructor in wxPython reduces the n and choices arguments are to a single argument, which is a list of strings.

wxPerl Note: Use an array reference for the choices parameter.

See also:
  Create(), wxValidator

virtual wxComboBox::~wxComboBox | ( |  | ) | `[virtual]`

Destructor, destroying the combobox.

## Member Function Documentation

bool wxComboBox::Create | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxString & | value = `wxEmptyString`,
|  | const wxPoint & | pos = `wxDefaultPosition`,
|  | const wxSize & | size = `wxDefaultSize`,
|  | int | n = `0`,
|  | const wxString | choices[] = `(const wxString *) NULL`,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxComboBoxNameStr` |
| ) |  |  |

Creates the combobox for two-step construction.

Derived classes should call or replace this function. See wxComboBox() for further details.

Reimplemented in wxBitmapComboBox.

bool wxComboBox::Create | ( | wxWindow * | parent,
|  | wxWindowID | id,
|  | const wxString & | value,
|  | const wxPoint & | pos,
|  | const wxSize & | size,
|  | const wxArrayString & | choices,
|  | long | style = `0`,
|  | const wxValidator & | validator = `wxDefaultValidator`,
|  | const wxString & | name = `wxComboBoxNameStr` |
| ) |  |  |

Creates the combobox for two-step construction.

Derived classes should call or replace this function. See wxComboBox() for further details.

Reimplemented in wxBitmapComboBox.

virtual void wxComboBox::Dismiss | ( |  | ) | `[virtual]`

Hides the list box portion of the combo box.

Currently only implemented in wxMSW and wxGTK.

Notice that calling this function will generate a `wxEVT_COMMAND_COMBOBOX_CLOSEUP` event.

Since:
  2.9.1

virtual int wxComboBox::GetCurrentSelection | ( |  | ) | const`[virtual]`

Returns the item being selected right now.

This function does the same things as wxChoice::GetCurrentSelection() and returns the item currently selected in the dropdown list if it's open or the same thing as wxControlWithItems::GetSelection() otherwise.

virtual long wxComboBox::GetInsertionPoint | ( |  | ) | const`[virtual]`

Same as wxTextEntry::GetInsertionPoint().

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

Reimplemented from wxTextEntry.

virtual void wxComboBox::Popup | ( |  | ) | `[virtual]`

Shows the list box portion of the combo box.

Currently only implemented in wxMSW and wxGTK.

Notice that calling this function will generate a `wxEVT_COMMAND_COMBOBOX_DROPDOWN` event.

Since:
  2.9.1

virtual void wxComboBox::SetSelection | ( | long | from,
|  | long | to |
| ) |  |  | `[virtual]`

Same as wxTextEntry::SetSelection().

wxPython Note: This method is called SetMark() in wxPython, "SetSelection" is kept for wxControlWithItems::SetSelection().

Reimplemented from wxTextEntry.

virtual void wxComboBox::SetValue | ( | const wxString & | text | ) | `[virtual]`

Sets the text for the combobox text field.

Notice that this method will generate a `wxEVT_COMMAND_TEXT_UPDATED` event, use wxTextEntry::ChangeValue() if this is undesirable.

Note:
  For a combobox with `wxCB_READONLY` style the string must be in the combobox choices list, otherwise the call to SetValue() is ignored. This is case insensitive.

Parameters:

  | text | The text to set.

Reimplemented from wxTextEntry.

|  | [ top ]