interface/combobox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        combobox.h
   3 // Purpose:     documentation for wxComboBox class
   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     @seealso
  62     wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
  63 */
  64 class wxComboBox : public wxControlWithItems
  65 {
  66 public:
  67     //@{
  68     /**
  69         Constructor, creating and showing a combobox.
  70
  71         @param parent
  72             Parent window. Must not be @NULL.
  73         @param id
  74             Window identifier. The value wxID_ANY indicates a default value.
  75         @param value
  76             Initial selection string. An empty string indicates no selection.
  77         @param pos
  78             Window position.
  79         @param size
  80             Window size. If wxDefaultSize is specified then the window is
  81         sized
  82             appropriately.
  83         @param n
  84             Number of strings with which to initialise the control.
  85         @param choices
  86             An array of strings with which to initialise the control.
  87         @param style
  88             Window style. See wxComboBox.
  89         @param validator
  90             Window validator.
  91         @param name
  92             Window name.
  93
  94         @see Create(), wxValidator
  95     */
  96     wxComboBox();
  97     wxComboBox(wxWindow* parent, wxWindowID id,
  98                const wxString& value = "",
  99                const wxPoint& pos = wxDefaultPosition,
 100                const wxSize& size = wxDefaultSize,
 101                int n = 0,
 102                const wxString choices[] = NULL,
 103                long style = 0,
 104                const wxValidator& validator = wxDefaultValidator,
 105                const wxString& name = "comboBox");
 106     wxComboBox(wxWindow* parent, wxWindowID id,
 107                const wxString& value,
 108                const wxPoint& pos,
 109                const wxSize& size,
 110                const wxArrayString& choices,
 111                long style = 0,
 112                const wxValidator& validator = wxDefaultValidator,
 113                const wxString& name = "comboBox");
 114     //@}
 115
 116     /**
 117         Destructor, destroying the combobox.
 118     */
 119     ~wxComboBox();
 120
 121     /**
 122         Returns @true if the combobox is editable and there is a text selection to copy
 123         to the clipboard.
 124         Only available on Windows.
 125     */
 126     bool CanCopy() const;
 127
 128     /**
 129         Returns @true if the combobox is editable and there is a text selection to copy
 130         to the clipboard.
 131         Only available on Windows.
 132     */
 133     bool CanCut() const;
 134
 135     /**
 136         Returns @true if the combobox is editable and there is text on the clipboard
 137         that can be pasted into the
 138         text field. Only available on Windows.
 139     */
 140     bool CanPaste() const;
 141
 142     /**
 143         Returns @true if the combobox is editable and the last undo can be redone.
 144         Only available on Windows.
 145     */
 146     bool CanRedo() const;
 147
 148     /**
 149         Returns @true if the combobox is editable and the last edit can be undone.
 150         Only available on Windows.
 151     */
 152     bool CanUndo() const;
 153
 154     /**
 155         Copies the selected text to the clipboard.
 156     */
 157     void Copy();
 158
 159     //@{
 160     /**
 161         Creates the combobox for two-step construction. Derived classes
 162         should call or replace this function. See wxComboBox()
 163         for further details.
 164     */
 165     bool Create(wxWindow* parent, wxWindowID id,
 166                 const wxString& value = "",
 167                 const wxPoint& pos = wxDefaultPosition,
 168                 const wxSize& size = wxDefaultSize,
 169                 int n, const wxString choices[],
 170                 long style = 0,
 171                 const wxValidator& validator = wxDefaultValidator,
 172                 const wxString& name = "comboBox");
 173     bool Create(wxWindow* parent, wxWindowID id,
 174                 const wxString& value,
 175                 const wxPoint& pos,
 176                 const wxSize& size,
 177                 const wxArrayString& choices,
 178                 long style = 0,
 179                 const wxValidator& validator = wxDefaultValidator,
 180                 const wxString& name = "comboBox");
 181     //@}
 182
 183     /**
 184         Copies the selected text to the clipboard and removes the selection.
 185     */
 186     void Cut();
 187
 188     /**
 189         This function does the same things as
 190         wxChoice::GetCurrentSelection and
 191         returns the item currently selected in the dropdown list if it's open or the
 192         same thing as wxControlWithItems::GetSelection otherwise.
 193     */
 194     int GetCurrentSelection() const;
 195
 196     /**
 197         Returns the insertion point for the combobox's text field.
 198         @b Note: Under wxMSW, this function always returns 0 if the combobox
 199         doesn't have the focus.
 200     */
 201     long GetInsertionPoint() const;
 202
 203     /**
 204         Returns the last position in the combobox text field.
 205     */
 206     virtual wxTextPos GetLastPosition() const;
 207
 208     /**
 209         This is the same as wxTextCtrl::GetSelection
 210         for the text control which is part of the combobox. Notice that this is a
 211         different method from wxControlWithItems::GetSelection.
 212         Currently this method is only implemented in wxMSW and wxGTK.
 213     */
 214     void GetSelection(long* from, long* to) const;
 215
 216     /**
 217         Returns the current value in the combobox text field.
 218     */
 219     wxString GetValue() const;
 220
 221     /**
 222         Pastes text from the clipboard to the text field.
 223     */
 224     void Paste();
 225
 226     /**
 227         Redoes the last undo in the text field. Windows only.
 228     */
 229     void Redo();
 230
 231     /**
 232         Removes the text between the two positions in the combobox text field.
 233
 234         @param from
 235             The first position.
 236         @param to
 237             The last position.
 238     */
 239     void Remove(long from, long to);
 240
 241     /**
 242         Replaces the text between two positions with the given text, in the combobox
 243         text field.
 244
 245         @param from
 246             The first position.
 247         @param to
 248             The second position.
 249         @param text
 250             The text to insert.
 251     */
 252     void Replace(long from, long to, const wxString& text);
 253
 254     /**
 255         Sets the insertion point in the combobox text field.
 256
 257         @param pos
 258             The new insertion point.
 259     */
 260     void SetInsertionPoint(long pos);
 261
 262     /**
 263         Sets the insertion point at the end of the combobox text field.
 264     */
 265     void SetInsertionPointEnd();
 266
 267     /**
 268         Selects the text between the two positions, in the combobox text field.
 269
 270         @param from
 271             The first position.
 272         @param to
 273             The second position.
 274     */
 275     void SetSelection(long from, long to);
 276
 277     /**
 278         Sets the text for the combobox text field.
 279         @b NB: For a combobox with @c wxCB_READONLY style the string must be in
 280         the combobox choices list, otherwise the call to SetValue() is ignored.
 281
 282         @param text
 283             The text to set.
 284     */
 285     void SetValue(const wxString& text);
 286
 287     /**
 288         Undoes the last edit in the text field. Windows only.
 289     */
 290     void Undo();
 291 };