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