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