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