include/wx/univ/combobox.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/univ/combobox.h
   3 // Purpose:     the universal combobox
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     30.08.00
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2000 SciTech Software, Inc. (www.scitechsoft.com)
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13    A few words about all the classes defined in this file are probably in
  14    order: why do we need extra wxComboControl and wxComboPopup classes?
  15
  16    This is because a traditional combobox is a combination of a text control
  17    (with a button allowing to open the pop down list) with a listbox and
  18    wxComboBox class is exactly such control, however we want to also have other
  19    combinations - in fact, we want to allow anything at all to be used as pop
  20    down list, not just a wxListBox.
  21
  22    So we define a base wxComboControl which can use any control as pop down
  23    list and wxComboBox deriving from it which implements the standard wxWidgets
  24    combobox API. wxComboControl needs to be told somehow which control to use
  25    and this is done by SetPopupControl(). However, we need something more than
  26    just a wxControl in this method as, for example, we need to call
  27    SetSelection("initial text value") and wxControl doesn't have such method.
  28    So we also need a wxComboPopup which is just a very simple interface which
  29    must be implemented by a control to be usable as a popup.
  30
  31    We couldn't derive wxComboPopup from wxControl as this would make it
  32    impossible to have a class deriving from both wxListBx and from it, so
  33    instead it is just a mix-in.
  34  */
  35
  36 #ifndef _WX_UNIV_COMBOBOX_H_
  37 #define _WX_UNIV_COMBOBOX_H_
  38
  39 class WXDLLEXPORT wxComboControl;
  40 class WXDLLEXPORT wxListBox;
  41 class WXDLLEXPORT wxPopupComboWindow;
  42 class WXDLLEXPORT wxTextCtrl;
  43 class WXDLLEXPORT wxButton;
  44
  45 // ----------------------------------------------------------------------------
  46 // the actions supported by this control
  47 // ----------------------------------------------------------------------------
  48
  49 // all actions of single line text controls are supported
  50
  51 // popup/dismiss the choice window
  52 #define wxACTION_COMBOBOX_POPUP     _T("popup")
  53 #define wxACTION_COMBOBOX_DISMISS   _T("dismiss")
  54
  55 // choose the next/prev/specified (by numArg) item
  56 #define wxACTION_COMBOBOX_SELECT_NEXT _T("next")
  57 #define wxACTION_COMBOBOX_SELECT_PREV _T("prev")
  58 #define wxACTION_COMBOBOX_SELECT      _T("select")
  59
  60 // ----------------------------------------------------------------------------
  61 // wxComboPopup is the interface which must be implemented by a control to be
  62 // used as a popup by wxComboControl
  63 // ----------------------------------------------------------------------------
  64
  65 class WXDLLEXPORT wxComboPopup
  66 {
  67 public:
  68     wxComboPopup(wxComboControl *combo) { m_combo = combo; }
  69     virtual ~wxComboPopup() {}
  70
  71     // we must have an associated control which is subclassed by the combobox
  72     virtual wxControl *GetControl() = 0;
  73
  74     // called before showing the control to set the initial selection - notice
  75     // that the text passed to this method might not correspond to any valid
  76     // item (if the user edited it directly), in which case the method should
  77     // just return false but not emit any errors
  78     virtual bool SetSelection(const wxString& value) = 0;
  79
  80     // called immediately after the control is shown
  81     virtual void OnShow() = 0;
  82
  83     virtual wxCoord GetBestWidth() const {return 0; }
  84
  85 protected:
  86     wxComboControl *m_combo;
  87 };
  88
  89 // ----------------------------------------------------------------------------
  90 // wxComboControl: a combination of a (single line) text control with a button
  91 // opening a popup window which contains the control from which the user can
  92 // choose the value directly.
  93 // ----------------------------------------------------------------------------
  94
  95 class WXDLLEXPORT wxComboControl : public wxControl
  96 {
  97 public:
  98     // construction
  99     wxComboControl()
 100     {
 101         Init();
 102     }
 103
 104     wxComboControl(wxWindow *parent,
 105                    wxWindowID id,
 106                    const wxString& value = wxEmptyString,
 107                    const wxPoint& pos = wxDefaultPosition,
 108                    const wxSize& size = wxDefaultSize,
 109                    long style = 0,
 110                    const wxValidator& validator = wxDefaultValidator,
 111                    const wxString& name = wxComboBoxNameStr)
 112     {
 113         Init();
 114
 115         (void)Create(parent, id, value, pos, size, style, validator, name);
 116     }
 117
 118     bool Create(wxWindow *parent,
 119                 wxWindowID id,
 120                 const wxString& value = wxEmptyString,
 121                 const wxPoint& pos = wxDefaultPosition,
 122                 const wxSize& size = wxDefaultSize,
 123                 long style = 0,
 124                 const wxValidator& validator = wxDefaultValidator,
 125                 const wxString& name = wxComboBoxNameStr);
 126
 127     virtual ~wxComboControl();
 128
 129     // a combo control needs a control for popup window it displays
 130     void SetPopupControl(wxComboPopup *popup);
 131     wxComboPopup *GetPopupControl() const { return m_popup; }
 132
 133     // show/hide popup window
 134     void ShowPopup();
 135     void HidePopup();
 136
 137     // return true if the popup is currently shown
 138     bool IsPopupShown() const { return m_isPopupShown; }
 139
 140     // get the popup window containing the popup control
 141     wxPopupComboWindow *GetPopupWindow() const { return m_winPopup; }
 142
 143     // get the text control which is part of the combobox
 144     wxTextCtrl *GetText() const { return m_text; }
 145
 146     // implementation only from now on
 147     // -------------------------------
 148
 149     // notifications from wxComboPopup (shouldn't be called by anybody else)
 150
 151     // called when the user selects something in the popup: this normally hides
 152     // the popup and sets the text to the new value
 153     virtual void OnSelect(const wxString& value);
 154
 155     // called when the user dismisses the popup
 156     virtual void OnDismiss();
 157
 158     // forward these functions to all subcontrols
 159     virtual bool Enable(bool enable = true);
 160     virtual bool Show(bool show = true);
 161
 162 #if wxUSE_TOOLTIPS
 163     virtual void DoSetToolTip( wxToolTip *tip );
 164 #endif // wxUSE_TOOLTIPS
 165
 166 protected:
 167     // override the base class virtuals involved into geometry calculations
 168     virtual wxSize DoGetBestClientSize() const;
 169     virtual void DoMoveWindow(int x, int y, int width, int height);
 170     virtual void DoSetSize(int x, int y,
 171                            int width, int height,
 172                            int sizeFlags = wxSIZE_AUTO);
 173
 174     // we have our own input handler and our own actions
 175     virtual bool PerformAction(const wxControlAction& action,
 176                                long numArg = 0l,
 177                                const wxString& strArg = wxEmptyString);
 178
 179     // event handlers
 180     void OnKey(wxKeyEvent& event);
 181
 182     // common part of all ctors
 183     void Init();
 184
 185 private:
 186     // the text control and button we show all the time
 187     wxTextCtrl *m_text;
 188     wxButton *m_btn;
 189
 190     // the popup control
 191     wxComboPopup *m_popup;
 192
 193     // and the popup window containing it
 194     wxPopupComboWindow *m_winPopup;
 195
 196     // the height of the combobox popup as calculated in Create()
 197     wxCoord m_heightPopup;
 198
 199     // is the popup window currenty shown?
 200     bool m_isPopupShown;
 201
 202     DECLARE_EVENT_TABLE()
 203 };
 204
 205 // ----------------------------------------------------------------------------
 206 // wxComboBox: a combination of text control and a listbox
 207 // ----------------------------------------------------------------------------
 208
 209 class WXDLLEXPORT wxComboBox : public wxComboControl, public wxComboBoxBase
 210 {
 211 public:
 212     // ctors and such
 213     wxComboBox() { Init(); }
 214
 215     wxComboBox(wxWindow *parent,
 216                wxWindowID id,
 217                const wxString& value = wxEmptyString,
 218                const wxPoint& pos = wxDefaultPosition,
 219                const wxSize& size = wxDefaultSize,
 220                int n = 0,
 221                const wxString choices[] = (const wxString *) NULL,
 222                long style = 0,
 223                const wxValidator& validator = wxDefaultValidator,
 224                const wxString& name = wxComboBoxNameStr)
 225     {
 226         Init();
 227
 228         (void)Create(parent, id, value, pos, size, n, choices,
 229                      style, validator, name);
 230     }
 231     wxComboBox(wxWindow *parent,
 232                wxWindowID id,
 233                const wxString& value,
 234                const wxPoint& pos,
 235                const wxSize& size,
 236                const wxArrayString& choices,
 237                long style = 0,
 238                const wxValidator& validator = wxDefaultValidator,
 239                const wxString& name = wxComboBoxNameStr);
 240
 241     bool Create(wxWindow *parent,
 242                 wxWindowID id,
 243                 const wxString& value = wxEmptyString,
 244                 const wxPoint& pos = wxDefaultPosition,
 245                 const wxSize& size = wxDefaultSize,
 246                 int n = 0,
 247                 const wxString choices[] = (const wxString *) NULL,
 248                 long style = 0,
 249                 const wxValidator& validator = wxDefaultValidator,
 250                 const wxString& name = wxComboBoxNameStr);
 251     bool Create(wxWindow *parent,
 252                 wxWindowID id,
 253                 const wxString& value,
 254                 const wxPoint& pos,
 255                 const wxSize& size,
 256                 const wxArrayString& choices,
 257                 long style = 0,
 258                 const wxValidator& validator = wxDefaultValidator,
 259                 const wxString& name = wxComboBoxNameStr);
 260
 261     virtual ~wxComboBox();
 262
 263     // the wxUniversal-specific methods
 264     // --------------------------------
 265
 266     // implement the combobox interface
 267
 268     // wxTextCtrl methods
 269     virtual wxString GetValue() const;
 270     virtual void SetValue(const wxString& value);
 271     virtual void Copy();
 272     virtual void Cut();
 273     virtual void Paste();
 274     virtual void SetInsertionPoint(long pos);
 275     virtual void SetInsertionPointEnd();
 276     virtual long GetInsertionPoint() const;
 277     virtual wxTextPos GetLastPosition() const;
 278     virtual void Replace(long from, long to, const wxString& value);
 279     virtual void Remove(long from, long to);
 280     virtual void SetSelection(long from, long to);
 281     virtual void SetEditable(bool editable);
 282     virtual bool IsEditable() const;
 283
 284     virtual void Undo();
 285     virtual void Redo();
 286     virtual void SelectAll();
 287
 288     virtual bool CanCopy() const;
 289     virtual bool CanCut() const;
 290     virtual bool CanPaste() const;
 291     virtual bool CanUndo() const;
 292     virtual bool CanRedo() const;
 293
 294     // wxControlWithItems methods
 295     virtual void Clear();
 296     virtual void Delete(int n);
 297     virtual int GetCount() const;
 298     virtual wxString GetString(int n) const;
 299     virtual void SetString(int n, const wxString& s);
 300     virtual int FindString(const wxString& s, bool bCase = false) const;
 301     virtual void SetSelection(int n);
 302     virtual int GetSelection() const;
 303
 304     wxCONTROL_ITEMCONTAINER_CLIENTDATAOBJECT_RECAST
 305
 306 protected:
 307     virtual int DoAppend(const wxString& item);
 308     virtual int DoInsert(const wxString& item, int pos);
 309     virtual void DoSetItemClientData(int n, void* clientData);
 310     virtual void* DoGetItemClientData(int n) const;
 311     virtual void DoSetItemClientObject(int n, wxClientData* clientData);
 312     virtual wxClientData* DoGetItemClientObject(int n) const;
 313
 314     // common part of all ctors
 315     void Init();
 316
 317     // get the associated listbox
 318     wxListBox *GetLBox() const { return m_lbox; }
 319
 320 private:
 321     // the popup listbox
 322     wxListBox *m_lbox;
 323
 324     //DECLARE_EVENT_TABLE()
 325     DECLARE_DYNAMIC_CLASS(wxComboBox)
 326 };
 327
 328 // ----------------------------------------------------------------------------
 329 // wxStdComboBoxInputHandler: allows the user to open/close the combo from kbd
 330 // ----------------------------------------------------------------------------
 331
 332 class WXDLLEXPORT wxStdComboBoxInputHandler : public wxStdInputHandler
 333 {
 334 public:
 335     wxStdComboBoxInputHandler(wxInputHandler *inphand);
 336
 337     virtual bool HandleKey(wxInputConsumer *consumer,
 338                            const wxKeyEvent& event,
 339                            bool pressed);
 340 };
 341
 342 #endif // _WX_UNIV_COMBOBOX_H_