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