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         wxPGEditor_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                 control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
 122                                  wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent),
 123                                  NULL, propgrid);
 124             @endcode
 125           OnCustomEditorEvent will then forward events, first to
 126           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
 127     */
 128     virtual wxPGWindowList CreateControls(wxPropertyGrid* propgrid,
 129                                           wxPGProperty* property,
 130                                           const wxPoint& pos,
 131                                           const wxSize& size) const = 0;
 132     #define wxPG_DECLARE_CREATECONTROLS \
 133         virtual wxPGWindowList \
 134             CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property, \
 135         const wxPoint& pos, const wxSize& sz ) const;
 136
 137     /** Loads value from property to the control. */
 138     virtual void UpdateControl( wxPGProperty* property,
 139                                 wxWindow* ctrl ) const = 0;
 140
 141     /**
 142         Used to get the renderer to draw the value with when the control is
 143         hidden.
 144
 145         Default implementation returns g_wxPGDefaultRenderer.
 146     */
 147     //virtual wxPGCellRenderer* GetCellRenderer() const;
 148
 149     /** Draws value for given property.
 150     */
 151     virtual void DrawValue( wxDC& dc,
 152                             const wxRect& rect,
 153                             wxPGProperty* property,
 154                             const wxString& text ) const;
 155
 156     /** Handles events. Returns true if value in control was modified
 157         (see wxPGProperty::OnEvent for more information).
 158
 159         @remarks wxPropertyGrid will automatically unfocus the editor when
 160                 wxEVT_COMMAND_TEXT_ENTER is received and when it results in
 161                 property value being modified. This happens regardless of
 162                 editor type (ie. behavior is same for any wxTextCtrl and
 163                 wxComboBox based editor).
 164     */
 165     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 166         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 167
 168 #if !defined(SWIG) || defined(CREATE_VCW)
 169     /** Returns value from control, via parameter 'variant'.
 170         Usually ends up calling property's StringToValue or IntToValue.
 171         Returns true if value was different.
 172     */
 173     virtual bool GetValueFromControl( wxVariant& variant,
 174                                       wxPGProperty* property,
 175                                       wxWindow* ctrl ) const;
 176 #endif
 177
 178     /** Sets value in control to unspecified. */
 179     virtual void SetValueToUnspecified( wxPGProperty* property,
 180                                         wxWindow* ctrl ) const = 0;
 181
 182     /** Sets control's value specifically from string. */
 183     virtual void SetControlStringValue( wxPGProperty* property,
 184                                         wxWindow* ctrl,
 185                                         const wxString& txt ) const;
 186
 187     /** Sets control's value specifically from int (applies to choice etc.). */
 188     virtual void SetControlIntValue( wxPGProperty* property,
 189                                      wxWindow* ctrl,
 190                                      int value ) const;
 191
 192     /** Inserts item to existing control. Index -1 means appending.
 193         Default implementation does nothing. Returns index of item added.
 194     */
 195     virtual int InsertItem( wxWindow* ctrl,
 196                             const wxString& label,
 197                             int index ) const;
 198
 199     /** Deletes item from existing control.
 200         Default implementation does nothing.
 201     */
 202     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 203
 204     /** Extra processing when control gains focus. For example, wxTextCtrl
 205         based controls should select all text.
 206     */
 207     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 208
 209     /** Returns true if control itself can contain the custom image. Default is
 210         to return false.
 211     */
 212     virtual bool CanContainCustomImage() const;
 213
 214     //
 215     // This member is public so scripting language bindings
 216     // wrapper code can access it freely.
 217     void*       m_clientData;
 218 };
 219
 220
 221 //
 222 // Note that we don't use this macro in this file because
 223 // otherwise doxygen gets confused.
 224 //
 225 #define WX_PG_DECLARE_EDITOR_CLASS(CLASSNAME) \
 226     DECLARE_DYNAMIC_CLASS(CLASSNAME) \
 227 public: \
 228     virtual wxString GetName() const; \
 229 private:
 230
 231
 232 #define WX_PG_IMPLEMENT_EDITOR_CLASS(EDITOR,CLASSNAME,BASECLASS) \
 233 IMPLEMENT_DYNAMIC_CLASS(CLASSNAME, BASECLASS) \
 234 wxString CLASSNAME::GetName() const \
 235 { \
 236     return wxS(#EDITOR); \
 237 } \
 238 wxPGEditor* wxPGEditor_##EDITOR = (wxPGEditor*) NULL; \
 239 wxPGEditor* wxPGConstruct##EDITOR##EditorClass() \
 240 { \
 241     wxASSERT( !wxPGEditor_##EDITOR ); \
 242     return new CLASSNAME(); \
 243 }
 244
 245
 246 #define WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS() \
 247 wxPG_DECLARE_CREATECONTROLS \
 248 virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const; \
 249 virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property, \
 250     wxWindow* primary, wxEvent& event ) const; \
 251 virtual bool GetValueFromControl( wxVariant& variant, \
 252                                   wxPGProperty* property, \
 253                                   wxWindow* ctrl ) const; \
 254 virtual void SetValueToUnspecified( wxPGProperty* property, \
 255                                     wxWindow* ctrl ) const;
 256
 257
 258 //
 259 // Following are the built-in editor classes.
 260 //
 261
 262 class WXDLLIMPEXP_PROPGRID wxPGTextCtrlEditor : public wxPGEditor
 263 {
 264 #ifndef SWIG
 265     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlEditor)
 266 #endif
 267 public:
 268     wxPGTextCtrlEditor() {}
 269     virtual ~wxPGTextCtrlEditor();
 270
 271     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 272     virtual wxString GetName() const;
 273
 274     //virtual wxPGCellRenderer* GetCellRenderer() const;
 275     virtual void SetControlStringValue( wxPGProperty* property,
 276                                         wxWindow* ctrl,
 277                                         const wxString& txt ) const;
 278     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 279
 280     // Provided so that, for example, ComboBox editor can use the same code
 281     // (multiple inheritance would get way too messy).
 282     static bool OnTextCtrlEvent( wxPropertyGrid* propgrid,
 283                                  wxPGProperty* property,
 284                                  wxWindow* ctrl,
 285                                  wxEvent& event );
 286
 287     static bool GetTextCtrlValueFromControl( wxVariant& variant,
 288                                              wxPGProperty* property,
 289                                              wxWindow* ctrl );
 290
 291 };
 292
 293
 294 class WXDLLIMPEXP_PROPGRID wxPGChoiceEditor : public wxPGEditor
 295 {
 296 #ifndef SWIG
 297     DECLARE_DYNAMIC_CLASS(wxPGChoiceEditor)
 298 #endif
 299 public:
 300     wxPGChoiceEditor() {}
 301     virtual ~wxPGChoiceEditor();
 302
 303     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 304     virtual wxString GetName() const;
 305
 306     virtual void SetControlIntValue( wxPGProperty* property,
 307                                      wxWindow* ctrl,
 308                                      int value ) const;
 309     virtual void SetControlStringValue( wxPGProperty* property,
 310                                         wxWindow* ctrl,
 311                                         const wxString& txt ) const;
 312
 313     virtual int InsertItem( wxWindow* ctrl,
 314                             const wxString& label,
 315                             int index ) const;
 316     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 317     virtual bool CanContainCustomImage() const;
 318
 319     // CreateControls calls this with CB_READONLY in extraStyle
 320     wxWindow* CreateControlsBase( wxPropertyGrid* propgrid,
 321                                   wxPGProperty* property,
 322                                   const wxPoint& pos,
 323                                   const wxSize& sz,
 324                                   long extraStyle ) const;
 325
 326 };
 327
 328
 329 class WXDLLIMPEXP_PROPGRID wxPGComboBoxEditor : public wxPGChoiceEditor
 330 {
 331 #ifndef SWIG
 332     DECLARE_DYNAMIC_CLASS(wxPGComboBoxEditor)
 333 #endif
 334 public:
 335     wxPGComboBoxEditor() {}
 336     virtual ~wxPGComboBoxEditor();
 337
 338     // Macro is used for convenience due to different signature with wxPython
 339     wxPG_DECLARE_CREATECONTROLS
 340
 341     virtual wxString GetName() const;
 342
 343     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const;
 344
 345     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 346         wxWindow* ctrl, wxEvent& event ) const;
 347
 348     virtual bool GetValueFromControl( wxVariant& variant,
 349                                       wxPGProperty* property,
 350                                       wxWindow* ctrl ) const;
 351
 352     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 353
 354 };
 355
 356
 357 // Exclude classes from being able to be derived from in wxPython bindings
 358 #ifndef SWIG
 359
 360 class WXDLLIMPEXP_PROPGRID wxPGChoiceAndButtonEditor : public wxPGChoiceEditor
 361 {
 362 public:
 363     wxPGChoiceAndButtonEditor() {}
 364     virtual ~wxPGChoiceAndButtonEditor();
 365     virtual wxString GetName() const;
 366
 367     // Macro is used for convenience due to different signature with wxPython
 368     wxPG_DECLARE_CREATECONTROLS
 369
 370     DECLARE_DYNAMIC_CLASS(wxPGChoiceAndButtonEditor)
 371 };
 372
 373 class WXDLLIMPEXP_PROPGRID
 374 wxPGTextCtrlAndButtonEditor : public wxPGTextCtrlEditor
 375 {
 376 public:
 377     wxPGTextCtrlAndButtonEditor() {}
 378     virtual ~wxPGTextCtrlAndButtonEditor();
 379     virtual wxString GetName() const;
 380     wxPG_DECLARE_CREATECONTROLS
 381
 382     DECLARE_DYNAMIC_CLASS(wxPGTextCtrlAndButtonEditor)
 383 };
 384
 385 #endif  // !SWIG
 386
 387
 388 #if wxPG_INCLUDE_CHECKBOX || defined(DOXYGEN)
 389
 390 //
 391 // Use custom check box code instead of native control
 392 // for cleaner (ie. more integrated) look.
 393 //
 394 class WXDLLIMPEXP_PROPGRID wxPGCheckBoxEditor : public wxPGEditor
 395 {
 396 #ifndef SWIG
 397     DECLARE_DYNAMIC_CLASS(wxPGCheckBoxEditor)
 398 #endif
 399 public:
 400     wxPGCheckBoxEditor() {}
 401     virtual ~wxPGCheckBoxEditor();
 402
 403     virtual wxString GetName() const;
 404     WX_PG_IMPLEMENT_EDITOR_CLASS_STD_METHODS()
 405
 406     virtual void DrawValue( wxDC& dc,
 407                             const wxRect& rect,
 408                             wxPGProperty* property,
 409                             const wxString& text ) const;
 410     //virtual wxPGCellRenderer* GetCellRenderer() const;
 411
 412     virtual void SetControlIntValue( wxPGProperty* property,
 413                                      wxWindow* ctrl,
 414                                      int value ) const;
 415 };
 416
 417 #endif
 418
 419
 420 // -----------------------------------------------------------------------
 421 // Editor class registeration macros
 422
 423 #define wxPGRegisterEditorClass(EDITOR) \
 424     if ( wxPGEditor_##EDITOR == (wxPGEditor*) NULL ) \
 425     { \
 426         wxPGEditor_##EDITOR = wxPropertyGrid::RegisterEditorClass( \
 427                 wxPGConstruct##EDITOR##EditorClass() ); \
 428     }
 429
 430 // Use this in RegisterDefaultEditors.
 431 #define wxPGRegisterDefaultEditorClass(EDITOR) \
 432 if ( wxPGEditor_##EDITOR == (wxPGEditor*) NULL ) \
 433     { \
 434         wxPGEditor_##EDITOR = wxPropertyGrid::RegisterEditorClass( \
 435                 wxPGConstruct##EDITOR##EditorClass(), true ); \
 436     }
 437
 438 #define wxPG_INIT_REQUIRED_EDITOR(T) \
 439     wxPGRegisterEditorClass(T)
 440
 441
 442 // -----------------------------------------------------------------------
 443
 444 /** @class wxPGEditorDialogAdapter
 445
 446     Derive a class from this to adapt an existing editor dialog or function to
 447     be used when editor button of a property is pushed.
 448
 449     You only need to derive class and implement DoShowDialog() to create and
 450     show the dialog, and finally submit the value returned by the dialog
 451     via SetValue().
 452
 453     @library{wxpropgrid}
 454     @category{propgrid}
 455 */
 456 class WXDLLIMPEXP_PROPGRID wxPGEditorDialogAdapter : public wxObject
 457 {
 458 #ifndef SWIG
 459     DECLARE_ABSTRACT_CLASS(wxPGEditorDialogAdapter)
 460 #endif
 461 public:
 462     wxPGEditorDialogAdapter()
 463         : wxObject()
 464     {
 465         m_clientData = NULL;
 466     }
 467
 468     virtual ~wxPGEditorDialogAdapter() { }
 469
 470     bool ShowDialog( wxPropertyGrid* propGrid, wxPGProperty* property );
 471
 472     virtual bool DoShowDialog( wxPropertyGrid* propGrid,
 473                                wxPGProperty* property ) = 0;
 474
 475     void SetValue( wxVariant value )
 476     {
 477         m_value = value;
 478     }
 479
 480     /**
 481         This method is typically only used if deriving class from existing
 482         adapter with value conversion purposes.
 483     */
 484     wxVariant& GetValue() { return m_value; }
 485
 486     //
 487     // This member is public so scripting language bindings
 488     // wrapper code can access it freely.
 489     void*               m_clientData;
 490
 491 private:
 492     wxVariant           m_value;
 493 };
 494
 495 // -----------------------------------------------------------------------
 496
 497
 498 /** @class wxPGMultiButton
 499
 500     This class can be used to have multiple buttons in a property editor.
 501     You will need to create a new property editor class, override
 502     CreateControls, and have it return wxPGMultiButton instance in
 503     wxPGWindowList::SetSecondary().
 504 */
 505 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 506 {
 507 public:
 508     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 509
 510     wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
 511     const wxWindow* GetButton( unsigned int i ) const
 512         { return (const wxWindow*) m_buttons[i]; }
 513
 514     /** Utility function to be used in event handlers.
 515     */
 516     int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
 517
 518     /** Returns number of buttons.
 519     */
 520     int GetCount() const { return m_buttons.Count(); }
 521
 522     void Add( const wxString& label, int id = -2 );
 523 #if wxUSE_BMPBUTTON
 524     void Add( const wxBitmap& bitmap, int id = -2 );
 525 #endif
 526
 527     wxSize GetPrimarySize() const
 528     {
 529         return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
 530     }
 531
 532     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 533
 534 #ifndef DOXYGEN
 535 protected:
 536
 537     int GenId( int id ) const;
 538
 539     wxArrayPtrVoid  m_buttons;
 540     wxSize          m_fullEditorSize;
 541     int             m_buttonsWidth;
 542 #endif // !DOXYGEN
 543 };
 544
 545 // -----------------------------------------------------------------------
 546
 547 #endif // wxUSE_PROPGRID
 548
 549 #endif // _WX_PROPGRID_EDITORS_H_