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_COMBOBOX_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_COMBOBOX_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. Also note that only wxMSW
  67            supports adding or deleting items in this event.
  68     @endEventTable
  69
  70     @library{wxcore}
  71     @category{ctrl}
  72     @appearance{combobox.png}
  73
  74     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  75 */
  76 class wxComboBox : public wxControl,
  77                    public wxItemContainer,
  78                    public wxTextEntry
  79 {
  80 public:
  81     /**
  82         Default constructor.
  83     */
  84     wxComboBox();
  85
  86     //@{
  87     /**
  88         Constructor, creating and showing a combobox.
  89
  90         @param parent
  91             Parent window. Must not be @NULL.
  92         @param id
  93             Window identifier. The value wxID_ANY indicates a default value.
  94         @param value
  95             Initial selection string. An empty string indicates no selection.
  96             Notice that for the controls with @c wxCB_READONLY style this
  97             string must be one of the valid choices if it is not empty.
  98         @param pos
  99             Window position.
 100             If ::wxDefaultPosition is specified then a default position is chosen.
 101         @param size
 102             Window size.
 103             If ::wxDefaultSize is specified then the window is sized appropriately.
 104         @param n
 105             Number of strings with which to initialise the control.
 106         @param choices
 107             An array of strings with which to initialise the control.
 108         @param style
 109             Window style. See wxComboBox.
 110         @param validator
 111             Window validator.
 112         @param name
 113             Window name.
 114
 115         @beginWxPythonOnly
 116         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 117         arguments are to a single argument, which is a list of strings.
 118         @endWxPythonOnly
 119
 120         @beginWxPerlOnly
 121         Not supported by wxPerl.
 122         @endWxPerlOnly
 123
 124         @see Create(), wxValidator
 125     */
 126     wxComboBox(wxWindow* parent, wxWindowID id,
 127                const wxString& value = wxEmptyString,
 128                const wxPoint& pos = wxDefaultPosition,
 129                const wxSize& size = wxDefaultSize,
 130                int n = 0,
 131                const wxString choices[] = NULL,
 132                long style = 0,
 133                const wxValidator& validator = wxDefaultValidator,
 134                const wxString& name = wxComboBoxNameStr);
 135     /**
 136         Constructor, creating and showing a combobox.
 137
 138         @param parent
 139             Parent window. Must not be @NULL.
 140         @param id
 141             Window identifier. The value wxID_ANY indicates a default value.
 142         @param value
 143             Initial selection string. An empty string indicates no selection.
 144         @param pos
 145             Window position.
 146         @param size
 147             Window size. If wxDefaultSize is specified then the window is sized
 148             appropriately.
 149         @param choices
 150             An array of strings with which to initialise the control.
 151         @param style
 152             Window style. See wxComboBox.
 153         @param validator
 154             Window validator.
 155         @param name
 156             Window name.
 157
 158         @beginWxPythonOnly
 159         The wxComboBox constructor in wxPython reduces the @a n and @a choices
 160         arguments are to a single argument, which is a list of strings.
 161         @endWxPythonOnly
 162
 163         @beginWxPerlOnly
 164         Use an array reference for the @a choices parameter.
 165         @endWxPerlOnly
 166
 167         @see Create(), wxValidator
 168     */
 169     wxComboBox(wxWindow* parent, wxWindowID id,
 170                const wxString& value,
 171                const wxPoint& pos,
 172                const wxSize& size,
 173                const wxArrayString& choices,
 174                long style = 0,
 175                const wxValidator& validator = wxDefaultValidator,
 176                const wxString& name = wxComboBoxNameStr);
 177     //@}
 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.
 243
 244         @param text
 245             The text to set.
 246     */
 247     virtual void SetValue(const wxString& text);
 248 };
 249