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         @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         @beginWxPerlOnly
 158         Use an array reference for the @a choices parameter.
 159         @endWxPerlOnly
 160
 161         @see Create(), wxValidator
 162     */
 163     wxComboBox(wxWindow* parent, wxWindowID id,
 164                const wxString& value,
 165                const wxPoint& pos,
 166                const wxSize& size,
 167                const wxArrayString& choices,
 168                long style = 0,
 169                const wxValidator& validator = wxDefaultValidator,
 170                const wxString& name = wxComboBoxNameStr);
 171
 172     /**
 173         Destructor, destroying the combobox.
 174     */
 175     virtual ~wxComboBox();
 176
 177     //@{
 178     /**
 179         Creates the combobox for two-step construction. Derived classes should
 180         call or replace this function. See wxComboBox() for further details.
 181     */
 182     bool Create(wxWindow *parent, wxWindowID id,
 183                 const wxString& value = wxEmptyString,
 184                 const wxPoint& pos = wxDefaultPosition,
 185                 const wxSize& size = wxDefaultSize,
 186                 int n = 0, const wxString choices[] = (const wxString *) NULL,
 187                 long style = 0,
 188                 const wxValidator& validator = wxDefaultValidator,
 189                 const wxString& name = wxComboBoxNameStr);
 190     bool Create(wxWindow *parent, wxWindowID id,
 191                 const wxString& value,
 192                 const wxPoint& pos,
 193                 const wxSize& size,
 194                 const wxArrayString& choices,
 195                 long style = 0,
 196                 const wxValidator& validator = wxDefaultValidator,
 197                 const wxString& name = wxComboBoxNameStr);
 198     //@}
 199
 200     /**
 201         Returns the item being selected right now.
 202
 203         This function does the same things as wxChoice::GetCurrentSelection()
 204         and returns the item currently selected in the dropdown list if it's
 205         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 206     */
 207     virtual int GetCurrentSelection() const;
 208
 209     /**
 210         Same as wxTextEntry::GetInsertionPoint().
 211
 212         @note Under wxMSW, this function always returns 0 if the combobox
 213               doesn't have the focus.
 214     */
 215     virtual long GetInsertionPoint() const;
 216
 217     /**
 218         IsEmpty() is not available in this class.
 219
 220         This method is documented here only to notice that it can't be used
 221         with this class because of the ambiguity between the methods with the
 222         same name inherited from wxItemContainer and wxTextEntry base classes.
 223
 224         Because of this, any attempt to call it results in a compilation error
 225         and you should use either IsListEmpty() or IsTextEmpty() depending on
 226         what exactly do you want to test.
 227      */
 228     bool IsEmpty() const;
 229
 230     /**
 231         Returns true if the list of combobox choices is empty.
 232
 233         Use this method instead of (not available in this class) IsEmpty() to
 234         test if the list of items is empty.
 235
 236         @since 2.9.3
 237      */
 238     bool IsListEmpty() const;
 239
 240     /**
 241         Returns true if the text of the combobox is empty.
 242
 243         Use this method instead of (not available in this class) IsEmpty() to
 244         test if the text currently entered into the combobox is empty.
 245
 246         @since 2.9.3
 247      */
 248     bool IsTextEmpty() const;
 249
 250     /**
 251         Same as wxTextEntry::SetSelection().
 252     */
 253     virtual void SetSelection(long from, long to);
 254
 255     /**
 256         Sets the text for the combobox text field.
 257
 258         Notice that this method will generate a @c wxEVT_COMMAND_TEXT_UPDATED
 259         event, use wxTextEntry::ChangeValue() if this is undesirable.
 260
 261         @note For a combobox with @c wxCB_READONLY style the string must be in
 262               the combobox choices list, otherwise the call to SetValue() is
 263               ignored. This is case insensitive.
 264
 265         @param text
 266             The text to set.
 267     */
 268     virtual void SetValue(const wxString& text);
 269
 270     /**
 271         Shows the list box portion of the combo box.
 272
 273         Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.
 274
 275         Notice that calling this function will generate a
 276         @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event except under wxOSX where
 277         generation of this event is not supported at all.
 278
 279         @since 2.9.1
 280     */
 281     virtual void Popup();
 282
 283     /**
 284         Hides the list box portion of the combo box.
 285
 286         Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.
 287
 288         Notice that calling this function will generate a
 289         @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event except under wxOSX where
 290         generation of this event is not supported at all.
 291
 292         @since 2.9.1
 293     */
 294     virtual void Dismiss();
 295
 296     virtual int GetSelection() const;
 297     virtual void GetSelection(long *from, long *to) const;
 298     virtual void SetSelection(int n);
 299     virtual int FindString(const wxString& s, bool bCase = false) const;
 300     virtual wxString GetString(unsigned int n) const;
 301     virtual wxString GetStringSelection() const;
 302
 303     /**
 304         Changes the text of the specified combobox item.
 305
 306         Notice that if the item is the currently selected one, i.e. if its text
 307         is displayed in the text part of the combobox, then the text is also
 308         replaced with the new @a text.
 309      */
 310     virtual void SetString(unsigned int n, const wxString& text);
 311
 312     virtual unsigned int GetCount() const;
 313 };
 314