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 #ifndef SWIG
  79     DECLARE_ABSTRACT_CLASS(wxPGEditor)
  80 #endif
  81 public:
  82
  83     /** Constructor. */
  84     wxPGEditor()
  85         : wxObject()
  86     {
  87         m_clientData = NULL;
  88     }
  89
  90     /** Destructor. */
  91     virtual ~wxPGEditor();
  92
  93     /**
  94         Returns pointer to the name of the editor. For example,
  95         wxPG_EDITOR(TextCtrl) has name "TextCtrl". This method is autogenerated
  96         for custom editors.
  97     */
  98     virtual wxString GetName() const = 0;
  99
 100     /**
 101         Instantiates editor controls.
 102
 103         @param propgrid
 104             wxPropertyGrid to which the property belongs (use as parent for
 105             control).
 106         @param property
 107             Property for which this method is called.
 108         @param pos
 109             Position, inside wxPropertyGrid, to create control(s) to.
 110         @param size
 111             Initial size for control(s).
 112
 113         @remarks
 114         - Primary control shall use id wxPG_SUBID1, and secondary (button)
 115           control shall use wxPG_SUBID2.
 116         - Implementation shoud connect all necessary events to the
 117           wxPropertyGrid::OnCustomEditorEvent. For Example:
 118             @code
 119                 // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
 120                 // control to the OnEvent.
 121                 propgrid->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
 122                                   wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent));
 123             @endcode
 124           OnCustomEditorEvent will then forward events, first to
 125           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
 126     */
 127     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 128                                           wxPGProperty* property,
 129                                           const wxPoint& pos,
 130                                           const wxSize& size) const = 0;
 131     #define wxPG_DECLARE_CREATECONTROLS \
 132         virtual wxPGWindowList \
 133             CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property, \
 134         const wxPoint& pos, const wxSize& sz ) const;
 135
 136     /** Loads value from property to the control. */
 137     virtual void UpdateControl( wxPGProperty* property,
 138                                 wxWindow* ctrl ) const = 0;
 139
 140     /**
 141         Used to get the renderer to draw the value with when the control is
 142         hidden.
 143
 144         Default implementation returns g_wxPGDefaultRenderer.
 145     */
 146     //virtual wxPGCellRenderer* GetCellRenderer() const;
 147
 148     /** Draws value for given property.
 149     */
 150     virtual void DrawValue( wxDC& dc,
 151                             const wxRect& rect,
 152                             wxPGProperty* property,
 153                             const wxString& text ) const;
 154
 155     /** Handles events. Returns true if value in control was modified
 156         (see wxPGProperty::OnEvent for more information).
 157     */
 158     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 159         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 160
 161 #if !defined(SWIG) || defined(CREATE_VCW)
 162     /** Returns value from control, via parameter 'variant'.
 163         Usually ends up calling property's StringToValue or IntToValue.
 164         Returns true if value was different.
 165     */
 166     virtual bool GetValueFromControl( wxVariant& variant,
 167                                       wxPGProperty* property,
 168                                       wxWindow* ctrl ) const;
 169 #endif
 170
 171     /** Sets value in control to unspecified. */
 172     virtual void SetValueToUnspecified( wxPGProperty* property,
 173                                         wxWindow* ctrl ) const = 0;
 174
 175     /** Sets control's value specifically from string. */
 176     virtual void SetControlStringValue( wxPGProperty* property,
 177                                         wxWindow* ctrl,
 178                                         const wxString& txt ) const;
 179
 180     /** Sets control's value specifically from int (applies to choice etc.). */
 181     virtual void SetControlIntValue( wxPGProperty* property,
 182                                      wxWindow* ctrl,
 183                                      int value ) const;
 184
 185     /** Inserts item to existing control. Index -1 means appending.
 186         Default implementation does nothing. Returns index of item added.
 187     */
 188     virtual int InsertItem( wxWindow* ctrl,
 189                             const wxString& label,
 190                             int index ) const;
 191
 192     /** Deletes item from existing control.
 193         Default implementation does nothing.
 194     */
 195     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 196
 197     /** Extra processing when control gains focus. For example, wxTextCtrl
 198         based controls should select all text.
 199     */
 200     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 201
 202     /** Returns true if control itself can contain the custom image. Default is
 203         to return false.
 204     */
 205     virtual bool CanContainCustomImage() const;
 206
 207     //
 208     // This member is public so scripting language bindings
 209     // wrapper code can access it freely.
 210     void*       m_clientData;
 211 };
 212
 213
 214 //
 215 // Note that we don't use this macro in this file because
 216 // otherwise doxygen gets confused.
 217 //
 218 #define WX_PG_DECLARE_EDITOR_CLASS(CLASSNAME) \
 219     DECLARE_DYNAMIC_CLASS(CLASSNAME) \
 220 public: \
 221     virtual wxString GetName() const; \
 222 private:
 223
 224
 225 #define WX_PG_IMPLEMENT_EDITOR_CLASS(EDITOR,CLASSNAME,BASECLASS) \
 226 IMPLEMENT_DYNAMIC_CLASS(CLASSNAME, BASECLASS) \
 227 wxString CLASSNAME::GetName() const \
 228 { \
 229     return wxS(#EDITOR); \
 230 } \
 231 wxPGEditor* wxPGEditor_##EDITOR = (wxPGEditor*) NULL; \
 232 wxPGEditor* wxPGConstruct##EDITOR##EditorClass() \
 233 { \
 234     wxASSERT( !wxPGEditor_##EDITOR ); \
 235     return new CLASSNAME(); \
 236 }
 237
 238
 239 #define WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS() \
 240 wxPG_DECLARE_CREATECONTROLS \
 241 virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const; \
 242 virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property, \
 243     wxWindow* primary, wxEvent& event ) const; \
 244 virtual bool GetValueFromControl( wxVariant& variant, \
 245                                   wxPGProperty* property, \
 246                                   wxWindow* ctrl ) const; \
 247 virtual void SetValueToUnspecified( wxPGProperty* property, \
 248                                     wxWindow* ctrl ) const;
 249
 250
 251 //
 252 // Following are the built-in editor classes.
 253 //
 254
 255 class WXDLLIMPEXP_PROPGRID wxPGTextCtrlEditor : public wxPGEditor
 256 {
 257 #ifndef SWIG
 258     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlEditor)
 259 #endif
 260 public:
 261     wxPGTextCtrlEditor() {}
 262     virtual ~wxPGTextCtrlEditor();
 263
 264     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 265     virtual wxString GetName() const;
 266
 267     //virtual wxPGCellRenderer* GetCellRenderer() const;
 268     virtual void SetControlStringValue( wxPGProperty* property,
 269                                         wxWindow* ctrl,
 270                                         const wxString& txt ) const;
 271     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 272
 273     // Provided so that, for example, ComboBox editor can use the same code
 274     // (multiple inheritance would get way too messy).
 275     static bool OnTextCtrlEvent( wxPropertyGrid* propgrid,
 276                                  wxPGProperty* property,
 277                                  wxWindow* ctrl,
 278                                  wxEvent& event );
 279
 280     static bool GetTextCtrlValueFromControl( wxVariant& variant,
 281                                              wxPGProperty* property,
 282                                              wxWindow* ctrl );
 283
 284 };
 285
 286
 287 class WXDLLIMPEXP_PROPGRID wxPGChoiceEditor : public wxPGEditor
 288 {
 289 #ifndef SWIG
 290     DECLARE_DYNAMIC_CLASS(wxPGChoiceEditor)
 291 #endif
 292 public:
 293     wxPGChoiceEditor() {}
 294     virtual ~wxPGChoiceEditor();
 295
 296     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 297     virtual wxString GetName() const;
 298
 299     virtual void SetControlIntValue( wxPGProperty* property,
 300                                      wxWindow* ctrl,
 301                                      int value ) const;
 302     virtual void SetControlStringValue( wxPGProperty* property,
 303                                         wxWindow* ctrl,
 304                                         const wxString& txt ) const;
 305
 306     virtual int InsertItem( wxWindow* ctrl,
 307                             const wxString& label,
 308                             int index ) const;
 309     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 310     virtual bool CanContainCustomImage() const;
 311
 312     // CreateControls calls this with CB_READONLY in extraStyle
 313     wxWindow* CreateControlsBase( wxPropertyGrid* propgrid,
 314                                   wxPGProperty* property,
 315                                   const wxPoint& pos,
 316                                   const wxSize& sz,
 317                                   long extraStyle ) const;
 318
 319 };
 320
 321
 322 class WXDLLIMPEXP_PROPGRID wxPGComboBoxEditor : public wxPGChoiceEditor
 323 {
 324 #ifndef SWIG
 325     DECLARE_DYNAMIC_CLASS(wxPGComboBoxEditor)
 326 #endif
 327 public:
 328     wxPGComboBoxEditor() {}
 329     virtual ~wxPGComboBoxEditor();
 330
 331     // Macro is used for convenience due to different signature with wxPython
 332     wxPG_DECLARE_CREATECONTROLS
 333
 334     virtual wxString GetName() const;
 335
 336     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const;
 337
 338     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 339         wxWindow* ctrl, wxEvent& event ) const;
 340
 341     virtual bool GetValueFromControl( wxVariant& variant,
 342                                       wxPGProperty* property,
 343                                       wxWindow* ctrl ) const;
 344
 345     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 346
 347 };
 348
 349
 350 // Exclude classes from being able to be derived from in wxPython bindings
 351 #ifndef SWIG
 352
 353 class WXDLLIMPEXP_PROPGRID wxPGChoiceAndButtonEditor : public wxPGChoiceEditor
 354 {
 355 public:
 356     wxPGChoiceAndButtonEditor() {}
 357     virtual ~wxPGChoiceAndButtonEditor();
 358     virtual wxString GetName() const;
 359
 360     // Macro is used for convenience due to different signature with wxPython
 361     wxPG_DECLARE_CREATECONTROLS
 362
 363     DECLARE_DYNAMIC_CLASS(wxPGChoiceAndButtonEditor)
 364 };
 365
 366 class WXDLLIMPEXP_PROPGRID
 367 wxPGTextCtrlAndButtonEditor : public wxPGTextCtrlEditor
 368 {
 369 public:
 370     wxPGTextCtrlAndButtonEditor() {}
 371     virtual ~wxPGTextCtrlAndButtonEditor();
 372     virtual wxString GetName() const;
 373     wxPG_DECLARE_CREATECONTROLS
 374
 375     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlAndButtonEditor)
 376 };
 377
 378 #endif  // !SWIG
 379
 380
 381 #if wxPG_INCLUDE_CHECKBOX || defined(DOXYGEN)
 382
 383 //
 384 // Use custom check box code instead of native control
 385 // for cleaner (ie. more integrated) look.
 386 //
 387 class WXDLLIMPEXP_PROPGRID wxPGCheckBoxEditor : public wxPGEditor
 388 {
 389 #ifndef SWIG
 390     DECLARE_DYNAMIC_CLASS(wxPGCheckBoxEditor)
 391 #endif
 392 public:
 393     wxPGCheckBoxEditor() {}
 394     virtual ~wxPGCheckBoxEditor();
 395
 396     virtual wxString GetName() const;
 397     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 398
 399     virtual void DrawValue( wxDC& dc,
 400                             const wxRect& rect,
 401                             wxPGProperty* property,
 402                             const wxString& text ) const;
 403     //virtual wxPGCellRenderer* GetCellRenderer() const;
 404
 405     virtual void SetControlIntValue( wxPGProperty* property,
 406                                      wxWindow* ctrl,
 407                                      int value ) const;
 408 };
 409
 410 #endif
 411
 412
 413 // -----------------------------------------------------------------------
 414 // Editor class registeration macros
 415
 416 #define wxPGRegisterEditorClass(EDITOR) \
 417     if ( wxPGEditor_##EDITOR == (wxPGEditor*) NULL ) \
 418     { \
 419         wxPGEditor_##EDITOR = wxPropertyGrid::RegisterEditorClass( \
 420                 wxPGConstruct##EDITOR##EditorClass(), wxS(#EDITOR) ); \
 421     }
 422
 423 // Use this in RegisterDefaultEditors.
 424 #define wxPGRegisterDefaultEditorClass(EDITOR) \
 425 if ( wxPGEditor_##EDITOR == (wxPGEditor*) NULL ) \
 426     { \
 427         wxPGEditor_##EDITOR = wxPropertyGrid::RegisterEditorClass( \
 428                 wxPGConstruct##EDITOR##EditorClass(), wxS(#EDITOR), true ); \
 429     }
 430
 431 #define wxPG_INIT_REQUIRED_EDITOR(T) \
 432     wxPGRegisterEditorClass(T)
 433
 434
 435 // -----------------------------------------------------------------------
 436
 437 /** @class wxPGEditorDialogAdapter
 438
 439     Derive a class from this to adapt an existing editor dialog or function to
 440     be used when editor button of a property is pushed.
 441
 442     You only need to derive class and implement DoShowDialog() to create and
 443     show the dialog, and finally submit the value returned by the dialog
 444     via SetValue().
 445
 446     @library{wxpropgrid}
 447     @category{propgrid}
 448 */
 449 class WXDLLIMPEXP_PROPGRID wxPGEditorDialogAdapter : public wxObject
 450 {
 451 #ifndef SWIG
 452     DECLARE_ABSTRACT_CLASS(wxPGEditorDialogAdapter)
 453 #endif
 454 public:
 455     wxPGEditorDialogAdapter()
 456         : wxObject()
 457     {
 458         m_clientData = NULL;
 459     }
 460
 461     virtual ~wxPGEditorDialogAdapter() { }
 462
 463     bool ShowDialog( wxPropertyGrid* propGrid, wxPGProperty* property );
 464
 465     virtual bool DoShowDialog( wxPropertyGrid* propGrid,
 466                                wxPGProperty* property ) = 0;
 467
 468     void SetValue( wxVariant value )
 469     {
 470         m_value = value;
 471     }
 472
 473     /**
 474         This method is typically only used if deriving class from existing
 475         adapter with value conversion purposes.
 476     */
 477     wxVariant& GetValue() { return m_value; }
 478
 479     //
 480     // This member is public so scripting language bindings
 481     // wrapper code can access it freely.
 482     void*               m_clientData;
 483
 484 private:
 485     wxVariant           m_value;
 486 };
 487
 488 // -----------------------------------------------------------------------
 489
 490
 491 /** @class wxPGMultiButton
 492
 493     This class can be used to have multiple buttons in a property editor.
 494     You will need to create a new property editor class, override
 495     CreateControls, and have it return wxPGMultiButton instance in
 496     wxPGWindowList::SetSecondary(). For instance, here we add three buttons to
 497     a textctrl editor:
 498
 499     @code
 500
 501     #include <wx/propgrid/editors.h>
 502
 503     class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
 504     {
 505         WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
 506     public:
 507         wxMultiButtonTextCtrlEditor() {}
 508         virtual ~wxMultiButtonTextCtrlEditor() {}
 509
 510         wxPG_DECLARE_CREATECONTROLS
 511         virtual bool OnEvent( wxPropertyGrid* propGrid,
 512                               wxPGProperty* property,
 513                               wxWindow* ctrl,
 514                               wxEvent& event ) const;
 515
 516     };
 517
 518     WX_PG_IMPLEMENT_EDITOR_CLASS(MultiButtonTextCtrlEditor,
 519                                  wxMultiButtonTextCtrlEditor,
 520                                  wxPGTextCtrlEditor)
 521
 522     wxPGWindowList
 523     wxMultiButtonTextCtrlEditor::CreateControls( wxPropertyGrid* propGrid,
 524                                                  wxPGProperty* property,
 525                                                  const wxPoint& pos,
 526                                                  const wxSize& sz ) const
 527     {
 528         // Create and populate buttons-subwindow
 529         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 530
 531         // Add two regular buttons
 532         buttons->Add( "..." );
 533         buttons->Add( "A" );
 534         // Add a bitmap button
 535         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 536
 537         // Create the 'primary' editor control (textctrl in this case)
 538         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls(
 539                                     propGrid,
 540                                     property,
 541                                     pos,
 542                                     buttons->GetPrimarySize()
 543                                  );
 544
 545         // Finally, move buttons-subwindow to correct position and make sure
 546         // returned wxPGWindowList contains our custom button list.
 547         buttons->FinalizePosition(pos);
 548
 549         wndList.SetSecondary( buttons );
 550         return wndList;
 551     }
 552
 553     bool wxMultiButtonTextCtrlEditor::OnEvent( wxPropertyGrid* propGrid,
 554                                                wxPGProperty* property,
 555                                                wxWindow* ctrl,
 556                                                wxEvent& event ) const
 557     {
 558         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 559         {
 560             wxPGMultiButton* buttons = (wxPGMultiButton*)
 561                 propGrid->GetEditorControlSecondary();
 562
 563             if ( event.GetId() == buttons->GetButtonId(0) )
 564             {
 565                 // Do something when first button is pressed
 566                 return true;
 567             }
 568             if ( event.GetId() == buttons->GetButtonId(1) )
 569             {
 570                 // Do something when first button is pressed
 571                 return true;
 572             }
 573             if ( event.GetId() == buttons->GetButtonId(2) )
 574             {
 575                 // Do something when second button is pressed
 576                 return true;
 577             }
 578         }
 579         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 580     }
 581
 582     @endcode
 583
 584     Further to use this editor, code like this can be used:
 585
 586     @code
 587
 588         // Register editor class - needs only to be called once
 589         wxPGRegisterEditorClass( MultiButtonTextCtrlEditor );
 590
 591         // Insert the property that will have multiple buttons
 592         propGrid->Append( new wxLongStringProperty("MultipleButtons",
 593                                                     wxPG_LABEL) );
 594
 595         // Change property to use editor created in the previous code segment
 596         propGrid->SetPropertyEditor( "MultipleButtons",
 597                                      wxPG_EDITOR(MultiButtonTextCtrlEditor) );
 598
 599     @endcode
 600
 601     @library{wxpropgrid}
 602     @category{propgrid}
 603 */
 604 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 605 {
 606 public:
 607     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 608
 609     wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
 610     const wxWindow* GetButton( unsigned int i ) const
 611         { return (const wxWindow*) m_buttons[i]; }
 612
 613     /** Utility function to be used in event handlers.
 614     */
 615     int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
 616
 617     /** Returns number of buttons.
 618     */
 619     int GetCount() const { return m_buttons.Count(); }
 620
 621     void Add( const wxString& label, int id = -2 );
 622 #if wxUSE_BMPBUTTON
 623     void Add( const wxBitmap& bitmap, int id = -2 );
 624 #endif
 625
 626     wxSize GetPrimarySize() const
 627     {
 628         return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
 629     }
 630
 631     void FinalizePosition( const wxPoint& pos )
 632     {
 633         Move( pos.x + m_fullEditorSize.x - m_buttonsWidth, pos.y );
 634     }
 635
 636 #ifndef DOXYGEN
 637 protected:
 638
 639     int GenId( int id ) const;
 640
 641     wxArrayPtrVoid  m_buttons;
 642     wxSize          m_fullEditorSize;
 643     int             m_buttonsWidth;
 644 #endif // !DOXYGEN
 645 };
 646
 647 // -----------------------------------------------------------------------
 648
 649 #endif // wxUSE_PROPGRID
 650
 651 #endif // _WX_PROPGRID_EDITORS_H_