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 protected:
  87     wxComboControl *m_combo;
  88 };
  89
  90 // ----------------------------------------------------------------------------
  91 // wxComboControl: a combination of a (single line) text control with a button
  92 // opening a popup window which contains the control from which the user can
  93 // choose the value directly.
  94 // ----------------------------------------------------------------------------
  95
  96 class WXDLLEXPORT wxComboControl : public wxControl
  97 {
  98 public:
  99     // construction
 100     wxComboControl()
 101     {
 102         Init();
 103     }
 104
 105     wxComboControl(wxWindow *parent,
 106                    wxWindowID id,
 107                    const wxString& value = wxEmptyString,
 108                    const wxPoint& pos = wxDefaultPosition,
 109                    const wxSize& size = wxDefaultSize,
 110                    long style = 0,
 111                    const wxValidator& validator = wxDefaultValidator,
 112                    const wxString& name = wxComboBoxNameStr)
 113     {
 114         Init();
 115
 116         (void)Create(parent, id, value, pos, size, style, validator, name);
 117     }
 118
 119     bool Create(wxWindow *parent,
 120                 wxWindowID id,
 121                 const wxString& value = wxEmptyString,
 122                 const wxPoint& pos = wxDefaultPosition,
 123                 const wxSize& size = wxDefaultSize,
 124                 long style = 0,
 125                 const wxValidator& validator = wxDefaultValidator,
 126                 const wxString& name = wxComboBoxNameStr);
 127
 128     virtual ~wxComboControl();
 129
 130     // a combo control needs a control for popup window it displays
 131     void SetPopupControl(wxComboPopup *popup);
 132     wxComboPopup *GetPopupControl() const { return m_popup; }
 133
 134     // show/hide popup window
 135     void ShowPopup();
 136     void HidePopup();
 137
 138     // return TRUE if the popup is currently shown
 139     bool IsPopupShown() const { return m_isPopupShown; }
 140
 141     // get the popup window containing the popup control
 142     wxPopupComboWindow *GetPopupWindow() const { return m_winPopup; }
 143
 144     // get the text control which is part of the combobox
 145     wxTextCtrl *GetText() const { return m_text; }
 146
 147     // implementation only from now on
 148     // -------------------------------
 149
 150     // notifications from wxComboPopup (shouldn't be called by anybody else)
 151
 152     // called when the user selects something in the popup: this normally hides
 153     // the popup and sets the text to the new value
 154     virtual void OnSelect(const wxString& value);
 155
 156     // called when the user dismisses the popup
 157     virtual void OnDismiss();
 158
 159     // forward these functions to all subcontrols
 160     virtual bool Enable(bool enable = TRUE);
 161     virtual bool Show(bool show = TRUE);
 162
 163 #if wxUSE_TOOLTIPS
 164     virtual void DoSetToolTip( wxToolTip *tip );
 165 #endif // wxUSE_TOOLTIPS
 166
 167 protected:
 168     // override the base class virtuals involved into geometry calculations
 169     virtual wxSize DoGetBestClientSize() const;
 170     virtual void DoMoveWindow(int x, int y, int width, int height);
 171     virtual void DoSetSize(int x, int y,
 172                            int width, int height,
 173                            int sizeFlags = wxSIZE_AUTO);
 174
 175     // we have our own input handler and our own actions
 176     virtual bool PerformAction(const wxControlAction& action,
 177                                long numArg = 0l,
 178                                const wxString& strArg = wxEmptyString);
 179
 180     // event handlers
 181     void OnKey(wxKeyEvent& event);
 182
 183     // common part of all ctors
 184     void Init();
 185
 186 private:
 187     // the text control and button we show all the time
 188     wxTextCtrl *m_text;
 189     wxButton *m_btn;
 190
 191     // the popup control
 192     wxComboPopup *m_popup;
 193
 194     // and the popup window containing it
 195     wxPopupComboWindow *m_winPopup;
 196
 197     // the height of the combobox popup as calculated in Create()
 198     wxCoord m_heightPopup;
 199
 200     // is the popup window currenty shown?
 201     bool m_isPopupShown;
 202
 203     DECLARE_EVENT_TABLE()
 204 };
 205
 206 // ----------------------------------------------------------------------------
 207 // wxComboBox: a combination of text control and a listbox
 208 // ----------------------------------------------------------------------------
 209
 210 class WXDLLEXPORT wxComboBox : public wxComboControl, public wxComboBoxBase
 211 {
 212 public:
 213     // ctors and such
 214     wxComboBox() { Init(); }
 215
 216     wxComboBox(wxWindow *parent,
 217                wxWindowID id,
 218                const wxString& value = wxEmptyString,
 219                const wxPoint& pos = wxDefaultPosition,
 220                const wxSize& size = wxDefaultSize,
 221                int n = 0,
 222                const wxString *choices = (const wxString *) NULL,
 223                long style = 0,
 224                const wxValidator& validator = wxDefaultValidator,
 225                const wxString& name = wxComboBoxNameStr)
 226     {
 227         Init();
 228
 229         (void)Create(parent, id, value, pos, size, n, choices,
 230                      style, validator, name);
 231     }
 232
 233     bool Create(wxWindow *parent,
 234                 wxWindowID id,
 235                 const wxString& value = wxEmptyString,
 236                 const wxPoint& pos = wxDefaultPosition,
 237                 const wxSize& size = wxDefaultSize,
 238                 int n = 0,
 239                 const wxString choices[] = (const wxString *) NULL,
 240                 long style = 0,
 241                 const wxValidator& validator = wxDefaultValidator,
 242                 const wxString& name = wxComboBoxNameStr);
 243
 244
 245     virtual ~wxComboBox();
 246
 247     // the wxUniversal-specific methods
 248     // --------------------------------
 249
 250     // implement the combobox interface
 251
 252     // wxTextCtrl methods
 253     virtual wxString GetValue() const;
 254     virtual void SetValue(const wxString& value);
 255     virtual void Copy();
 256     virtual void Cut();
 257     virtual void Paste();
 258     virtual void SetInsertionPoint(long pos);
 259     virtual void SetInsertionPointEnd();
 260     virtual long GetInsertionPoint() const;
 261     virtual long GetLastPosition() const;
 262     virtual void Replace(long from, long to, const wxString& value);
 263     virtual void Remove(long from, long to);
 264     virtual void SetSelection(long from, long to);
 265     virtual void SetEditable(bool editable);
 266
 267     // wxControlWithItems methods
 268     virtual void Clear();
 269     virtual void Delete(int n);
 270     virtual int GetCount() const;
 271     virtual wxString GetString(int n) const;
 272     virtual void SetString(int n, const wxString& s);
 273     virtual int FindString(const wxString& s) const;
 274     virtual void Select(int n);
 275     virtual int GetSelection() const;
 276     void SetSelection(int n) { Select(n); }
 277
 278     void SetStringSelection(const wxString& s) {  }
 279
 280     // we have to redefine these functions here to avoid ambiguities in classes
 281     // deriving from us which would arise otherwise because we inherit these
 282     // methods (with different signatures) from both wxItemContainer via
 283     // wxComboBoxBase (with "int n" parameter) and from wxEvtHandler via
 284     // wxControl and wxComboControl (without)
 285     //
 286     // hopefully, a smart compiler can optimize away these simple inline
 287     // wrappers so we don't suffer much from this
 288
 289     void SetClientData(void *data)
 290     {
 291         wxControl::SetClientData(data);
 292     }
 293
 294     void *GetClientData() const
 295     {
 296         return wxControl::GetClientData();
 297     }
 298
 299     void SetClientObject(wxClientData *data)
 300     {
 301         wxControl::SetClientObject(data);
 302     }
 303
 304     wxClientData *GetClientObject() const
 305     {
 306         return wxControl::GetClientObject();
 307     }
 308
 309     void SetClientData(int n, void* clientData)
 310     {
 311         wxItemContainer::SetClientData(n, clientData);
 312     }
 313
 314     void* GetClientData(int n) const
 315     {
 316         return wxItemContainer::GetClientData(n);
 317     }
 318
 319     void SetClientObject(int n, wxClientData* clientData)
 320     {
 321         wxItemContainer::SetClientObject(n, clientData);
 322     }
 323
 324     wxClientData* GetClientObject(int n) const
 325     {
 326         return wxItemContainer::GetClientObject(n);
 327     }
 328
 329 protected:
 330     virtual int DoAppend(const wxString& item);
 331     virtual void DoSetItemClientData(int n, void* clientData);
 332     virtual void* DoGetItemClientData(int n) const;
 333     virtual void DoSetItemClientObject(int n, wxClientData* clientData);
 334     virtual wxClientData* DoGetItemClientObject(int n) const;
 335
 336     // common part of all ctors
 337     void Init();
 338
 339     // get the associated listbox
 340     wxListBox *GetLBox() const { return m_lbox; }
 341
 342 private:
 343     // the popup listbox
 344     wxListBox *m_lbox;
 345
 346     //DECLARE_EVENT_TABLE()
 347     DECLARE_DYNAMIC_CLASS(wxComboBox)
 348 };
 349
 350 // ----------------------------------------------------------------------------
 351 // wxStdComboBoxInputHandler: allows the user to open/close the combo from kbd
 352 // ----------------------------------------------------------------------------
 353
 354 class WXDLLEXPORT wxStdComboBoxInputHandler : public wxStdInputHandler
 355 {
 356 public:
 357     wxStdComboBoxInputHandler(wxInputHandler *inphand);
 358
 359     virtual bool HandleKey(wxInputConsumer *consumer,
 360                            const wxKeyEvent& event,
 361                            bool pressed);
 362 };
 363
 364 #endif // _WX_UNIV_COMBOBOX_H_