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     @endEventTable
  58
  59     @library{wxcore}
  60     @category{ctrl}
  61     @appearance{combobox.png}
  62
  63     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  64 */
  65 class wxComboBox : public wxControl,
  66                    public wxItemContainer,
  67                    public wxTextEntry
  68 {
  69 public:
  70     /**
  71         Default constructor.
  72     */
  73     wxComboBox();
  74
  75     //@{
  76     /**
  77         Constructor, creating and showing a combobox.
  78
  79         @param parent
  80             Parent window. Must not be @NULL.
  81         @param id
  82             Window identifier. The value wxID_ANY indicates a default value.
  83         @param value
  84             Initial selection string. An empty string indicates no selection.
  85             Notice that for the controls with @c wxCB_READONLY style this
  86             string must be one of the valid choices if it is not empty.
  87         @param pos
  88             Window position.
  89         @param size
  90             Window size. If wxDefaultSize is specified then the window is sized
  91             appropriately.
  92         @param n
  93             Number of strings with which to initialise the control.
  94         @param choices
  95             An array of strings with which to initialise the control.
  96         @param style
  97             Window style. See wxComboBox.
  98         @param validator
  99             Window validator.
 100         @param name
 101             Window name.
 102
 103         @beginWxPythonOnly
 104         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 105         arguments are to a single argument, which is a list of strings.
 106         @endWxPythonOnly
 107
 108         @see Create(), wxValidator
 109     */
 110     wxComboBox(wxWindow* parent, wxWindowID id,
 111                const wxString& value = wxEmptyString,
 112                const wxPoint& pos = wxDefaultPosition,
 113                const wxSize& size = wxDefaultSize,
 114                int n = 0,
 115                const wxString choices[] = NULL,
 116                long style = 0,
 117                const wxValidator& validator = wxDefaultValidator,
 118                const wxString& name = wxComboBoxNameStr);
 119     /**
 120         Constructor, creating and showing a combobox.
 121
 122         @param parent
 123             Parent window. Must not be @NULL.
 124         @param id
 125             Window identifier. The value wxID_ANY indicates a default value.
 126         @param value
 127             Initial selection string. An empty string indicates no selection.
 128         @param pos
 129             Window position.
 130         @param size
 131             Window size. If wxDefaultSize is specified then the window is sized
 132             appropriately.
 133         @param choices
 134             An array of strings with which to initialise the control.
 135         @param style
 136             Window style. See wxComboBox.
 137         @param validator
 138             Window validator.
 139         @param name
 140             Window name.
 141
 142         @beginWxPythonOnly
 143         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 144         arguments are to a single argument, which is a list of strings.
 145         @endWxPythonOnly
 146
 147         @see Create(), wxValidator
 148     */
 149     wxComboBox(wxWindow* parent, wxWindowID id,
 150                const wxString& value,
 151                const wxPoint& pos,
 152                const wxSize& size,
 153                const wxArrayString& choices,
 154                long style = 0,
 155                const wxValidator& validator = wxDefaultValidator,
 156                const wxString& name = wxComboBoxNameStr);
 157     //@}
 158
 159     /**
 160         Destructor, destroying the combobox.
 161     */
 162     virtual ~wxComboBox();
 163
 164     //@{
 165     /**
 166         Creates the combobox for two-step construction. Derived classes should
 167         call or replace this function. See wxComboBox() for further details.
 168     */
 169     bool Create(wxWindow *parent, wxWindowID id,
 170                 const wxString& value = wxEmptyString,
 171                 const wxPoint& pos = wxDefaultPosition,
 172                 const wxSize& size = wxDefaultSize,
 173                 int n = 0, const wxString choices[] = (const wxString *) NULL,
 174                 long style = 0,
 175                 const wxValidator& validator = wxDefaultValidator,
 176                 const wxString& name = wxComboBoxNameStr);
 177     bool Create(wxWindow *parent, wxWindowID id,
 178                 const wxString& value,
 179                 const wxPoint& pos,
 180                 const wxSize& size,
 181                 const wxArrayString& choices,
 182                 long style = 0,
 183                 const wxValidator& validator = wxDefaultValidator,
 184                 const wxString& name = wxComboBoxNameStr);
 185     //@}
 186
 187     /**
 188         Returns the item being selected right now.
 189
 190         This function does the same things as wxChoice::GetCurrentSelection()
 191         and returns the item currently selected in the dropdown list if it's
 192         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 193     */
 194     virtual int GetCurrentSelection() const;
 195
 196     /**
 197         Same as wxTextEntry::GetInsertionPoint().
 198
 199         @note Under wxMSW, this function always returns 0 if the combobox
 200               doesn't have the focus.
 201     */
 202     virtual long GetInsertionPoint() const;
 203
 204     /**
 205         Same as wxTextEntry::SetSelection().
 206
 207         @beginWxPythonOnly
 208         This method is called SetMark() in wxPython, "SetSelection" is kept for
 209         wxControlWithItems::SetSelection().
 210         @endWxPythonOnly
 211     */
 212     virtual void SetSelection(long from, long to);
 213
 214     /**
 215         Sets the text for the combobox text field.
 216
 217         @note For a combobox with @c wxCB_READONLY style the string must be in
 218               the combobox choices list, otherwise the call to SetValue() is
 219               ignored.
 220
 221         @param text
 222             The text to set.
 223     */
 224     virtual void SetValue(const wxString& text);
 225 };
 226