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