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