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