include/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/propgrid/editors.h
   3 // Purpose:     wxPropertyGrid editors
   4 // Author:      Jaakko Salli
   5 // Modified by:
   6 // Created:     2007-04-14
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Jaakko Salli
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_PROPGRID_EDITORS_H_
  13 #define _WX_PROPGRID_EDITORS_H_
  14
  15 #if wxUSE_PROPGRID
  16
  17 // -----------------------------------------------------------------------
  18 // wxPGWindowList contains list of editor windows returned by CreateControls.
  19
  20 class wxPGWindowList
  21 {
  22 public:
  23     wxPGWindowList()
  24     {
  25         m_primary = m_secondary = NULL;
  26     }
  27
  28     void SetSecondary( wxWindow* secondary ) { m_secondary = secondary; }
  29
  30     wxWindow*   m_primary;
  31     wxWindow*   m_secondary;
  32
  33 #ifndef SWIG
  34     wxPGWindowList( wxWindow* a )
  35     {
  36         m_primary = a;
  37         m_secondary = NULL;
  38     };
  39     wxPGWindowList( wxWindow* a, wxWindow* b )
  40     {
  41         m_primary = a;
  42         m_secondary = b;
  43     };
  44 #endif
  45 };
  46
  47 // -----------------------------------------------------------------------
  48
  49 /** @class wxPGEditor
  50
  51     Base class for custom wxPropertyGrid editors.
  52
  53     @remarks
  54     - Names of builtin property editors are: TextCtrl, Choice,
  55       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  56       editors include SpinCtrl and DatePickerCtrl, but using them requires
  57       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  58
  59     - Pointer to builtin editor is available as wxPGEditor_EditorName
  60       (eg. wxPGEditor_TextCtrl).
  61
  62     - To add new editor you need to register it first using static function
  63       wxPropertyGrid::RegisterEditorClass(), with code like this:
  64         @code
  65             wxPGEditor *editorPointer = wxPropertyGrid::RegisterEditorClass(
  66                                             new MyEditorClass(), "MyEditor");
  67         @endcode
  68       After that, wxPropertyGrid will take ownership of the given object, but
  69       you should still store editorPointer somewhere, so you can pass it to
  70       wxPGProperty::SetEditor(), or return it from
  71       wxPGEditor::DoGetEditorClass().
  72
  73     @library{wxpropgrid}
  74     @category{propgrid}
  75 */
  76 class WXDLLIMPEXP_PROPGRID wxPGEditor : public wxObject
  77 {
  78     DECLARE_ABSTRACT_CLASS(wxPGEditor)
  79 public:
  80
  81     /** Constructor. */
  82     wxPGEditor()
  83         : wxObject()
  84     {
  85         m_clientData = NULL;
  86     }
  87
  88     /** Destructor. */
  89     virtual ~wxPGEditor();
  90
  91     /**
  92         Returns pointer to the name of the editor. For example,
  93         wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
  94         your custom editor by string name, then you do not need to implement
  95         this function.
  96     */
  97     virtual wxString GetName() const;
  98
  99     /**
 100         Instantiates editor controls.
 101
 102         @param propgrid
 103             wxPropertyGrid to which the property belongs (use as parent for
 104             control).
 105         @param property
 106             Property for which this method is called.
 107         @param pos
 108             Position, inside wxPropertyGrid, to create control(s) to.
 109         @param size
 110             Initial size for control(s).
 111
 112         @remarks
 113         - Primary control shall use id wxPG_SUBID1, and secondary (button)
 114           control shall use wxPG_SUBID2.
 115         - Unlike in previous version of wxPropertyGrid, it is no longer
 116           necessary to call wxEvtHandler::Connect() for interesting editor
 117           events. Instead, all events from control are now automatically
 118           forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent().
 119     */
 120     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 121                                           wxPGProperty* property,
 122                                           const wxPoint& pos,
 123                                           const wxSize& size) const = 0;
 124
 125     /** Loads value from property to the control. */
 126     virtual void UpdateControl( wxPGProperty* property,
 127                                 wxWindow* ctrl ) const = 0;
 128
 129     /**
 130         Used to get the renderer to draw the value with when the control is
 131         hidden.
 132
 133         Default implementation returns g_wxPGDefaultRenderer.
 134     */
 135     //virtual wxPGCellRenderer* GetCellRenderer() const;
 136
 137     /** Draws value for given property.
 138     */
 139     virtual void DrawValue( wxDC& dc,
 140                             const wxRect& rect,
 141                             wxPGProperty* property,
 142                             const wxString& text ) const;
 143
 144     /** Handles events. Returns true if value in control was modified
 145         (see wxPGProperty::OnEvent for more information).
 146
 147         @remarks wxPropertyGrid will automatically unfocus the editor when
 148                 wxEVT_COMMAND_TEXT_ENTER is received and when it results in
 149                 property value being modified. This happens regardless of
 150                 editor type (ie. behavior is same for any wxTextCtrl and
 151                 wxComboBox based editor).
 152     */
 153     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 154         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 155
 156 #if !defined(SWIG) || defined(CREATE_VCW)
 157     /** Returns value from control, via parameter 'variant'.
 158         Usually ends up calling property's StringToValue or IntToValue.
 159         Returns true if value was different.
 160     */
 161     virtual bool GetValueFromControl( wxVariant& variant,
 162                                       wxPGProperty* property,
 163                                       wxWindow* ctrl ) const;
 164 #endif
 165
 166     /** Sets value in control to unspecified. */
 167     virtual void SetValueToUnspecified( wxPGProperty* property,
 168                                         wxWindow* ctrl ) const = 0;
 169
 170     /** Sets control's value specifically from string. */
 171     virtual void SetControlStringValue( wxPGProperty* property,
 172                                         wxWindow* ctrl,
 173                                         const wxString& txt ) const;
 174
 175     /** Sets control's value specifically from int (applies to choice etc.). */
 176     virtual void SetControlIntValue( wxPGProperty* property,
 177                                      wxWindow* ctrl,
 178                                      int value ) const;
 179
 180     /** Inserts item to existing control. Index -1 means appending.
 181         Default implementation does nothing. Returns index of item added.
 182     */
 183     virtual int InsertItem( wxWindow* ctrl,
 184                             const wxString& label,
 185                             int index ) const;
 186
 187     /** Deletes item from existing control.
 188         Default implementation does nothing.
 189     */
 190     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 191
 192     /** Extra processing when control gains focus. For example, wxTextCtrl
 193         based controls should select all text.
 194     */
 195     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 196
 197     /** Returns true if control itself can contain the custom image. Default is
 198         to return false.
 199     */
 200     virtual bool CanContainCustomImage() const;
 201
 202     //
 203     // This member is public so scripting language bindings
 204     // wrapper code can access it freely.
 205     void*       m_clientData;
 206 };
 207
 208
 209 #define WX_PG_IMPLEMENT_INTERNAL_EDITOR_CLASS(EDITOR,CLASSNAME,BASECLASS) \
 210 IMPLEMENT_DYNAMIC_CLASS(CLASSNAME, BASECLASS) \
 211 wxString CLASSNAME::GetName() const \
 212 { \
 213     return wxS(#EDITOR); \
 214 } \
 215 wxPGEditor* wxPGEditor_##EDITOR = NULL;
 216
 217
 218 //
 219 // Following are the built-in editor classes.
 220 //
 221
 222 class WXDLLIMPEXP_PROPGRID wxPGTextCtrlEditor : public wxPGEditor
 223 {
 224     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlEditor)
 225 public:
 226     wxPGTextCtrlEditor() {}
 227     virtual ~wxPGTextCtrlEditor();
 228
 229     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 230                                           wxPGProperty* property,
 231                                           const wxPoint& pos,
 232                                           const wxSize& size) const;
 233     virtual void UpdateControl( wxPGProperty* property,
 234                                 wxWindow* ctrl ) const;
 235     virtual bool OnEvent( wxPropertyGrid* propgrid,
 236                           wxPGProperty* property,
 237                           wxWindow* primaryCtrl,
 238                           wxEvent& event ) const;
 239     virtual bool GetValueFromControl( wxVariant& variant,
 240                                       wxPGProperty* property,
 241                                       wxWindow* ctrl ) const;
 242     virtual void SetValueToUnspecified( wxPGProperty* property,
 243                                         wxWindow* ctrl ) const;
 244
 245     virtual wxString GetName() const;
 246
 247     //virtual wxPGCellRenderer* GetCellRenderer() const;
 248     virtual void SetControlStringValue( wxPGProperty* property,
 249                                         wxWindow* ctrl,
 250                                         const wxString& txt ) const;
 251     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 252
 253     // Provided so that, for example, ComboBox editor can use the same code
 254     // (multiple inheritance would get way too messy).
 255     static bool OnTextCtrlEvent( wxPropertyGrid* propgrid,
 256                                  wxPGProperty* property,
 257                                  wxWindow* ctrl,
 258                                  wxEvent& event );
 259
 260     static bool GetTextCtrlValueFromControl( wxVariant& variant,
 261                                              wxPGProperty* property,
 262                                              wxWindow* ctrl );
 263
 264 };
 265
 266
 267 class WXDLLIMPEXP_PROPGRID wxPGChoiceEditor : public wxPGEditor
 268 {
 269     DECLARE_DYNAMIC_CLASS(wxPGChoiceEditor)
 270 public:
 271     wxPGChoiceEditor() {}
 272     virtual ~wxPGChoiceEditor();
 273
 274     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 275                                           wxPGProperty* property,
 276                                           const wxPoint& pos,
 277                                           const wxSize& size) const;
 278     virtual void UpdateControl( wxPGProperty* property,
 279                                 wxWindow* ctrl ) const;
 280     virtual bool OnEvent( wxPropertyGrid* propgrid,
 281                           wxPGProperty* property,
 282                           wxWindow* primaryCtrl,
 283                           wxEvent& event ) const;
 284     virtual bool GetValueFromControl( wxVariant& variant,
 285                                       wxPGProperty* property,
 286                                       wxWindow* ctrl ) const;
 287     virtual void SetValueToUnspecified( wxPGProperty* property,
 288                                         wxWindow* ctrl ) const;
 289     virtual wxString GetName() const;
 290
 291     virtual void SetControlIntValue( wxPGProperty* property,
 292                                      wxWindow* ctrl,
 293                                      int value ) const;
 294     virtual void SetControlStringValue( wxPGProperty* property,
 295                                         wxWindow* ctrl,
 296                                         const wxString& txt ) const;
 297
 298     virtual int InsertItem( wxWindow* ctrl,
 299                             const wxString& label,
 300                             int index ) const;
 301     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 302     virtual bool CanContainCustomImage() const;
 303
 304     // CreateControls calls this with CB_READONLY in extraStyle
 305     wxWindow* CreateControlsBase( wxPropertyGrid* propgrid,
 306                                   wxPGProperty* property,
 307                                   const wxPoint& pos,
 308                                   const wxSize& sz,
 309                                   long extraStyle ) const;
 310
 311 };
 312
 313
 314 class WXDLLIMPEXP_PROPGRID wxPGComboBoxEditor : public wxPGChoiceEditor
 315 {
 316     DECLARE_DYNAMIC_CLASS(wxPGComboBoxEditor)
 317 public:
 318     wxPGComboBoxEditor() {}
 319     virtual ~wxPGComboBoxEditor();
 320
 321     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 322                                           wxPGProperty* property,
 323                                           const wxPoint& pos,
 324                                           const wxSize& size) const;
 325
 326     virtual wxString GetName() const;
 327
 328     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const;
 329
 330     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 331         wxWindow* ctrl, wxEvent& event ) const;
 332
 333     virtual bool GetValueFromControl( wxVariant& variant,
 334                                       wxPGProperty* property,
 335                                       wxWindow* ctrl ) const;
 336
 337     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 338
 339 };
 340
 341
 342 // Exclude classes from being able to be derived from in wxPython bindings
 343 #ifndef SWIG
 344
 345 class WXDLLIMPEXP_PROPGRID wxPGChoiceAndButtonEditor : public wxPGChoiceEditor
 346 {
 347 public:
 348     wxPGChoiceAndButtonEditor() {}
 349     virtual ~wxPGChoiceAndButtonEditor();
 350     virtual wxString GetName() const;
 351
 352     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 353                                           wxPGProperty* property,
 354                                           const wxPoint& pos,
 355                                           const wxSize& size) const;
 356
 357     DECLARE_DYNAMIC_CLASS(wxPGChoiceAndButtonEditor)
 358 };
 359
 360 class WXDLLIMPEXP_PROPGRID
 361 wxPGTextCtrlAndButtonEditor : public wxPGTextCtrlEditor
 362 {
 363 public:
 364     wxPGTextCtrlAndButtonEditor() {}
 365     virtual ~wxPGTextCtrlAndButtonEditor();
 366     virtual wxString GetName() const;
 367
 368     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 369                                           wxPGProperty* property,
 370                                           const wxPoint& pos,
 371                                           const wxSize& size) const;
 372
 373     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlAndButtonEditor)
 374 };
 375
 376 #endif  // !SWIG
 377
 378
 379 #if wxPG_INCLUDE_CHECKBOX
 380
 381 //
 382 // Use custom check box code instead of native control
 383 // for cleaner (ie. more integrated) look.
 384 //
 385 class WXDLLIMPEXP_PROPGRID wxPGCheckBoxEditor : public wxPGEditor
 386 {
 387     DECLARE_DYNAMIC_CLASS(wxPGCheckBoxEditor)
 388 public:
 389     wxPGCheckBoxEditor() {}
 390     virtual ~wxPGCheckBoxEditor();
 391
 392     virtual wxString GetName() const;
 393     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 394                                           wxPGProperty* property,
 395                                           const wxPoint& pos,
 396                                           const wxSize& size) const;
 397     virtual void UpdateControl( wxPGProperty* property,
 398                                 wxWindow* ctrl ) const;
 399     virtual bool OnEvent( wxPropertyGrid* propgrid,
 400                           wxPGProperty* property,
 401                           wxWindow* primaryCtrl,
 402                           wxEvent& event ) const;
 403     virtual bool GetValueFromControl( wxVariant& variant,
 404                                       wxPGProperty* property,
 405                                       wxWindow* ctrl ) const;
 406     virtual void SetValueToUnspecified( wxPGProperty* property,
 407                                         wxWindow* ctrl ) const;
 408
 409     virtual void DrawValue( wxDC& dc,
 410                             const wxRect& rect,
 411                             wxPGProperty* property,
 412                             const wxString& text ) const;
 413     //virtual wxPGCellRenderer* GetCellRenderer() const;
 414
 415     virtual void SetControlIntValue( wxPGProperty* property,
 416                                      wxWindow* ctrl,
 417                                      int value ) const;
 418 };
 419
 420 #endif
 421
 422
 423 // -----------------------------------------------------------------------
 424 // Editor class registeration macro (mostly for internal use)
 425
 426 #define wxPGRegisterEditorClass(EDITOR) \
 427     if ( wxPGEditor_##EDITOR == NULL ) \
 428     { \
 429         wxPGEditor_##EDITOR = wxPropertyGrid::RegisterEditorClass( \
 430                 new wxPG##EDITOR##Editor ); \
 431     }
 432
 433 // -----------------------------------------------------------------------
 434
 435 /** @class wxPGEditorDialogAdapter
 436
 437     Derive a class from this to adapt an existing editor dialog or function to
 438     be used when editor button of a property is pushed.
 439
 440     You only need to derive class and implement DoShowDialog() to create and
 441     show the dialog, and finally submit the value returned by the dialog
 442     via SetValue().
 443
 444     @library{wxpropgrid}
 445     @category{propgrid}
 446 */
 447 class WXDLLIMPEXP_PROPGRID wxPGEditorDialogAdapter : public wxObject
 448 {
 449     DECLARE_ABSTRACT_CLASS(wxPGEditorDialogAdapter)
 450 public:
 451     wxPGEditorDialogAdapter()
 452         : wxObject()
 453     {
 454         m_clientData = NULL;
 455     }
 456
 457     virtual ~wxPGEditorDialogAdapter() { }
 458
 459     bool ShowDialog( wxPropertyGrid* propGrid, wxPGProperty* property );
 460
 461     virtual bool DoShowDialog( wxPropertyGrid* propGrid,
 462                                wxPGProperty* property ) = 0;
 463
 464     void SetValue( wxVariant value )
 465     {
 466         m_value = value;
 467     }
 468
 469     /**
 470         This method is typically only used if deriving class from existing
 471         adapter with value conversion purposes.
 472     */
 473     wxVariant& GetValue() { return m_value; }
 474
 475     //
 476     // This member is public so scripting language bindings
 477     // wrapper code can access it freely.
 478     void*               m_clientData;
 479
 480 private:
 481     wxVariant           m_value;
 482 };
 483
 484 // -----------------------------------------------------------------------
 485
 486
 487 /** @class wxPGMultiButton
 488
 489     This class can be used to have multiple buttons in a property editor.
 490     You will need to create a new property editor class, override
 491     CreateControls, and have it return wxPGMultiButton instance in
 492     wxPGWindowList::SetSecondary().
 493 */
 494 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 495 {
 496 public:
 497     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 498     virtual ~wxPGMultiButton() {}
 499
 500     wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
 501     const wxWindow* GetButton( unsigned int i ) const
 502         { return (const wxWindow*) m_buttons[i]; }
 503
 504     /** Utility function to be used in event handlers.
 505     */
 506     int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
 507
 508     /** Returns number of buttons.
 509     */
 510     unsigned int GetCount() const { return (unsigned int) m_buttons.size(); }
 511
 512     void Add( const wxString& label, int id = -2 );
 513 #if wxUSE_BMPBUTTON
 514     void Add( const wxBitmap& bitmap, int id = -2 );
 515 #endif
 516
 517     wxSize GetPrimarySize() const
 518     {
 519         return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
 520     }
 521
 522     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 523
 524 protected:
 525
 526     void DoAddButton( wxWindow* button, const wxSize& sz );
 527
 528     int GenId( int id ) const;
 529
 530     wxArrayPtrVoid  m_buttons;
 531     wxSize          m_fullEditorSize;
 532     int             m_buttonsWidth;
 533 };
 534
 535 // -----------------------------------------------------------------------
 536
 537 #endif // wxUSE_PROPGRID
 538
 539 #endif // _WX_PROPGRID_EDITORS_H_