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 #ifdef __GNUG__
  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
 235     bool Create(wxWindow *parent,
 236                 wxWindowID id,
 237                 const wxString& value = wxEmptyString,
 238                 const wxPoint& pos = wxDefaultPosition,
 239                 const wxSize& size = wxDefaultSize,
 240                 int n = 0,
 241                 const wxString choices[] = (const wxString *) NULL,
 242                 long style = 0,
 243                 const wxValidator& validator = wxDefaultValidator,
 244                 const wxString& name = wxComboBoxNameStr);
 245
 246
 247     virtual ~wxComboBox();
 248
 249     // the wxUniversal-specific methods
 250     // --------------------------------
 251
 252     // implement the combobox interface
 253
 254     // wxTextCtrl methods
 255     virtual wxString GetValue() const;
 256     virtual void SetValue(const wxString& value);
 257     virtual void Copy();
 258     virtual void Cut();
 259     virtual void Paste();
 260     virtual void SetInsertionPoint(long pos);
 261     virtual void SetInsertionPointEnd();
 262     virtual long GetInsertionPoint() const;
 263     virtual long GetLastPosition() const;
 264     virtual void Replace(long from, long to, const wxString& value);
 265     virtual void Remove(long from, long to);
 266     virtual void SetSelection(long from, long to);
 267     virtual void SetEditable(bool editable);
 268
 269     // wxControlWithItems methods
 270     virtual void Clear();
 271     virtual void Delete(int n);
 272     virtual int GetCount() const;
 273     virtual wxString GetString(int n) const;
 274     virtual void SetString(int n, const wxString& s);
 275     virtual int FindString(const wxString& s) const;
 276     virtual void Select(int n);
 277     virtual int GetSelection() const;
 278     void SetSelection(int n) { Select(n); }
 279
 280     void SetStringSelection(const wxString& WXUNUSED(s)) {  }
 281
 282     // we have to redefine these functions here to avoid ambiguities in classes
 283     // deriving from us which would arise otherwise because we inherit these
 284     // methods (with different signatures) from both wxItemContainer via
 285     // wxComboBoxBase (with "int n" parameter) and from wxEvtHandler via
 286     // wxControl and wxComboControl (without)
 287     //
 288     // hopefully, a smart compiler can optimize away these simple inline
 289     // wrappers so we don't suffer much from this
 290
 291     void SetClientData(void *data)
 292     {
 293         wxControl::SetClientData(data);
 294     }
 295
 296     void *GetClientData() const
 297     {
 298         return wxControl::GetClientData();
 299     }
 300
 301     void SetClientObject(wxClientData *data)
 302     {
 303         wxControl::SetClientObject(data);
 304     }
 305
 306     wxClientData *GetClientObject() const
 307     {
 308         return wxControl::GetClientObject();
 309     }
 310
 311     void SetClientData(int n, void* clientData)
 312     {
 313         wxItemContainer::SetClientData(n, clientData);
 314     }
 315
 316     void* GetClientData(int n) const
 317     {
 318         return wxItemContainer::GetClientData(n);
 319     }
 320
 321     void SetClientObject(int n, wxClientData* clientData)
 322     {
 323         wxItemContainer::SetClientObject(n, clientData);
 324     }
 325
 326     wxClientData* GetClientObject(int n) const
 327     {
 328         return wxItemContainer::GetClientObject(n);
 329     }
 330
 331 protected:
 332     virtual int DoAppend(const wxString& item);
 333     virtual int DoInsert(const wxString& item, int pos);
 334     virtual void DoSetItemClientData(int n, void* clientData);
 335     virtual void* DoGetItemClientData(int n) const;
 336     virtual void DoSetItemClientObject(int n, wxClientData* clientData);
 337     virtual wxClientData* DoGetItemClientObject(int n) const;
 338
 339     // common part of all ctors
 340     void Init();
 341
 342     // get the associated listbox
 343     wxListBox *GetLBox() const { return m_lbox; }
 344
 345 private:
 346     // the popup listbox
 347     wxListBox *m_lbox;
 348
 349     //DECLARE_EVENT_TABLE()
 350     DECLARE_DYNAMIC_CLASS(wxComboBox)
 351 };
 352
 353 // ----------------------------------------------------------------------------
 354 // wxStdComboBoxInputHandler: allows the user to open/close the combo from kbd
 355 // ----------------------------------------------------------------------------
 356
 357 class WXDLLEXPORT wxStdComboBoxInputHandler : public wxStdInputHandler
 358 {
 359 public:
 360     wxStdComboBoxInputHandler(wxInputHandler *inphand);
 361
 362     virtual bool HandleKey(wxInputConsumer *consumer,
 363                            const wxKeyEvent& event,
 364                            bool pressed);
 365 };
 366
 367 #endif // _WX_UNIV_COMBOBOX_H_