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