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