interface/wx/combobox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        combobox.h
   3 // Purpose:     interface of wxComboBox
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxComboBox
  10
  11     A combobox is like a combination of an edit control and a listbox.
  12
  13     It can be displayed as static list with editable or read-only text field;
  14     or a drop-down list with text field; or a drop-down list without a text
  15     field depending on the platform and presence of wxCB_READONLY style.
  16
  17     A combobox permits a single selection only. Combobox items are numbered
  18     from zero.
  19
  20     If you need a customized combobox, have a look at wxComboCtrl,
  21     wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
  22
  23     Please refer to wxTextEntry documentation for the description of methods
  24     operating with the text entry part of the combobox and to wxItemContainer
  25     for the methods operating with the list of strings. Notice that at least
  26     under MSW wxComboBox doesn't behave correctly if it contains strings
  27     differing in case only so portable programs should avoid adding such
  28     strings to this control.
  29
  30     @beginStyleTable
  31     @style{wxCB_SIMPLE}
  32            Creates a combobox with a permanently displayed list. Windows only.
  33     @style{wxCB_DROPDOWN}
  34            Creates a combobox with a drop-down list. MSW and Motif only.
  35     @style{wxCB_READONLY}
  36            A combobox with this style behaves like a wxChoice (and may look in
  37            the same way as well, although this is platform-dependent), i.e. it
  38            allows the user to choose from the list of options but doesn't allow
  39            to enter a value not present in the list.
  40     @style{wxCB_SORT}
  41            Sorts the entries in the list alphabetically.
  42     @style{wxTE_PROCESS_ENTER}
  43            The control will generate the event @c wxEVT_TEXT_ENTER
  44            (otherwise pressing Enter key is either processed internally by the
  45            control or used for navigation between dialog controls).
  46     @endStyleTable
  47
  48     @beginEventEmissionTable{wxCommandEvent}
  49     @event{EVT_COMBOBOX(id, func)}
  50            Process a @c wxEVT_COMBOBOX event, when an item on
  51            the list is selected. Note that calling GetValue() returns the new
  52            value of selection.
  53     @event{EVT_TEXT(id, func)}
  54            Process a @c wxEVT_TEXT event, when the combobox text
  55            changes.
  56     @event{EVT_TEXT_ENTER(id, func)}
  57            Process a @c wxEVT_TEXT_ENTER event, when RETURN is pressed in
  58            the combobox (notice that the combobox must have been created with
  59            wxTE_PROCESS_ENTER style to receive this event).
  60     @event{EVT_COMBOBOX_DROPDOWN(id, func)}
  61            Process a @c wxEVT_COMBOBOX_DROPDOWN event, which is generated
  62            when the list box part of the combo box is shown (drops down).
  63            Notice that this event is currently only supported by wxMSW and
  64            wxGTK with GTK+ 2.10 or later.
  65     @event{EVT_COMBOBOX_CLOSEUP(id, func)}
  66            Process a @c wxEVT_COMBOBOX_CLOSEUP event, which is generated
  67            when the list box of the combo box disappears (closes up). This
  68            event is only generated for the same platforms as
  69            @c wxEVT_COMBOBOX_DROPDOWN above. Also note that only wxMSW
  70            supports adding or deleting items in this event.
  71     @endEventTable
  72
  73     @library{wxcore}
  74     @category{ctrl}
  75     @appearance{combobox}
  76
  77     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  78 */
  79 class wxComboBox : public wxControl,
  80                    public wxItemContainer,
  81                    public wxTextEntry
  82 {
  83 public:
  84     /**
  85         Default constructor.
  86     */
  87     wxComboBox();
  88
  89     /**
  90         Constructor, creating and showing a combobox.
  91
  92         @param parent
  93             Parent window. Must not be @NULL.
  94         @param id
  95             Window identifier. The value wxID_ANY indicates a default value.
  96         @param value
  97             Initial selection string. An empty string indicates no selection.
  98             Notice that for the controls with @c wxCB_READONLY style this
  99             string must be one of the valid choices if it is not empty.
 100         @param pos
 101             Window position.
 102             If ::wxDefaultPosition is specified then a default position is chosen.
 103         @param size
 104             Window size.
 105             If ::wxDefaultSize is specified then the window is sized appropriately.
 106         @param n
 107             Number of strings with which to initialise the control.
 108         @param choices
 109             An array of strings with which to initialise the control.
 110         @param style
 111             Window style. See wxComboBox.
 112         @param validator
 113             Window validator.
 114         @param name
 115             Window name.
 116
 117         @beginWxPerlOnly
 118         Not supported by wxPerl.
 119         @endWxPerlOnly
 120
 121         @see Create(), wxValidator
 122     */
 123     wxComboBox(wxWindow* parent, wxWindowID id,
 124                const wxString& value = wxEmptyString,
 125                const wxPoint& pos = wxDefaultPosition,
 126                const wxSize& size = wxDefaultSize,
 127                int n = 0,
 128                const wxString choices[] = NULL,
 129                long style = 0,
 130                const wxValidator& validator = wxDefaultValidator,
 131                const wxString& name = wxComboBoxNameStr);
 132     /**
 133         Constructor, creating and showing a combobox.
 134
 135         @param parent
 136             Parent window. Must not be @NULL.
 137         @param id
 138             Window identifier. The value wxID_ANY indicates a default value.
 139         @param value
 140             Initial selection string. An empty string indicates no selection.
 141         @param pos
 142             Window position.
 143         @param size
 144             Window size. If wxDefaultSize is specified then the window is sized
 145             appropriately.
 146         @param choices
 147             An array of strings with which to initialise the control.
 148         @param style
 149             Window style. See wxComboBox.
 150         @param validator
 151             Window validator.
 152         @param name
 153             Window name.
 154
 155         @beginWxPerlOnly
 156         Use an array reference for the @a choices parameter.
 157         @endWxPerlOnly
 158
 159         @see Create(), wxValidator
 160     */
 161     wxComboBox(wxWindow* parent, wxWindowID id,
 162                const wxString& value,
 163                const wxPoint& pos,
 164                const wxSize& size,
 165                const wxArrayString& choices,
 166                long style = 0,
 167                const wxValidator& validator = wxDefaultValidator,
 168                const wxString& name = wxComboBoxNameStr);
 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         IsEmpty() is not available in this class.
 217
 218         This method is documented here only to notice that it can't be used
 219         with this class because of the ambiguity between the methods with the
 220         same name inherited from wxItemContainer and wxTextEntry base classes.
 221
 222         Because of this, any attempt to call it results in a compilation error
 223         and you should use either IsListEmpty() or IsTextEmpty() depending on
 224         what exactly do you want to test.
 225      */
 226     bool IsEmpty() const;
 227
 228     /**
 229         Returns true if the list of combobox choices is empty.
 230
 231         Use this method instead of (not available in this class) IsEmpty() to
 232         test if the list of items is empty.
 233
 234         @since 2.9.3
 235      */
 236     bool IsListEmpty() const;
 237
 238     /**
 239         Returns true if the text of the combobox is empty.
 240
 241         Use this method instead of (not available in this class) IsEmpty() to
 242         test if the text currently entered into the combobox is empty.
 243
 244         @since 2.9.3
 245      */
 246     bool IsTextEmpty() const;
 247
 248     /**
 249         Same as wxTextEntry::SetSelection().
 250     */
 251     virtual void SetSelection(long from, long to);
 252
 253     /**
 254         Sets the text for the combobox text field.
 255
 256         Notice that this method will generate a @c wxEVT_TEXT
 257         event, use wxTextEntry::ChangeValue() if this is undesirable.
 258
 259         @note For a combobox with @c wxCB_READONLY style the string must be in
 260               the combobox choices list, otherwise the call to SetValue() is
 261               ignored. This is case insensitive.
 262
 263         @param text
 264             The text to set.
 265     */
 266     virtual void SetValue(const wxString& text);
 267
 268     /**
 269         Shows the list box portion of the combo box.
 270
 271         Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.
 272
 273         Notice that calling this function will generate a
 274         @c wxEVT_COMBOBOX_DROPDOWN event except under wxOSX where
 275         generation of this event is not supported at all.
 276
 277         @since 2.9.1
 278     */
 279     virtual void Popup();
 280
 281     /**
 282         Hides the list box portion of the combo box.
 283
 284         Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.
 285
 286         Notice that calling this function will generate a
 287         @c wxEVT_COMBOBOX_CLOSEUP event except under wxOSX where
 288         generation of this event is not supported at all.
 289
 290         @since 2.9.1
 291     */
 292     virtual void Dismiss();
 293
 294     virtual int GetSelection() const;
 295     virtual void GetSelection(long *from, long *to) const;
 296     virtual void SetSelection(int n);
 297     virtual int FindString(const wxString& s, bool bCase = false) const;
 298     virtual wxString GetString(unsigned int n) const;
 299     virtual wxString GetStringSelection() const;
 300
 301     /**
 302         Changes the text of the specified combobox item.
 303
 304         Notice that if the item is the currently selected one, i.e. if its text
 305         is displayed in the text part of the combobox, then the text is also
 306         replaced with the new @a text.
 307      */
 308     virtual void SetString(unsigned int n, const wxString& text);
 309
 310     virtual unsigned int GetCount() const;
 311 };
 312