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 licence
   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_COMBOBOX_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_COMBOBOX_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. Also note that only wxMSW
  67            supports adding or deleting items in this event.
  68     @endEventTable
  69
  70     @library{wxcore}
  71     @category{ctrl}
  72     @appearance{combobox.png}
  73
  74     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  75 */
  76 class wxComboBox : public wxControl,
  77                    public wxItemContainer,
  78                    public wxTextEntry
  79 {
  80 public:
  81     /**
  82         Default constructor.
  83     */
  84     wxComboBox();
  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         @beginWxPerlOnly
 120         Not supported by wxPerl.
 121         @endWxPerlOnly
 122
 123         @see Create(), wxValidator
 124     */
 125     wxComboBox(wxWindow* parent, wxWindowID id,
 126                const wxString& value = wxEmptyString,
 127                const wxPoint& pos = wxDefaultPosition,
 128                const wxSize& size = wxDefaultSize,
 129                int n = 0,
 130                const wxString choices[] = NULL,
 131                long style = 0,
 132                const wxValidator& validator = wxDefaultValidator,
 133                const wxString& name = wxComboBoxNameStr);
 134     /**
 135         Constructor, creating and showing a combobox.
 136
 137         @param parent
 138             Parent window. Must not be @NULL.
 139         @param id
 140             Window identifier. The value wxID_ANY indicates a default value.
 141         @param value
 142             Initial selection string. An empty string indicates no selection.
 143         @param pos
 144             Window position.
 145         @param size
 146             Window size. If wxDefaultSize is specified then the window is sized
 147             appropriately.
 148         @param choices
 149             An array of strings with which to initialise the control.
 150         @param style
 151             Window style. See wxComboBox.
 152         @param validator
 153             Window validator.
 154         @param name
 155             Window name.
 156
 157         @beginWxPythonOnly
 158         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 159         arguments are to a single argument, which is a list of strings.
 160         @endWxPythonOnly
 161
 162         @beginWxPerlOnly
 163         Use an array reference for the @a choices parameter.
 164         @endWxPerlOnly
 165
 166         @see Create(), wxValidator
 167     */
 168     wxComboBox(wxWindow* parent, wxWindowID id,
 169                const wxString& value,
 170                const wxPoint& pos,
 171                const wxSize& size,
 172                const wxArrayString& choices,
 173                long style = 0,
 174                const wxValidator& validator = wxDefaultValidator,
 175                const wxString& name = wxComboBoxNameStr);
 176
 177     /**
 178         Destructor, destroying the combobox.
 179     */
 180     virtual ~wxComboBox();
 181
 182     //@{
 183     /**
 184         Creates the combobox for two-step construction. Derived classes should
 185         call or replace this function. See wxComboBox() for further details.
 186     */
 187     bool Create(wxWindow *parent, wxWindowID id,
 188                 const wxString& value = wxEmptyString,
 189                 const wxPoint& pos = wxDefaultPosition,
 190                 const wxSize& size = wxDefaultSize,
 191                 int n = 0, const wxString choices[] = (const wxString *) NULL,
 192                 long style = 0,
 193                 const wxValidator& validator = wxDefaultValidator,
 194                 const wxString& name = wxComboBoxNameStr);
 195     bool Create(wxWindow *parent, wxWindowID id,
 196                 const wxString& value,
 197                 const wxPoint& pos,
 198                 const wxSize& size,
 199                 const wxArrayString& choices,
 200                 long style = 0,
 201                 const wxValidator& validator = wxDefaultValidator,
 202                 const wxString& name = wxComboBoxNameStr);
 203     //@}
 204
 205     /**
 206         Returns the item being selected right now.
 207
 208         This function does the same things as wxChoice::GetCurrentSelection()
 209         and returns the item currently selected in the dropdown list if it's
 210         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 211     */
 212     virtual int GetCurrentSelection() const;
 213
 214     /**
 215         Same as wxTextEntry::GetInsertionPoint().
 216
 217         @note Under wxMSW, this function always returns 0 if the combobox
 218               doesn't have the focus.
 219     */
 220     virtual long GetInsertionPoint() const;
 221
 222     /**
 223         Same as wxTextEntry::SetSelection().
 224
 225         @beginWxPythonOnly
 226         This method is called SetMark() in wxPython, "SetSelection" is kept for
 227         wxControlWithItems::SetSelection().
 228         @endWxPythonOnly
 229     */
 230     virtual void SetSelection(long from, long to);
 231
 232     /**
 233         Sets the text for the combobox text field.
 234
 235         Notice that this method will generate a wxEVT_COMMAND_TEXT_UPDATED
 236         event, use wxTextEntry::ChangeValue() if this is undesirable.
 237
 238         @note For a combobox with @c wxCB_READONLY style the string must be in
 239               the combobox choices list, otherwise the call to SetValue() is
 240               ignored.
 241
 242         @param text
 243             The text to set.
 244     */
 245     virtual void SetValue(const wxString& text);
 246
 247     /**
 248         Shows the list box portion of the combo box.
 249
 250         Currently only implemented in wxMSW and wxGTK.
 251
 252         Notice that calling this function will generate a
 253         wxEVT_COMMAND_COMBOBOX_DROPDOWN event.
 254
 255         @since 2.9.1
 256     */
 257     virtual void Popup();
 258
 259     /**
 260         Hides the list box portion of the combo box.
 261
 262         Currently only implemented in wxMSW and wxGTK.
 263
 264         Notice that calling this function will generate a
 265         wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
 266
 267         @since 2.9.1
 268     */
 269     virtual void Dismiss();
 270 };
 271