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