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