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 wxWindows
  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 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  40     #pragma interface "univcombobox.h"
  41 #endif
  42
  43 class WXDLLEXPORT wxComboControl;
  44 class WXDLLEXPORT wxListBox;
  45 class WXDLLEXPORT wxPopupComboWindow;
  46 class WXDLLEXPORT wxTextCtrl;
  47 class WXDLLEXPORT wxButton;
  48
  49 // ----------------------------------------------------------------------------
  50 // the actions supported by this control
  51 // ----------------------------------------------------------------------------
  52
  53 // all actions of single line text controls are supported
  54
  55 // popup/dismiss the choice window
  56 #define wxACTION_COMBOBOX_POPUP     _T("popup")
  57 #define wxACTION_COMBOBOX_DISMISS   _T("dismiss")
  58
  59 // choose the next/prev/specified (by numArg) item
  60 #define wxACTION_COMBOBOX_SELECT_NEXT _T("next")
  61 #define wxACTION_COMBOBOX_SELECT_PREV _T("prev")
  62 #define wxACTION_COMBOBOX_SELECT      _T("select")
  63
  64 // ----------------------------------------------------------------------------
  65 // wxComboPopup is the interface which must be implemented by a control to be
  66 // used as a popup by wxComboControl
  67 // ----------------------------------------------------------------------------
  68
  69 class WXDLLEXPORT wxComboPopup
  70 {
  71 public:
  72     wxComboPopup(wxComboControl *combo) { m_combo = combo; }
  73
  74     // we must have an associated control which is subclassed by the combobox
  75     virtual wxControl *GetControl() = 0;
  76
  77     // called before showing the control to set the initial selection - notice
  78     // that the text passed to this method might not correspond to any valid
  79     // item (if the user edited it directly), in which case the method should
  80     // just return FALSE but not emit any errors
  81     virtual bool SetSelection(const wxString& value) = 0;
  82
  83     // called immediately after the control is shown
  84     virtual void OnShow() = 0;
  85
  86     virtual wxCoord GetBestWidth() const {return 0; }
  87
  88 protected:
  89     wxComboControl *m_combo;
  90 };
  91
  92 // ----------------------------------------------------------------------------
  93 // wxComboControl: a combination of a (single line) text control with a button
  94 // opening a popup window which contains the control from which the user can
  95 // choose the value directly.
  96 // ----------------------------------------------------------------------------
  97
  98 class WXDLLEXPORT wxComboControl : public wxControl
  99 {
 100 public:
 101     // construction
 102     wxComboControl()
 103     {
 104         Init();
 105     }
 106
 107     wxComboControl(wxWindow *parent,
 108                    wxWindowID id,
 109                    const wxString& value = wxEmptyString,
 110                    const wxPoint& pos = wxDefaultPosition,
 111                    const wxSize& size = wxDefaultSize,
 112                    long style = 0,
 113                    const wxValidator& validator = wxDefaultValidator,
 114                    const wxString& name = wxComboBoxNameStr)
 115     {
 116         Init();
 117
 118         (void)Create(parent, id, value, pos, size, style, validator, name);
 119     }
 120
 121     bool Create(wxWindow *parent,
 122                 wxWindowID id,
 123                 const wxString& value = wxEmptyString,
 124                 const wxPoint& pos = wxDefaultPosition,
 125                 const wxSize& size = wxDefaultSize,
 126                 long style = 0,
 127                 const wxValidator& validator = wxDefaultValidator,
 128                 const wxString& name = wxComboBoxNameStr);
 129
 130     virtual ~wxComboControl();
 131
 132     // a combo control needs a control for popup window it displays
 133     void SetPopupControl(wxComboPopup *popup);
 134     wxComboPopup *GetPopupControl() const { return m_popup; }
 135
 136     // show/hide popup window
 137     void ShowPopup();
 138     void HidePopup();
 139
 140     // return TRUE if the popup is currently shown
 141     bool IsPopupShown() const { return m_isPopupShown; }
 142
 143     // get the popup window containing the popup control
 144     wxPopupComboWindow *GetPopupWindow() const { return m_winPopup; }
 145
 146     // get the text control which is part of the combobox
 147     wxTextCtrl *GetText() const { return m_text; }
 148
 149     // implementation only from now on
 150     // -------------------------------
 151
 152     // notifications from wxComboPopup (shouldn't be called by anybody else)
 153
 154     // called when the user selects something in the popup: this normally hides
 155     // the popup and sets the text to the new value
 156     virtual void OnSelect(const wxString& value);
 157
 158     // called when the user dismisses the popup
 159     virtual void OnDismiss();
 160
 161     // forward these functions to all subcontrols
 162     virtual bool Enable(bool enable = TRUE);
 163     virtual bool Show(bool show = TRUE);
 164
 165 #if wxUSE_TOOLTIPS
 166     virtual void DoSetToolTip( wxToolTip *tip );
 167 #endif // wxUSE_TOOLTIPS
 168
 169 protected:
 170     // override the base class virtuals involved into geometry calculations
 171     virtual wxSize DoGetBestClientSize() const;
 172     virtual void DoMoveWindow(int x, int y, int width, int height);
 173     virtual void DoSetSize(int x, int y,
 174                            int width, int height,
 175                            int sizeFlags = wxSIZE_AUTO);
 176
 177     // we have our own input handler and our own actions
 178     virtual bool PerformAction(const wxControlAction& action,
 179                                long numArg = 0l,
 180                                const wxString& strArg = wxEmptyString);
 181
 182     // event handlers
 183     void OnKey(wxKeyEvent& event);
 184
 185     // common part of all ctors
 186     void Init();
 187
 188 private:
 189     // the text control and button we show all the time
 190     wxTextCtrl *m_text;
 191     wxButton *m_btn;
 192
 193     // the popup control
 194     wxComboPopup *m_popup;
 195
 196     // and the popup window containing it
 197     wxPopupComboWindow *m_winPopup;
 198
 199     // the height of the combobox popup as calculated in Create()
 200     wxCoord m_heightPopup;
 201
 202     // is the popup window currenty shown?
 203     bool m_isPopupShown;
 204
 205     DECLARE_EVENT_TABLE()
 206 };
 207
 208 // ----------------------------------------------------------------------------
 209 // wxComboBox: a combination of text control and a listbox
 210 // ----------------------------------------------------------------------------
 211
 212 class WXDLLEXPORT wxComboBox : public wxComboControl, public wxComboBoxBase
 213 {
 214 public:
 215     // ctors and such
 216     wxComboBox() { Init(); }
 217
 218     wxComboBox(wxWindow *parent,
 219                wxWindowID id,
 220                const wxString& value = wxEmptyString,
 221                const wxPoint& pos = wxDefaultPosition,
 222                const wxSize& size = wxDefaultSize,
 223                int n = 0,
 224                const wxString choices[] = (const wxString *) NULL,
 225                long style = 0,
 226                const wxValidator& validator = wxDefaultValidator,
 227                const wxString& name = wxComboBoxNameStr)
 228     {
 229         Init();
 230
 231         (void)Create(parent, id, value, pos, size, n, choices,
 232                      style, validator, name);
 233     }
 234     wxComboBox(wxWindow *parent,
 235                wxWindowID id,
 236                const wxString& value,
 237                const wxPoint& pos,
 238                const wxSize& size,
 239                const wxArrayString& choices,
 240                long style = 0,
 241                const wxValidator& validator = wxDefaultValidator,
 242                const wxString& name = wxComboBoxNameStr);
 243
 244     bool Create(wxWindow *parent,
 245                 wxWindowID id,
 246                 const wxString& value = wxEmptyString,
 247                 const wxPoint& pos = wxDefaultPosition,
 248                 const wxSize& size = wxDefaultSize,
 249                 int n = 0,
 250                 const wxString choices[] = (const wxString *) NULL,
 251                 long style = 0,
 252                 const wxValidator& validator = wxDefaultValidator,
 253                 const wxString& name = wxComboBoxNameStr);
 254     bool Create(wxWindow *parent,
 255                 wxWindowID id,
 256                 const wxString& value,
 257                 const wxPoint& pos,
 258                 const wxSize& size,
 259                 const wxArrayString& choices,
 260                 long style = 0,
 261                 const wxValidator& validator = wxDefaultValidator,
 262                 const wxString& name = wxComboBoxNameStr);
 263
 264     virtual ~wxComboBox();
 265
 266     // the wxUniversal-specific methods
 267     // --------------------------------
 268
 269     // implement the combobox interface
 270
 271     // wxTextCtrl methods
 272     virtual wxString GetValue() const;
 273     virtual void SetValue(const wxString& value);
 274     virtual void Copy();
 275     virtual void Cut();
 276     virtual void Paste();
 277     virtual void SetInsertionPoint(long pos);
 278     virtual void SetInsertionPointEnd();
 279     virtual long GetInsertionPoint() const;
 280     virtual long GetLastPosition() const;
 281     virtual void Replace(long from, long to, const wxString& value);
 282     virtual void Remove(long from, long to);
 283     virtual void SetSelection(long from, long to);
 284     virtual void SetEditable(bool editable);
 285
 286     // wxControlWithItems methods
 287     virtual void Clear();
 288     virtual void Delete(int n);
 289     virtual int GetCount() const;
 290     virtual wxString GetString(int n) const;
 291     virtual void SetString(int n, const wxString& s);
 292     virtual int FindString(const wxString& s) const;
 293     virtual void Select(int n);
 294     virtual int GetSelection() const;
 295     void SetSelection(int n) { Select(n); }
 296
 297     void SetStringSelection(const wxString& WXUNUSED(s)) {  }
 298
 299     wxCONTROL_ITEMCONTAINER_CLIENTDATAOBJECT_RECAST
 300
 301 protected:
 302     virtual int DoAppend(const wxString& item);
 303     virtual int DoInsert(const wxString& item, int pos);
 304     virtual void DoSetItemClientData(int n, void* clientData);
 305     virtual void* DoGetItemClientData(int n) const;
 306     virtual void DoSetItemClientObject(int n, wxClientData* clientData);
 307     virtual wxClientData* DoGetItemClientObject(int n) const;
 308
 309     // common part of all ctors
 310     void Init();
 311
 312     // get the associated listbox
 313     wxListBox *GetLBox() const { return m_lbox; }
 314
 315 private:
 316     // the popup listbox
 317     wxListBox *m_lbox;
 318
 319     //DECLARE_EVENT_TABLE()
 320     DECLARE_DYNAMIC_CLASS(wxComboBox)
 321 };
 322
 323 // ----------------------------------------------------------------------------
 324 // wxStdComboBoxInputHandler: allows the user to open/close the combo from kbd
 325 // ----------------------------------------------------------------------------
 326
 327 class WXDLLEXPORT wxStdComboBoxInputHandler : public wxStdInputHandler
 328 {
 329 public:
 330     wxStdComboBoxInputHandler(wxInputHandler *inphand);
 331
 332     virtual bool HandleKey(wxInputConsumer *consumer,
 333                            const wxKeyEvent& event,
 334                            bool pressed);
 335 };
 336
 337 #endif // _WX_UNIV_COMBOBOX_H_