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