interface/wx/combobox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        combobox.h
   3 // Purpose:     interface of wxComboBox
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxComboBox
  11
  12     A combobox is like a combination of an edit control and a listbox.
  13
  14     It can be displayed as static list with editable or read-only text field;
  15     or a drop-down list with text field; or a drop-down list without a text
  16     field.
  17
  18     A combobox permits a single selection only. Combobox items are numbered
  19     from zero.
  20
  21     If you need a customized combobox, have a look at wxComboCtrl,
  22     wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
  23
  24     Please refer to wxTextEntry documentation for the description of methods
  25     operating with the text entry part of the combobox.
  26
  27     @beginStyleTable
  28     @style{wxCB_SIMPLE}
  29            Creates a combobox with a permanently displayed list. Windows only.
  30     @style{wxCB_DROPDOWN}
  31            Creates a combobox with a drop-down list.
  32     @style{wxCB_READONLY}
  33            Same as wxCB_DROPDOWN but only the strings specified as the combobox
  34            choices can be selected, it is impossible to select (even from a
  35            program) a string which is not in the choices list.
  36     @style{wxCB_SORT}
  37            Sorts the entries in the list alphabetically.
  38     @style{wxTE_PROCESS_ENTER}
  39            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
  40            (otherwise pressing Enter key is either processed internally by the
  41            control or used for navigation between dialog controls). Windows
  42            only.
  43     @endStyleTable
  44
  45     @beginEventEmissionTable{wxCommandEvent}
  46     @event{EVT_COMBOBOX(id, func)}
  47            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  48            the list is selected. Note that calling GetValue() returns the new
  49            value of selection.
  50     @event{EVT_TEXT(id, func)}
  51            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
  52            changes.
  53     @event{EVT_TEXT_ENTER(id, func)}
  54            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
  55            the combobox (notice that the combobox must have been created with
  56            wxTE_PROCESS_ENTER style to receive this event).
  57     @event{EVT_COMBOX_DROPDOWN(id, func)}
  58            Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
  59            when the list box part of the combo box is shown (drops down).
  60            Notice that this event is currently only supported by wxMSW and
  61            wxGTK with GTK+ 2.10 or later.
  62     @event{EVT_COMBOX_CLOSEUP(id, func)}
  63            Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
  64            when the list box of the combo box disappears (closes up). This
  65            event is only generated for the same platforms as
  66            wxEVT_COMMAND_COMBOBOX_DROPDOWN above.
  67     @endEventTable
  68
  69     @library{wxcore}
  70     @category{ctrl}
  71     @appearance{combobox.png}
  72
  73     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  74 */
  75 class wxComboBox : public wxControl,
  76                    public wxItemContainer,
  77                    public wxTextEntry
  78 {
  79 public:
  80     /**
  81         Default constructor.
  82     */
  83     wxComboBox();
  84
  85     //@{
  86     /**
  87         Constructor, creating and showing a combobox.
  88
  89         @param parent
  90             Parent window. Must not be @NULL.
  91         @param id
  92             Window identifier. The value wxID_ANY indicates a default value.
  93         @param value
  94             Initial selection string. An empty string indicates no selection.
  95             Notice that for the controls with @c wxCB_READONLY style this
  96             string must be one of the valid choices if it is not empty.
  97         @param pos
  98             Window position.
  99             If ::wxDefaultPosition is specified then a default position is chosen.
 100         @param size
 101             Window size.
 102             If ::wxDefaultSize is specified then the window is sized appropriately.
 103         @param n
 104             Number of strings with which to initialise the control.
 105         @param choices
 106             An array of strings with which to initialise the control.
 107         @param style
 108             Window style. See wxComboBox.
 109         @param validator
 110             Window validator.
 111         @param name
 112             Window name.
 113
 114         @beginWxPythonOnly
 115         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 116         arguments are to a single argument, which is a list of strings.
 117         @endWxPythonOnly
 118
 119         @see Create(), wxValidator
 120     */
 121     wxComboBox(wxWindow* parent, wxWindowID id,
 122                const wxString& value = wxEmptyString,
 123                const wxPoint& pos = wxDefaultPosition,
 124                const wxSize& size = wxDefaultSize,
 125                int n = 0,
 126                const wxString choices[] = NULL,
 127                long style = 0,
 128                const wxValidator& validator = wxDefaultValidator,
 129                const wxString& name = wxComboBoxNameStr);
 130     /**
 131         Constructor, creating and showing a combobox.
 132
 133         @param parent
 134             Parent window. Must not be @NULL.
 135         @param id
 136             Window identifier. The value wxID_ANY indicates a default value.
 137         @param value
 138             Initial selection string. An empty string indicates no selection.
 139         @param pos
 140             Window position.
 141         @param size
 142             Window size. If wxDefaultSize is specified then the window is sized
 143             appropriately.
 144         @param choices
 145             An array of strings with which to initialise the control.
 146         @param style
 147             Window style. See wxComboBox.
 148         @param validator
 149             Window validator.
 150         @param name
 151             Window name.
 152
 153         @beginWxPythonOnly
 154         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 155         arguments are to a single argument, which is a list of strings.
 156         @endWxPythonOnly
 157
 158         @see Create(), wxValidator
 159     */
 160     wxComboBox(wxWindow* parent, wxWindowID id,
 161                const wxString& value,
 162                const wxPoint& pos,
 163                const wxSize& size,
 164                const wxArrayString& choices,
 165                long style = 0,
 166                const wxValidator& validator = wxDefaultValidator,
 167                const wxString& name = wxComboBoxNameStr);
 168     //@}
 169
 170     /**
 171         Destructor, destroying the combobox.
 172     */
 173     virtual ~wxComboBox();
 174
 175     //@{
 176     /**
 177         Creates the combobox for two-step construction. Derived classes should
 178         call or replace this function. See wxComboBox() for further details.
 179     */
 180     bool Create(wxWindow *parent, wxWindowID id,
 181                 const wxString& value = wxEmptyString,
 182                 const wxPoint& pos = wxDefaultPosition,
 183                 const wxSize& size = wxDefaultSize,
 184                 int n = 0, const wxString choices[] = (const wxString *) NULL,
 185                 long style = 0,
 186                 const wxValidator& validator = wxDefaultValidator,
 187                 const wxString& name = wxComboBoxNameStr);
 188     bool Create(wxWindow *parent, wxWindowID id,
 189                 const wxString& value,
 190                 const wxPoint& pos,
 191                 const wxSize& size,
 192                 const wxArrayString& choices,
 193                 long style = 0,
 194                 const wxValidator& validator = wxDefaultValidator,
 195                 const wxString& name = wxComboBoxNameStr);
 196     //@}
 197
 198     /**
 199         Returns the item being selected right now.
 200
 201         This function does the same things as wxChoice::GetCurrentSelection()
 202         and returns the item currently selected in the dropdown list if it's
 203         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 204     */
 205     virtual int GetCurrentSelection() const;
 206
 207     /**
 208         Same as wxTextEntry::GetInsertionPoint().
 209
 210         @note Under wxMSW, this function always returns 0 if the combobox
 211               doesn't have the focus.
 212     */
 213     virtual long GetInsertionPoint() const;
 214
 215     /**
 216         Same as wxTextEntry::SetSelection().
 217
 218         @beginWxPythonOnly
 219         This method is called SetMark() in wxPython, "SetSelection" is kept for
 220         wxControlWithItems::SetSelection().
 221         @endWxPythonOnly
 222     */
 223     virtual void SetSelection(long from, long to);
 224
 225     /**
 226         Sets the text for the combobox text field.
 227
 228         Notice that this method will generate a wxEVT_COMMAND_TEXT_UPDATED
 229         event, use wxTextEntry::ChangeValue() if this is undesirable.
 230
 231         @note For a combobox with @c wxCB_READONLY style the string must be in
 232               the combobox choices list, otherwise the call to SetValue() is
 233               ignored.
 234
 235         @param text
 236             The text to set.
 237     */
 238     virtual void SetValue(const wxString& text);
 239 };
 240