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 depending on the platform and presence of wxCB_READONLY style.
  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 and to wxItemContainer
  26     for the methods operating with the list of strings. Notice that at least
  27     under MSW wxComboBox doesn't behave correctly if it contains strings
  28     differing in case only so portable programs should avoid adding such
  29     strings to this control.
  30
  31     @beginStyleTable
  32     @style{wxCB_SIMPLE}
  33            Creates a combobox with a permanently displayed list. Windows only.
  34     @style{wxCB_DROPDOWN}
  35            Creates a combobox with a drop-down list. MSW and Motif only.
  36     @style{wxCB_READONLY}
  37            A combobox with this style behaves like a wxChoice (and may look in
  38            the same way as well, although this is platform-dependent), i.e. it
  39            allows the user to choose from the list of options but doesn't allow
  40            to enter a value not present in the list.
  41     @style{wxCB_SORT}
  42            Sorts the entries in the list alphabetically.
  43     @style{wxTE_PROCESS_ENTER}
  44            The control will generate the event @c wxEVT_COMMAND_TEXT_ENTER
  45            (otherwise pressing Enter key is either processed internally by the
  46            control or used for navigation between dialog controls). Windows
  47            only.
  48     @endStyleTable
  49
  50     @beginEventEmissionTable{wxCommandEvent}
  51     @event{EVT_COMBOBOX(id, func)}
  52            Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  53            the list is selected. Note that calling GetValue() returns the new
  54            value of selection.
  55     @event{EVT_TEXT(id, func)}
  56            Process a @c wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
  57            changes.
  58     @event{EVT_TEXT_ENTER(id, func)}
  59            Process a @c wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
  60            the combobox (notice that the combobox must have been created with
  61            wxTE_PROCESS_ENTER style to receive this event).
  62     @event{EVT_COMBOBOX_DROPDOWN(id, func)}
  63            Process a @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
  64            when the list box part of the combo box is shown (drops down).
  65            Notice that this event is currently only supported by wxMSW and
  66            wxGTK with GTK+ 2.10 or later.
  67     @event{EVT_COMBOBOX_CLOSEUP(id, func)}
  68            Process a @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
  69            when the list box of the combo box disappears (closes up). This
  70            event is only generated for the same platforms as
  71            @c wxEVT_COMMAND_COMBOBOX_DROPDOWN above. Also note that only wxMSW
  72            supports adding or deleting items in this event.
  73     @endEventTable
  74
  75     @library{wxcore}
  76     @category{ctrl}
  77     @appearance{combobox.png}
  78
  79     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  80 */
  81 class wxComboBox : public wxControl,
  82                    public wxItemContainer,
  83                    public wxTextEntry
  84 {
  85 public:
  86     /**
  87         Default constructor.
  88     */
  89     wxComboBox();
  90
  91     /**
  92         Constructor, creating and showing a combobox.
  93
  94         @param parent
  95             Parent window. Must not be @NULL.
  96         @param id
  97             Window identifier. The value wxID_ANY indicates a default value.
  98         @param value
  99             Initial selection string. An empty string indicates no selection.
 100             Notice that for the controls with @c wxCB_READONLY style this
 101             string must be one of the valid choices if it is not empty.
 102         @param pos
 103             Window position.
 104             If ::wxDefaultPosition is specified then a default position is chosen.
 105         @param size
 106             Window size.
 107             If ::wxDefaultSize is specified then the window is sized appropriately.
 108         @param n
 109             Number of strings with which to initialise the control.
 110         @param choices
 111             An array of strings with which to initialise the control.
 112         @param style
 113             Window style. See wxComboBox.
 114         @param validator
 115             Window validator.
 116         @param name
 117             Window name.
 118
 119         @beginWxPythonOnly
 120         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 121         arguments are to a single argument, which is a list of strings.
 122         @endWxPythonOnly
 123
 124         @beginWxPerlOnly
 125         Not supported by wxPerl.
 126         @endWxPerlOnly
 127
 128         @see Create(), wxValidator
 129     */
 130     wxComboBox(wxWindow* parent, wxWindowID id,
 131                const wxString& value = wxEmptyString,
 132                const wxPoint& pos = wxDefaultPosition,
 133                const wxSize& size = wxDefaultSize,
 134                int n = 0,
 135                const wxString choices[] = NULL,
 136                long style = 0,
 137                const wxValidator& validator = wxDefaultValidator,
 138                const wxString& name = wxComboBoxNameStr);
 139     /**
 140         Constructor, creating and showing a combobox.
 141
 142         @param parent
 143             Parent window. Must not be @NULL.
 144         @param id
 145             Window identifier. The value wxID_ANY indicates a default value.
 146         @param value
 147             Initial selection string. An empty string indicates no selection.
 148         @param pos
 149             Window position.
 150         @param size
 151             Window size. If wxDefaultSize is specified then the window is sized
 152             appropriately.
 153         @param choices
 154             An array of strings with which to initialise the control.
 155         @param style
 156             Window style. See wxComboBox.
 157         @param validator
 158             Window validator.
 159         @param name
 160             Window name.
 161
 162         @beginWxPythonOnly
 163         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 164         arguments are to a single argument, which is a list of strings.
 165         @endWxPythonOnly
 166
 167         @beginWxPerlOnly
 168         Use an array reference for the @a choices parameter.
 169         @endWxPerlOnly
 170
 171         @see Create(), wxValidator
 172     */
 173     wxComboBox(wxWindow* parent, wxWindowID id,
 174                const wxString& value,
 175                const wxPoint& pos,
 176                const wxSize& size,
 177                const wxArrayString& choices,
 178                long style = 0,
 179                const wxValidator& validator = wxDefaultValidator,
 180                const wxString& name = wxComboBoxNameStr);
 181
 182     /**
 183         Destructor, destroying the combobox.
 184     */
 185     virtual ~wxComboBox();
 186
 187     //@{
 188     /**
 189         Creates the combobox for two-step construction. Derived classes should
 190         call or replace this function. See wxComboBox() for further details.
 191     */
 192     bool Create(wxWindow *parent, wxWindowID id,
 193                 const wxString& value = wxEmptyString,
 194                 const wxPoint& pos = wxDefaultPosition,
 195                 const wxSize& size = wxDefaultSize,
 196                 int n = 0, const wxString choices[] = (const wxString *) NULL,
 197                 long style = 0,
 198                 const wxValidator& validator = wxDefaultValidator,
 199                 const wxString& name = wxComboBoxNameStr);
 200     bool Create(wxWindow *parent, wxWindowID id,
 201                 const wxString& value,
 202                 const wxPoint& pos,
 203                 const wxSize& size,
 204                 const wxArrayString& choices,
 205                 long style = 0,
 206                 const wxValidator& validator = wxDefaultValidator,
 207                 const wxString& name = wxComboBoxNameStr);
 208     //@}
 209
 210     /**
 211         Returns the item being selected right now.
 212
 213         This function does the same things as wxChoice::GetCurrentSelection()
 214         and returns the item currently selected in the dropdown list if it's
 215         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 216     */
 217     virtual int GetCurrentSelection() const;
 218
 219     /**
 220         Same as wxTextEntry::GetInsertionPoint().
 221
 222         @note Under wxMSW, this function always returns 0 if the combobox
 223               doesn't have the focus.
 224     */
 225     virtual long GetInsertionPoint() const;
 226
 227     /**
 228         IsEmpty() is not available in this class.
 229
 230         This method is documented here only to notice that it can't be used
 231         with this class because of the ambiguity between the methods with the
 232         same name inherited from wxItemContainer and wxTextEntry base classes.
 233
 234         Because of this, any attempt to call it results in a compilation error
 235         and you should use either IsListEmpty() or IsTextEmpty() depending on
 236         what exactly do you want to test.
 237      */
 238     bool IsEmpty() const;
 239
 240     /**
 241         Returns true if the list of combobox choices is empty.
 242
 243         Use this method instead of (not available in this class) IsEmpty() to
 244         test if the list of items is empty.
 245
 246         @since 2.9.3
 247      */
 248     bool IsListEmpty() const;
 249
 250     /**
 251         Returns true if the text of the combobox is empty.
 252
 253         Use this method instead of (not available in this class) IsEmpty() to
 254         test if the text currently entered into the combobox is empty.
 255
 256         @since 2.9.3
 257      */
 258     bool IsTextEmpty() const;
 259
 260     /**
 261         Same as wxTextEntry::SetSelection().
 262
 263         @beginWxPythonOnly
 264         This method is called SetMark() in wxPython, "SetSelection" is kept for
 265         wxControlWithItems::SetSelection().
 266         @endWxPythonOnly
 267     */
 268     virtual void SetSelection(long from, long to);
 269
 270     /**
 271         Sets the text for the combobox text field.
 272
 273         Notice that this method will generate a @c wxEVT_COMMAND_TEXT_UPDATED
 274         event, use wxTextEntry::ChangeValue() if this is undesirable.
 275
 276         @note For a combobox with @c wxCB_READONLY style the string must be in
 277               the combobox choices list, otherwise the call to SetValue() is
 278               ignored. This is case insensitive.
 279
 280         @param text
 281             The text to set.
 282     */
 283     virtual void SetValue(const wxString& text);
 284
 285     /**
 286         Shows the list box portion of the combo box.
 287
 288         Currently only implemented in wxMSW and wxGTK.
 289
 290         Notice that calling this function will generate a
 291         @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event.
 292
 293         @since 2.9.1
 294     */
 295     virtual void Popup();
 296
 297     /**
 298         Hides the list box portion of the combo box.
 299
 300         Currently only implemented in wxMSW and wxGTK.
 301
 302         Notice that calling this function will generate a
 303         @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
 304
 305         @since 2.9.1
 306     */
 307     virtual void Dismiss();
 308 };
 309