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