interface/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     @wxheader{combobox.h}
  12
  13     A combobox is like a combination of an edit control and a listbox. It can
  14     be displayed as static list with editable or read-only text field; or a
  15     drop-down list with text field; or a drop-down list without a text field.
  16
  17     A combobox permits a single selection only. Combobox items are numbered
  18     from zero.
  19
  20     If you need a customized combobox, have a look at wxComboCtrl,
  21     wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
  22
  23     @beginStyleTable
  24     @style{wxCB_SIMPLE}
  25            Creates a combobox with a permanently displayed list. Windows only.
  26     @style{wxCB_DROPDOWN}
  27            Creates a combobox with a drop-down list.
  28     @style{wxCB_READONLY}
  29            Same as wxCB_DROPDOWN but only the strings specified as the combobox
  30            choices can be selected, it is impossible to select (even from a
  31            program) a string which is not in the choices list.
  32     @style{wxCB_SORT}
  33            Sorts the entries in the list alphabetically.
  34     @style{wxTE_PROCESS_ENTER}
  35            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
  36            (otherwise pressing Enter key is either processed internally by the
  37            control or used for navigation between dialog controls). Windows
  38            only.
  39     @endStyleTable
  40
  41     @beginEventTable{wxCommandEvent}
  42     @event{EVT_COMBOBOX(id, func)}
  43            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  44            the list is selected. Note that calling GetValue() returns the new
  45            value of selection.
  46     @event{EVT_TEXT(id, func)}
  47            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
  48            changes.
  49     @event{EVT_TEXT_ENTER(id, func)}
  50            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
  51            the combobox (notice that the combobox must have been created with
  52            wxTE_PROCESS_ENTER style to receive this event).
  53     @endEventTable
  54
  55     @library{wxcore}
  56     @category{ctrl}
  57     <!-- @appearance{combobox.png} -->
  58
  59     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  60 */
  61 class wxComboBox : public wxControl, public wxItemContainer
  62 {
  63 public:
  64     /**
  65         Default constructor.
  66     */
  67     wxComboBox();
  68
  69     //@{
  70     /**
  71         Constructor, creating and showing a combobox.
  72
  73         @param parent
  74             Parent window. Must not be @NULL.
  75         @param id
  76             Window identifier. The value wxID_ANY indicates a default value.
  77         @param value
  78             Initial selection string. An empty string indicates no selection.
  79         @param pos
  80             Window position.
  81         @param size
  82             Window size. If wxDefaultSize is specified then the window is sized
  83             appropriately.
  84         @param n
  85             Number of strings with which to initialise the control.
  86         @param choices
  87             An array of strings with which to initialise the control.
  88         @param style
  89             Window style. See wxComboBox.
  90         @param validator
  91             Window validator.
  92         @param name
  93             Window name.
  94
  95         @beginWxPythonOnly
  96         The wxComboBox constructor in wxPython reduces the @a n and @a choices
  97         arguments are to a single argument, which is a list of strings.
  98         @endWxPythonOnly
  99
 100         @see Create(), wxValidator
 101     */
 102     wxComboBox(wxWindow* parent, wxWindowID id,
 103                const wxString& value = "",
 104                const wxPoint& pos = wxDefaultPosition,
 105                const wxSize& size = wxDefaultSize,
 106                int n = 0,
 107                const wxString choices[] = NULL,
 108                long style = 0,
 109                const wxValidator& validator = wxDefaultValidator,
 110                const wxString& name = "comboBox");
 111     wxComboBox(wxWindow* parent, wxWindowID id,
 112                const wxString& value,
 113                const wxPoint& pos,
 114                const wxSize& size,
 115                const wxArrayString& choices,
 116                long style = 0,
 117                const wxValidator& validator = wxDefaultValidator,
 118                const wxString& name = "comboBox");
 119     //@}
 120
 121     /**
 122         Destructor, destroying the combobox.
 123     */
 124     ~wxComboBox();
 125
 126     //@{
 127     /**
 128         Creates the combobox for two-step construction. Derived classes should
 129         call or replace this function. See wxComboBox() for further details.
 130     */
 131     bool Create(wxWindow* parent, wxWindowID id,
 132                 const wxString& value = "",
 133                 const wxPoint& pos = wxDefaultPosition,
 134                 const wxSize& size = wxDefaultSize,
 135                 int n, const wxString choices[],
 136                 long style = 0,
 137                 const wxValidator& validator = wxDefaultValidator,
 138                 const wxString& name = "comboBox");
 139     bool Create(wxWindow* parent, wxWindowID id,
 140                 const wxString& value,
 141                 const wxPoint& pos,
 142                 const wxSize& size,
 143                 const wxArrayString& choices,
 144                 long style = 0,
 145                 const wxValidator& validator = wxDefaultValidator,
 146                 const wxString& name = "comboBox");
 147     //@}
 148
 149     /**
 150         Returns @true if the combobox is editable and there is a text selection
 151         to copy to the clipboard. Only available on Windows.
 152     */
 153     bool CanCopy() const;
 154
 155     /**
 156         Returns @true if the combobox is editable and there is a text selection
 157         to copy to the clipboard. Only available on Windows.
 158     */
 159     bool CanCut() const;
 160
 161     /**
 162         Returns @true if the combobox is editable and there is text on the
 163         clipboard that can be pasted into the text field. Only available on
 164         Windows.
 165     */
 166     bool CanPaste() const;
 167
 168     /**
 169         Returns @true if the combobox is editable and the last undo can be
 170         redone. Only available on Windows.
 171     */
 172     bool CanRedo() const;
 173
 174     /**
 175         Returns @true if the combobox is editable and the last edit can be
 176         undone. Only available on Windows.
 177     */
 178     bool CanUndo() const;
 179
 180     /**
 181         Copies the selected text to the clipboard.
 182     */
 183     void Copy();
 184
 185     /**
 186         Copies the selected text to the clipboard and removes the selection.
 187     */
 188     void Cut();
 189
 190     /**
 191         This function does the same things as wxChoice::GetCurrentSelection()
 192         and returns the item currently selected in the dropdown list if it's
 193         open or the same thing as wxControlWithItems::GetSelection() otherwise.
 194     */
 195     int GetCurrentSelection() const;
 196
 197     /**
 198         Returns the insertion point for the combobox's text field.
 199
 200         @note Under wxMSW, this function always returns 0 if the combobox
 201               doesn't have the focus.
 202     */
 203     long GetInsertionPoint() const;
 204
 205     /**
 206         Returns the last position in the combobox text field.
 207     */
 208     virtual wxTextPos GetLastPosition() const;
 209
 210     /**
 211         This is the same as wxTextCtrl::GetSelection() for the text control
 212         which is part of the combobox. Notice that this is a different method
 213         from wxControlWithItems::GetSelection().
 214
 215         Currently this method is only implemented in wxMSW and wxGTK.
 216     */
 217     void GetSelection(long* from, long* to) const;
 218
 219     /**
 220         Returns the current value in the combobox text field.
 221     */
 222     wxString GetValue() const;
 223
 224     /**
 225         Pastes text from the clipboard to the text field.
 226     */
 227     void Paste();
 228
 229     /**
 230         Redoes the last undo in the text field. Windows only.
 231     */
 232     void Redo();
 233
 234     /**
 235         Removes the text between the two positions in the combobox text field.
 236
 237         @param from
 238             The first position.
 239         @param to
 240             The last position.
 241     */
 242     void Remove(long from, long to);
 243
 244     /**
 245         Replaces the text between two positions with the given text, in the
 246         combobox text field.
 247
 248         @param from
 249             The first position.
 250         @param to
 251             The second position.
 252         @param text
 253             The text to insert.
 254     */
 255     void Replace(long from, long to, const wxString& text);
 256
 257     /**
 258         Sets the insertion point in the combobox text field.
 259
 260         @param pos
 261             The new insertion point.
 262     */
 263     void SetInsertionPoint(long pos);
 264
 265     /**
 266         Sets the insertion point at the end of the combobox text field.
 267     */
 268     void SetInsertionPointEnd();
 269
 270     /**
 271         Selects the text between the two positions, in the combobox text field.
 272
 273         @param from
 274             The first position.
 275         @param to
 276             The second position.
 277
 278         @beginWxPythonOnly
 279         This method is called SetMark() in wxPython, "SetSelection" is kept for
 280         wxControlWithItems::SetSelection().
 281         @endWxPythonOnly
 282     */
 283     void SetSelection(long from, long to);
 284
 285     /**
 286         Sets the text for the combobox text field.
 287
 288         @note For a combobox with @c wxCB_READONLY style the string must be in
 289               the combobox choices list, otherwise the call to SetValue() is
 290               ignored.
 291
 292         @param text
 293             The text to set.
 294     */
 295     void SetValue(const wxString& text);
 296
 297     /**
 298         Undoes the last edit in the text field. Windows only.
 299     */
 300     void Undo();
 301 };
 302