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