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