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