include/wx/propgrid/propgridiface.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/propgeid/propgridiface.h
   3 // Purpose:     wxPropertyGridInterface class
   4 // Author:      Jaakko Salli
   5 // Modified by:
   6 // Created:     2008-08-24
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Jaakko Salli
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef __WX_PROPGRID_PROPGRIDIFACE_H__
  13 #define __WX_PROPGRID_PROPGRIDIFACE_H__
  14
  15 #if wxUSE_PROPGRID
  16
  17 #include "wx/propgrid/property.h"
  18 #include "wx/propgrid/propgridpagestate.h"
  19
  20 // -----------------------------------------------------------------------
  21
  22 #ifndef SWIG
  23
  24 /** @section wxPGPropArgCls
  25
  26     Most property grid functions have this type as their argument, as it can
  27     convey a property by either a pointer or name.
  28 */
  29 class WXDLLIMPEXP_PROPGRID wxPGPropArgCls
  30 {
  31 public:
  32     wxPGPropArgCls() { }
  33     wxPGPropArgCls( const wxPGProperty* property )
  34     {
  35         m_ptr.property = (wxPGProperty*) property;
  36         m_flags = IsProperty;
  37     }
  38     wxPGPropArgCls( const wxString& str )
  39     {
  40         m_ptr.stringName = &str;
  41         m_flags = IsWxString;
  42     }
  43     wxPGPropArgCls( const wxPGPropArgCls& id )
  44     {
  45         m_ptr = id.m_ptr;
  46         m_flags = id.m_flags;
  47     }
  48     // This is only needed for wxPython bindings
  49     wxPGPropArgCls( wxString* str, bool WXUNUSED(deallocPtr) )
  50     {
  51         m_ptr.stringName = str;
  52         m_flags = IsWxString | OwnsWxString;
  53     }
  54     ~wxPGPropArgCls()
  55     {
  56         if ( m_flags & OwnsWxString )
  57             delete m_ptr.stringName;
  58     }
  59     wxPGProperty* GetPtr() const
  60     {
  61         wxCHECK( m_flags == IsProperty, NULL );
  62         return m_ptr.property;
  63     }
  64     wxPGPropArgCls( const char* str )
  65     {
  66         m_ptr.charName = str;
  67         m_flags = IsCharPtr;
  68     }
  69 #if wxUSE_WCHAR_T
  70     wxPGPropArgCls( const wchar_t* str )
  71     {
  72         m_ptr.wcharName = str;
  73         m_flags = IsWCharPtr;
  74     }
  75 #endif
  76     /** This constructor is required for NULL. */
  77     wxPGPropArgCls( int )
  78     {
  79         m_ptr.property = (wxPGProperty*) NULL;
  80         m_flags = IsProperty;
  81     }
  82     wxPGProperty* GetPtr( wxPropertyGridInterface* iface ) const;
  83     wxPGProperty* GetPtr( const wxPropertyGridInterface* iface ) const
  84     {
  85         return GetPtr((wxPropertyGridInterface*)iface);
  86     }
  87     wxPGProperty* GetPtr0() const { return m_ptr.property; }
  88     bool HasName() const { return (m_flags != IsProperty); }
  89     const wxString& GetName() const { return *m_ptr.stringName; }
  90 private:
  91
  92     enum
  93     {
  94         IsProperty      = 0x00,
  95         IsWxString      = 0x01,
  96         IsCharPtr       = 0x02,
  97         IsWCharPtr      = 0x04,
  98         OwnsWxString    = 0x10,
  99     };
 100
 101     union
 102     {
 103         wxPGProperty* property;
 104         const char* charName;
 105 #if wxUSE_WCHAR_T
 106         const wchar_t* wcharName;
 107 #endif
 108         const wxString* stringName;
 109     } m_ptr;
 110     unsigned char m_flags;
 111 };
 112
 113 #endif
 114
 115 typedef const wxPGPropArgCls& wxPGPropArg;
 116
 117 // -----------------------------------------------------------------------
 118
 119 WXDLLIMPEXP_PROPGRID
 120 void wxPGTypeOperationFailed( const wxPGProperty* p,
 121                               const wxString& typestr,
 122                               const wxString& op );
 123 WXDLLIMPEXP_PROPGRID
 124 void wxPGGetFailed( const wxPGProperty* p, const wxString& typestr );
 125
 126 // -----------------------------------------------------------------------
 127
 128 // Helper macro that does necessary preparations when calling
 129 // some wxPGProperty's member function.
 130 #define wxPG_PROP_ARG_CALL_PROLOG_0(PROPERTY) \
 131     PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
 132     if ( !p ) return;
 133
 134 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(PROPERTY, RETVAL) \
 135     PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
 136     if ( !p ) return RETVAL;
 137
 138 #define wxPG_PROP_ARG_CALL_PROLOG() \
 139     wxPG_PROP_ARG_CALL_PROLOG_0(wxPGProperty)
 140
 141 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL(RVAL) \
 142     wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(wxPGProperty, RVAL)
 143
 144 #define wxPG_PROP_ID_CONST_CALL_PROLOG() \
 145     wxPG_PROP_ARG_CALL_PROLOG_0(const wxPGProperty)
 146
 147 #define wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(RVAL) \
 148     wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(const wxPGProperty, RVAL)
 149
 150 // -----------------------------------------------------------------------
 151
 152
 153 /** @class wxPropertyGridInterface
 154
 155     Most of the shared property manipulation interface shared by wxPropertyGrid,
 156     wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
 157
 158     @remarks
 159     - In separate wxPropertyGrid component this class was known as
 160     wxPropertyContainerMethods.
 161
 162     @library{wxpropgrid}
 163     @category{propgrid}
 164 */
 165 class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
 166 {
 167 public:
 168
 169     /** Destructor */
 170     virtual ~wxPropertyGridInterface() { }
 171
 172     /**
 173         Appends property to the list.
 174
 175         wxPropertyGrid assumes ownership of the object.
 176         Becomes child of most recently added category.
 177         @remarks
 178         - wxPropertyGrid takes the ownership of the property pointer.
 179         - If appending a category with name identical to a category already in
 180           the wxPropertyGrid, then newly created category is deleted, and most
 181           recently added category (under which properties are appended) is set
 182           to the one with same name. This allows easier adding of items to same
 183           categories in multiple passes.
 184         - Does not automatically redraw the control, so you may need to call
 185           Refresh when calling this function after control has been shown for
 186           the first time.
 187     */
 188     wxPGProperty* Append( wxPGProperty* property );
 189
 190     wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newproperty );
 191
 192     /**
 193         In order to add new items into a property with fixed children (for
 194         instance, wxFlagsProperty), you need to call this method. After
 195         populating has been finished, you need to call EndAddChildren.
 196     */
 197     void BeginAddChildren( wxPGPropArg id );
 198
 199     /** Deletes all properties.
 200     */
 201     virtual void Clear() = 0;
 202
 203     /** Deselect current selection, if any. Returns true if success
 204         (ie. validator did not intercept). */
 205     bool ClearSelection();
 206
 207     /** Resets modified status of all properties.
 208     */
 209     void ClearModifiedStatus();
 210
 211     /** Collapses given category or property with children.
 212         Returns true if actually collapses.
 213     */
 214     bool Collapse( wxPGPropArg id );
 215
 216     /** Collapses all items that can be collapsed.
 217
 218         @return
 219         Return false if failed (may fail if editor value cannot be validated).
 220     */
 221     bool CollapseAll() { return ExpandAll(false); }
 222
 223     /**
 224         Changes value of a property, as if from an editor.
 225         Use this instead of SetPropertyValue() if you need the value to run
 226         through validation process, and also send the property change event.
 227
 228         @return
 229         Returns true if value was successfully changed.
 230     */
 231     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 232
 233     /**
 234         Deletes a property by id. If category is deleted, all children are
 235         automatically deleted as well.
 236      */
 237     void DeleteProperty( wxPGPropArg id );
 238
 239     /** Disables property. */
 240     bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); }
 241
 242     /**
 243         Returns true if all property grid data changes have been committed.
 244
 245         Usually only returns false if value in active editor has been
 246         invalidated by a wxValidator.
 247     */
 248     bool EditorValidate();
 249
 250     /**
 251         Enables or disables property, depending on whether enable is true or
 252         false.
 253      */
 254     bool EnableProperty( wxPGPropArg id, bool enable = true );
 255
 256     /** Called after population of property with fixed children has finished.
 257     */
 258     void EndAddChildren( wxPGPropArg id );
 259
 260     /** Expands given category or property with children.
 261         Returns true if actually expands.
 262     */
 263     bool Expand( wxPGPropArg id );
 264
 265     /** Expands all items that can be expanded.
 266     */
 267     bool ExpandAll( bool expand = true );
 268
 269     /** Returns id of first child of given property.
 270         @remarks
 271         Does not return sub-properties!
 272     */
 273     wxPGProperty* GetFirstChild( wxPGPropArg id )
 274     {
 275         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
 276
 277         if ( !p->GetChildCount() || p->HasFlag(wxPG_PROP_AGGREGATE) )
 278             return wxNullProperty;
 279
 280         return p->Item(0);
 281     }
 282
 283     //@{
 284     /** Returns iterator class instance.
 285         @param flags
 286         See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
 287         iteration over everything except private child properties.
 288         @param firstProp
 289             Property to start iteration from. If NULL, then first child of root
 290             is used.
 291         @param startPos
 292             Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
 293             from the first property from the top, and wxBOTTOM means that the
 294             iteration will instead begin from bottommost valid item.
 295     */
 296     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
 297                                         wxPGProperty* firstProp = NULL )
 298     {
 299         return wxPropertyGridIterator( m_pState, flags, firstProp );
 300     }
 301
 302     wxPropertyGridConstIterator
 303     GetIterator( int flags = wxPG_ITERATE_DEFAULT,
 304                  wxPGProperty* firstProp = NULL ) const
 305     {
 306         return wxPropertyGridConstIterator( m_pState, flags, firstProp );
 307     }
 308
 309     wxPropertyGridIterator GetIterator( int flags, int startPos )
 310     {
 311         return wxPropertyGridIterator( m_pState, flags, startPos );
 312     }
 313
 314     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
 315     {
 316         return wxPropertyGridConstIterator( m_pState, flags, startPos );
 317     }
 318     //@}
 319
 320     /** Returns id of first item, whether it is a category or property.
 321         @param flags
 322         @link iteratorflags List of iterator flags@endlink
 323     */
 324     wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL )
 325     {
 326         wxPropertyGridIterator it( m_pState, flags, wxNullProperty, 1 );
 327         return *it;
 328     }
 329
 330     const wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ) const
 331     {
 332         return ((wxPropertyGridInterface*)this)->GetFirst(flags);
 333     }
 334
 335     /**
 336         Returns id of property with given name (case-sensitive).
 337
 338         If there is no property with such name, returned property id is invalid
 339         ( i.e. it will return false with IsOk method).
 340         @remarks
 341         - Sub-properties (i.e. properties which have parent that is not
 342           category or root) can not be accessed globally by their name.
 343           Instead, use "<property>.<subproperty>" in place of "<subproperty>".
 344     */
 345     wxPGProperty* GetProperty( const wxString& name ) const
 346     {
 347         return GetPropertyByName(name);
 348     }
 349
 350     /** Returns map-like storage of property's attributes.
 351         @remarks
 352         Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set,
 353         then builtin-attributes are not included in the storage.
 354     */
 355     const wxPGAttributeStorage& GetPropertyAttributes( wxPGPropArg id ) const
 356     {
 357         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(*((const wxPGAttributeStorage*)NULL));
 358         return p->GetAttributes();
 359     }
 360
 361     /** Adds to 'targetArr' pointers to properties that have given
 362         flags 'flags' set. However, if 'inverse' is set to true, then
 363         only properties without given flags are stored.
 364         @param flags
 365         Property flags to use.
 366         @param iterFlags
 367         Iterator flags to use. Default is everything expect private children.
 368     */
 369     void GetPropertiesWithFlag( wxArrayPGProperty* targetArr,
 370                                 wxPGProperty::FlagType flags,
 371                                 bool inverse = false,
 372                                 int iterFlags = wxPG_ITERATE_PROPERTIES |
 373                                                 wxPG_ITERATE_HIDDEN |
 374                                                 wxPG_ITERATE_CATEGORIES) const;
 375
 376     /** Returns value of given attribute. If none found, returns NULL-variant.
 377     */
 378     wxVariant GetPropertyAttribute( wxPGPropArg id,
 379                                     const wxString& attrName ) const
 380     {
 381         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullVariant)
 382         return p->GetAttribute(attrName);
 383     }
 384
 385     /** Returns pointer of property's nearest parent category. If no category
 386         found, returns NULL.
 387     */
 388     wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const
 389     {
 390         wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(NULL)
 391         return m_pState->GetPropertyCategory(p);
 392     }
 393
 394 #ifndef SWIG
 395     /** Returns client data (void*) of a property. */
 396     void* GetPropertyClientData( wxPGPropArg id ) const
 397     {
 398         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 399         return p->GetClientData();
 400     }
 401 #endif
 402
 403     /**
 404         Returns first property which label matches given string.
 405
 406         NULL if none found. Note that this operation is extremely slow when
 407         compared to GetPropertyByName().
 408     */
 409     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 410
 411     /** Returns property with given name. NULL if none found.
 412     */
 413     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 414
 415     /** Returns child property 'subname' of property 'name'. Same as
 416         calling GetPropertyByName("name.subname"), albeit slightly faster.
 417     */
 418     wxPGProperty* GetPropertyByName( const wxString& name,
 419                                      const wxString& subname ) const;
 420
 421     /** Returns property's editor. */
 422     const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const
 423     {
 424         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 425         return p->GetEditorClass();
 426     }
 427
 428     /** Returns help string associated with a property. */
 429     wxString GetPropertyHelpString( wxPGPropArg id ) const
 430     {
 431         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 432         return p->GetHelpString();
 433     }
 434
 435     /** Returns property's custom value image (NULL of none). */
 436     wxBitmap* GetPropertyImage( wxPGPropArg id ) const
 437     {
 438         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 439         return p->GetValueImage();
 440     }
 441
 442     /** Returns label of a property. */
 443     const wxString& GetPropertyLabel( wxPGPropArg id )
 444     {
 445         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 446         return p->GetLabel();
 447     }
 448
 449     /** Returns name of a property, by which it is globally accessible. */
 450     wxString GetPropertyName( wxPGProperty* property )
 451     {
 452         return property->GetName();
 453     }
 454
 455     /** Returns parent item of a property. */
 456     wxPGProperty* GetPropertyParent( wxPGPropArg id )
 457     {
 458         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
 459         return p->GetParent();
 460     }
 461
 462 #if wxUSE_VALIDATORS
 463     /** Returns validator of a property as a reference, which you
 464         can pass to any number of SetPropertyValidator.
 465     */
 466     wxValidator* GetPropertyValidator( wxPGPropArg id )
 467     {
 468         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 469         return p->GetValidator();
 470     }
 471 #endif
 472
 473     /** Returns value as wxVariant. To get wxObject pointer from it,
 474         you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro.
 475
 476         If property value is unspecified, Null variant is returned.
 477     */
 478     wxVariant GetPropertyValue( wxPGPropArg id )
 479     {
 480         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant())
 481         return p->GetValue();
 482     }
 483
 484     wxString GetPropertyValueAsString( wxPGPropArg id ) const;
 485     long GetPropertyValueAsLong( wxPGPropArg id ) const;
 486     unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const
 487     {
 488         return (unsigned long) GetPropertyValueAsLong(id);
 489     }
 490 #ifndef SWIG
 491     int GetPropertyValueAsInt( wxPGPropArg id ) const
 492         { return (int)GetPropertyValueAsLong(id); }
 493 #endif
 494     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
 495     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 496
 497 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(TYPENAME, DEFVAL) \
 498     wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
 499     wxString typeName(wxS(TYPENAME)); \
 500     wxVariant value = p->GetValue(); \
 501     if ( value.GetType() != typeName ) \
 502     { \
 503         wxPGGetFailed(p, typeName); \
 504         return DEFVAL; \
 505     }
 506
 507 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(TYPENAME, DEFVAL) \
 508     wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
 509     wxVariant value = p->GetValue(); \
 510     if ( value.GetType() != wxS(TYPENAME) ) \
 511         return DEFVAL; \
 512
 513     wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const
 514     {
 515         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("arrstring",
 516                                                    wxArrayString())
 517         return value.GetArrayString();
 518     }
 519
 520 #if wxUSE_LONGLONG_NATIVE
 521     wxLongLong_t GetPropertyValueAsLongLong( wxPGPropArg id ) const
 522     {
 523         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK("wxLongLong",
 524                                              (long) GetPropertyValueAsLong(id))
 525         wxLongLong ll;
 526         ll << value;
 527         return ll.GetValue();
 528     }
 529
 530     wxULongLong_t GetPropertyValueAsULongLong( wxPGPropArg id ) const
 531     {
 532         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK("wxULongLong",
 533                                     (unsigned long) GetPropertyValueAsULong(id))
 534         wxULongLong ull;
 535         ull << value;
 536         return ull.GetValue();
 537     }
 538 #endif
 539
 540     wxArrayInt GetPropertyValueAsArrayInt( wxPGPropArg id ) const
 541     {
 542         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("wxArrayInt",
 543                                                    wxArrayInt())
 544         wxArrayInt arr;
 545         arr << value;
 546         return arr;
 547     }
 548
 549 #if wxUSE_DATETIME
 550     wxDateTime GetPropertyValueAsDateTime( wxPGPropArg id ) const
 551     {
 552         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("datetime",
 553                                                    wxDateTime())
 554         return value.GetDateTime();
 555     }
 556 #endif
 557
 558 #ifndef SWIG
 559     /** Returns a wxVariant list containing wxVariant versions of all
 560         property values. Order is not guaranteed.
 561         @param flags
 562         Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
 563         category will be its own wxVariantList of wxVariant.
 564         Use wxPG_INC_ATTRIBUTES to include property attributes as well.
 565         Each attribute will be stored as list variant named
 566         "@@<propname>@@attr."
 567         @remarks
 568     */
 569     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
 570         wxPGProperty* baseparent = NULL, long flags = 0 ) const
 571     {
 572         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
 573     }
 574 #endif
 575
 576     /** Returns currently selected property. */
 577     wxPGProperty* GetSelection() const
 578     {
 579         return m_pState->GetSelection();
 580     }
 581
 582 #ifndef SWIG
 583     wxPropertyGridPageState* GetState() const { return m_pState; }
 584 #endif
 585
 586     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
 587         which can be useful for forward-iterating through arbitrary property
 588         containers.
 589
 590         @param flags
 591         See @ref propgrid_iterator_flags.
 592     */
 593     virtual wxPGVIterator GetVIterator( int flags ) const;
 594
 595     /** Hides or reveals a property.
 596         @param hide
 597             If true, hides property, otherwise reveals it.
 598         @param flags
 599             By default changes are applied recursively. Set this paramter
 600             wxPG_DONT_RECURSE to prevent this.
 601     */
 602     bool HideProperty( wxPGPropArg id,
 603                        bool hide = true,
 604                        int flags = wxPG_RECURSE );
 605
 606 #if wxPG_INCLUDE_ADVPROPS
 607     /** Initializes *all* property types. Causes references to most object
 608         files in the library, so calling this may cause significant increase
 609         in executable size when linking with static library.
 610     */
 611     static void InitAllTypeHandlers();
 612 #else
 613     static void InitAllTypeHandlers() { }
 614 #endif
 615
 616     //@{
 617     /** Inserts property to the property container.
 618
 619         @param priorThis
 620         New property is inserted just prior to this. Available only
 621         in the first variant. There are two versions of this function
 622         to allow this parameter to be either an id or name to
 623         a property.
 624
 625         @param newproperty
 626         Pointer to the inserted property. wxPropertyGrid will take
 627         ownership of this object.
 628
 629         @param parent
 630         New property is inserted under this category. Available only
 631         in the second variant. There are two versions of this function
 632         to allow this parameter to be either an id or name to
 633         a property.
 634
 635         @param index
 636         Index under category. Available only in the second variant.
 637         If index is < 0, property is appended in category.
 638
 639         @return
 640         Returns id for the property,
 641
 642         @remarks
 643
 644         - wxPropertyGrid takes the ownership of the property pointer.
 645
 646         - While Append may be faster way to add items, make note that when
 647           both types of data storage (categoric and
 648           non-categoric) are active, Insert becomes even more slow. This is
 649           especially true if current mode is non-categoric.
 650
 651         Example of use:
 652
 653         @code
 654
 655             // append category
 656             wxPGProperty* my_cat_id = propertygrid->Append(
 657                 new wxPropertyCategory("My Category") );
 658
 659             ...
 660
 661             // insert into category - using second variant
 662             wxPGProperty* my_item_id_1 = propertygrid->Insert(
 663                 my_cat_id, 0, new wxStringProperty("My String 1") );
 664
 665             // insert before to first item - using first variant
 666             wxPGProperty* my_item_id_2 = propertygrid->Insert(
 667                 my_item_id, new wxStringProperty("My String 2") );
 668
 669         @endcode
 670
 671     */
 672     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty );
 673     wxPGProperty* Insert( wxPGPropArg parent,
 674                           int index,
 675                           wxPGProperty* newproperty );
 676     //@}
 677
 678     /** Returns true if property is a category. */
 679     bool IsPropertyCategory( wxPGPropArg id ) const
 680     {
 681         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 682         return p->IsCategory();
 683     }
 684
 685     /** Returns true if property is enabled. */
 686     bool IsPropertyEnabled( wxPGPropArg id ) const
 687     {
 688         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 689         return (!(p->GetFlags() & wxPG_PROP_DISABLED))?true:false;
 690     }
 691
 692     /**
 693         Returns true if given property is expanded.
 694
 695         Naturally, always returns false for properties that cannot be expanded.
 696     */
 697     bool IsPropertyExpanded( wxPGPropArg id ) const;
 698
 699     /**
 700         Returns true if property has been modified after value set or modify
 701         flag clear by software.
 702     */
 703     bool IsPropertyModified( wxPGPropArg id ) const
 704     {
 705         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 706         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
 707     }
 708
 709     /**
 710         Returns true if property is shown (ie hideproperty with true not
 711         called for it).
 712      */
 713     bool IsPropertyShown( wxPGPropArg id ) const
 714     {
 715         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 716         return (!(p->GetFlags() & wxPG_PROP_HIDDEN))?true:false;
 717     }
 718
 719     /** Returns true if property value is set to unspecified.
 720     */
 721     bool IsPropertyValueUnspecified( wxPGPropArg id ) const
 722     {
 723         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 724         return p->IsValueUnspecified();
 725     }
 726
 727     /**
 728         Disables (limit = true) or enables (limit = false) wxTextCtrl editor of
 729         a property, if it is not the sole mean to edit the value.
 730     */
 731     void LimitPropertyEditing( wxPGPropArg id, bool limit = true );
 732
 733     /** If state is shown in it's grid, refresh it now.
 734     */
 735     virtual void RefreshGrid( wxPropertyGridPageState* state = NULL );
 736
 737 #if wxPG_INCLUDE_ADVPROPS
 738     /**
 739         Initializes additional property editors (SpinCtrl etc.). Causes
 740         references to most object files in the library, so calling this may
 741         cause significant increase in executable size when linking with static
 742         library.
 743     */
 744     static void RegisterAdditionalEditors();
 745 #else
 746     static void RegisterAdditionalEditors() { }
 747 #endif
 748
 749     /** Replaces property with id with newly created property. For example,
 750         this code replaces existing property named "Flags" with one that
 751         will have different set of items:
 752         @code
 753             pg->ReplaceProperty("Flags",
 754                 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
 755         @endcode
 756         For more info, see wxPropertyGrid::Insert.
 757     */
 758     wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property );
 759
 760     /** @anchor propgridinterface_editablestate_flags
 761
 762         Flags for wxPropertyGridInterface::SaveEditableState() and
 763         wxPropertyGridInterface::RestoreEditableState().
 764     */
 765     enum EditableStateFlags
 766     {
 767         /** Include selected property. */
 768         SelectionState   = 0x01,
 769         /** Include expanded/collapsed property information. */
 770         ExpandedState    = 0x02,
 771         /** Include scrolled position. */
 772         ScrollPosState   = 0x04,
 773         /** Include selected page information.
 774             Only applies to wxPropertyGridManager. */
 775         PageState        = 0x08,
 776         /** Include splitter position. Stored for each page. */
 777         SplitterPosState = 0x10,
 778         /** Include description box size.
 779             Only applies to wxPropertyGridManager. */
 780         DescBoxState     = 0x20,
 781
 782         /**
 783             Include all supported user editable state information.
 784             This is usually the default value. */
 785         AllStates        = SelectionState |
 786                            ExpandedState |
 787                            ScrollPosState |
 788                            PageState |
 789                            SplitterPosState |
 790                            DescBoxState
 791     };
 792
 793     /**
 794         Restores user-editable state.
 795
 796         See also wxPropertyGridInterface::SaveEditableState().
 797
 798         @param src
 799             String generated by SaveEditableState.
 800
 801         @param restoreStates
 802             Which parts to restore from source string. See @ref
 803             propgridinterface_editablestate_flags "list of editable state
 804             flags".
 805
 806         @return
 807             False if there was problem reading the string.
 808
 809         @remarks
 810         If some parts of state (such as scrolled or splitter position) fail to
 811         restore correctly, please make sure that you call this function after
 812         wxPropertyGrid size has been set (this may sometimes be tricky when
 813         sizers are used).
 814     */
 815     bool RestoreEditableState( const wxString& src,
 816                                int restoreStates = AllStates );
 817
 818     /**
 819         Used to acquire user-editable state (selected property, expanded
 820         properties, scrolled position, splitter positions).
 821
 822         @param includedStates
 823         Which parts of state to include. See @ref
 824         propgridinterface_editablestate_flags "list of editable state flags".
 825     */
 826     wxString SaveEditableState( int includedStates = AllStates ) const;
 827
 828     /**
 829         Lets user to set the strings listed in the choice dropdown of a
 830         wxBoolProperty. Defaults are "True" and "False", so changing them to,
 831         say, "Yes" and "No" may be useful in some less technical applications.
 832     */
 833     static void SetBoolChoices( const wxString& trueChoice,
 834                                 const wxString& falseChoice );
 835
 836     /** Sets an attribute for this property.
 837         @param name
 838             Text identifier of attribute. See @ref propgrid_property_attributes.
 839         @param value
 840             Value of attribute.
 841         @param argFlags
 842             Optional. Use wxPG_RECURSE to set the attribute to child properties
 843             recursively.
 844     */
 845     void SetPropertyAttribute( wxPGPropArg id,
 846                                const wxString& attrName,
 847                                wxVariant value,
 848                                long argFlags = 0 )
 849     {
 850         DoSetPropertyAttribute(id,attrName,value,argFlags);
 851     }
 852
 853     /** Sets property attribute for all applicapple properties.
 854         Be sure to use this method only after all properties have been
 855         added to the grid.
 856     */
 857     void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );
 858
 859     /** Sets text, bitmap, and colours for given column's cell.
 860
 861         @remarks
 862         - You can set label cell by setting column to 0.
 863         - You can use wxPG_LABEL as text to use default text for column.
 864     */
 865     void SetPropertyCell( wxPGPropArg id,
 866                           int column,
 867                           const wxString& text = wxEmptyString,
 868                           const wxBitmap& bitmap = wxNullBitmap,
 869                           const wxColour& fgCol = wxNullColour,
 870                           const wxColour& bgCol = wxNullColour );
 871
 872 #ifndef SWIG
 873     /** Sets client data (void*) of a property.
 874         @remarks
 875         This untyped client data has to be deleted manually.
 876     */
 877     void SetPropertyClientData( wxPGPropArg id, void* clientData )
 878     {
 879         wxPG_PROP_ARG_CALL_PROLOG()
 880         p->SetClientData(clientData);
 881     }
 882
 883     /** Sets editor for a property.
 884
 885         @param editor
 886         For builtin editors, use wxPGEditor_X, where X is builtin editor's
 887         name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
 888         list).
 889
 890         For custom editors, use pointer you received from
 891         wxPropertyGrid::RegisterEditorClass().
 892     */
 893     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
 894     {
 895         wxPG_PROP_ARG_CALL_PROLOG()
 896         wxCHECK_RET( editor, wxT("unknown/NULL editor") );
 897         p->SetEditor(editor);
 898         RefreshProperty(p);
 899     }
 900 #endif
 901
 902     /** Sets editor control of a property. As editor argument, use
 903         editor name string, such as "TextCtrl" or "Choice".
 904     */
 905     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
 906     {
 907         SetPropertyEditor(id,GetEditorByName(editorName));
 908     }
 909
 910     /** Sets label of a property.
 911     */
 912     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
 913
 914     /**
 915         Sets name of a property.
 916
 917         @param id
 918             Name or pointer of property which name to change.
 919
 920         @param newName
 921             New name for property.
 922     */
 923     void SetPropertyName( wxPGPropArg id, const wxString& newName )
 924     {
 925         wxPG_PROP_ARG_CALL_PROLOG()
 926         m_pState->DoSetPropertyName( p, newName );
 927     }
 928
 929     /**
 930         Sets property (and, recursively, its children) to have read-only value.
 931         In other words, user cannot change the value in the editor, but they
 932         can still copy it.
 933         @remarks
 934         This is mainly for use with textctrl editor. Not all other editors fully
 935         support it.
 936         @param flags
 937         By default changes are applied recursively. Set this paramter
 938         wxPG_DONT_RECURSE to prevent this.
 939     */
 940     void SetPropertyReadOnly( wxPGPropArg id,
 941                               bool set = true,
 942                               int flags = wxPG_RECURSE )
 943     {
 944         wxPG_PROP_ARG_CALL_PROLOG()
 945         if ( flags & wxPG_RECURSE )
 946             p->SetFlagRecursively(wxPG_PROP_READONLY, set);
 947         else
 948             p->SetFlag(wxPG_PROP_READONLY);
 949     }
 950
 951     /** Sets property's value to unspecified.
 952         If it has children (it may be category), then the same thing is done to
 953         them.
 954     */
 955     void SetPropertyValueUnspecified( wxPGPropArg id );
 956
 957 #ifndef SWIG
 958     /** Sets various property values from a list of wxVariants. If property with
 959         name is missing from the grid, new property is created under given
 960         default category (or root if omitted).
 961     */
 962     void SetPropertyValues( const wxVariantList& list,
 963                             wxPGPropArg defaultCategory = wxNullProperty )
 964     {
 965         wxPGProperty *p;
 966         if ( defaultCategory.HasName() ) p = defaultCategory.GetPtr(this);
 967         else p = defaultCategory.GetPtr0();
 968         m_pState->DoSetPropertyValues(list, p);
 969     }
 970
 971     void SetPropertyValues( const wxVariant& list,
 972                             wxPGPropArg defaultCategory = wxNullProperty )
 973     {
 974         SetPropertyValues(list.GetList(),defaultCategory);
 975     }
 976 #endif
 977
 978     /** Associates the help string with property.
 979         @remarks
 980         By default, text is shown either in the manager's "description"
 981         text box or in the status bar. If extra window style
 982         wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a
 983         tooltip.
 984     */
 985     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
 986     {
 987         wxPG_PROP_ARG_CALL_PROLOG()
 988         p->SetHelpString(helpString);
 989     }
 990
 991     /** Set wxBitmap in front of the value.
 992         @remarks
 993         - Bitmap will be scaled to a size returned by
 994         wxPropertyGrid::GetImageSize();
 995     */
 996     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp )
 997     {
 998         wxPG_PROP_ARG_CALL_PROLOG()
 999         p->SetValueImage(bmp);
1000         RefreshProperty(p);
1001     }
1002
1003     /** Sets max length of property's text.
1004     */
1005     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
1006
1007 #if wxUSE_VALIDATORS
1008     /** Sets validator of a property.
1009     */
1010     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
1011     {
1012         wxPG_PROP_ARG_CALL_PROLOG()
1013         p->SetValidator(validator);
1014     }
1015 #endif
1016
1017 #ifndef SWIG
1018     /** Sets value (long integer) of a property.
1019     */
1020     void SetPropertyValue( wxPGPropArg id, long value )
1021     {
1022         wxVariant v(value);
1023         SetPropVal( id, v );
1024     }
1025
1026     /** Sets value (integer) of a property.
1027     */
1028     void SetPropertyValue( wxPGPropArg id, int value )
1029     {
1030         wxVariant v((long)value);
1031         SetPropVal( id, v );
1032     }
1033     /** Sets value (floating point) of a property.
1034     */
1035     void SetPropertyValue( wxPGPropArg id, double value )
1036     {
1037         wxVariant v(value);
1038         SetPropVal( id, v );
1039     }
1040     /** Sets value (bool) of a property.
1041     */
1042     void SetPropertyValue( wxPGPropArg id, bool value )
1043     {
1044         wxVariant v(value);
1045         SetPropVal( id, v );
1046     }
1047 #if wxUSE_WCHAR_T
1048     void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
1049     {
1050         SetPropertyValueString( id, wxString(value) );
1051     }
1052 #endif
1053     void SetPropertyValue( wxPGPropArg id, const char* value )
1054     {
1055         SetPropertyValueString( id, wxString(value) );
1056     }
1057     void SetPropertyValue( wxPGPropArg id, const wxString& value )
1058     {
1059         SetPropertyValueString( id, value );
1060     }
1061
1062     /** Sets value (wxArrayString) of a property.
1063     */
1064     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
1065     {
1066         wxVariant v(value);
1067         SetPropVal( id, v );
1068     }
1069
1070 #if wxUSE_DATETIME
1071     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
1072     {
1073         wxVariant v(value);
1074         SetPropVal( id, v );
1075     }
1076 #endif
1077
1078     /** Sets value (wxObject*) of a property.
1079     */
1080     void SetPropertyValue( wxPGPropArg id, wxObject* value )
1081     {
1082         wxVariant v(value);
1083         SetPropVal( id, v );
1084     }
1085
1086     void SetPropertyValue( wxPGPropArg id, wxObject& value )
1087     {
1088         wxVariant v(&value);
1089         SetPropVal( id, v );
1090     }
1091
1092 #if wxUSE_LONGLONG_NATIVE
1093     /** Sets value (wxLongLong&) of a property.
1094     */
1095     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value )
1096     {
1097         wxVariant v = WXVARIANT(wxLongLong(value));
1098         SetPropVal( id, v );
1099     }
1100     /** Sets value (wxULongLong&) of a property.
1101     */
1102     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value )
1103     {
1104         wxVariant v = WXVARIANT(wxULongLong(value));
1105         SetPropVal( id, v );
1106     }
1107 #endif
1108
1109     /** Sets value (wxArrayInt&) of a property.
1110     */
1111     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
1112     {
1113         wxVariant v = WXVARIANT(value);
1114         SetPropVal( id, v );
1115     }
1116 #endif  // !SWIG
1117
1118     /** Sets value (wxString) of a property.
1119
1120         @remarks
1121         This method uses wxPGProperty::SetValueFromString, which all properties
1122         should implement. This means that there should not be a type error,
1123         and instead the string is converted to property's actual value type.
1124     */
1125     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
1126
1127     /** Sets value (wxVariant&) of a property.
1128
1129         @remarks
1130         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1131         through validation process and send property change event.
1132     */
1133     void SetPropertyValue( wxPGPropArg id, wxVariant value )
1134     {
1135         SetPropVal( id, value );
1136     }
1137
1138 #ifndef SWIG
1139     /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
1140         accepts reference. */
1141     void SetPropVal( wxPGPropArg id, wxVariant& value );
1142 #endif
1143
1144     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
1145         in a property.
1146         @param vfbFlags
1147         See @link vfbflags list of valid flags values@endlink
1148     */
1149     void SetValidationFailureBehavior( int vfbFlags );
1150
1151 #ifdef SWIG
1152     %pythoncode {
1153         def MapType(class_,factory):
1154             "Registers Python type/class to property mapping.\n\nfactory: Property builder function/class."
1155             global _type2property
1156             try:
1157                 mappings = _type2property
1158             except NameError:
1159                 raise AssertionError("call only after a propertygrid or manager instance constructed")
1160
1161             mappings[class_] = factory
1162
1163
1164         def DoDefaultTypeMappings(self):
1165             "Map built-in properties."
1166             global _type2property
1167             try:
1168                 mappings = _type2property
1169
1170                 return
1171             except NameError:
1172                 mappings = {}
1173                 _type2property = mappings
1174
1175             mappings[str] = StringProperty
1176             mappings[unicode] = StringProperty
1177             mappings[int] = IntProperty
1178             mappings[float] = FloatProperty
1179             mappings[bool] = BoolProperty
1180             mappings[list] = ArrayStringProperty
1181             mappings[tuple] = ArrayStringProperty
1182             mappings[wx.Font] = FontProperty
1183             mappings[wx.Colour] = ColourProperty
1184             "mappings[wx.Size] = SizeProperty"
1185             "mappings[wx.Point] = PointProperty"
1186             "mappings[wx.FontData] = FontDataProperty"
1187
1188         def DoDefaultValueTypeMappings(self):
1189             "Map pg value type ids to getter methods."
1190             global _vt2getter
1191             try:
1192                 vt2getter = _vt2getter
1193
1194                 return
1195             except NameError:
1196                 vt2getter = {}
1197                 _vt2getter = vt2getter
1198
1199         def GetPropertyValues(self,dict_=None, as_strings=False, inc_attributes=False):
1200             "Returns values in the grid."
1201             ""
1202             "dict_: if not given, then a new one is created. dict_ can be"
1203             "  object as well, in which case it's __dict__ is used."
1204             "as_strings: if True, then string representations of values"
1205             "  are fetched instead of native types. Useful for config and such."
1206             "inc_attributes: if True, then property attributes are added"
1207             "  as @<propname>@<attr>."
1208             ""
1209             "Return value: dictionary with values. It is always a dictionary,"
1210             "so if dict_ was object with __dict__ attribute, then that attribute"
1211             "is returned."
1212
1213             if dict_ is None:
1214                 dict_ = {}
1215             elif hasattr(dict_,'__dict__'):
1216                 dict_ = dict_.__dict__
1217
1218             if not as_strings:
1219                 getter = self.GetPropertyValue
1220             else:
1221                 getter = self.GetPropertyValueAsString
1222
1223             it = self.GetVIterator(PG_ITERATE_PROPERTIES)
1224             while not it.AtEnd():
1225                 p = it.GetProperty()
1226                 name = p.GetName()
1227
1228                 dict_[name] = getter(p)
1229
1230                 if inc_attributes:
1231                     attrs = p.GetAttributes()
1232                     if attrs and len(attrs):
1233                         dict_['@%s@attr'%name] = attrs
1234
1235                 it.Next()
1236
1237             return dict_
1238
1239         GetValues = GetPropertyValues
1240
1241
1242         def SetPropertyValues(self,dict_):
1243             "Sets property values from dict_, which can be either\ndictionary or an object with __dict__ attribute."
1244             ""
1245             "autofill: If true, keys with not relevant properties"
1246             "  are auto-created. For more info, see AutoFill."
1247             ""
1248             "Notes:"
1249             "  * Keys starting with underscore are ignored."
1250             "  * Attributes can be set with entries named @<propname>@<attr>."
1251             ""
1252
1253             autofill = False
1254
1255             if dict_ is None:
1256                 dict_ = {}
1257             elif hasattr(dict_,'__dict__'):
1258                 dict_ = dict_.__dict__
1259
1260             attr_dicts = []
1261
1262             def set_sub_obj(k0,dict_):
1263                 for k,v in dict_.iteritems():
1264                     if k[0] != '_':
1265                         if k.endswith('@attr'):
1266                             attr_dicts.append((k[1:-5],v))
1267                         else:
1268                             try:
1269                                 self.SetPropertyValue(k,v)
1270                             except:
1271                                 try:
1272                                     if autofill:
1273                                         self._AutoFillOne(k0,k,v)
1274                                         continue
1275                                 except:
1276                                     if isinstance(v,dict):
1277                                         set_sub_obj(k,v)
1278                                     elif hasattr(v,'__dict__'):
1279                                         set_sub_obj(k,v.__dict__)
1280
1281
1282             for k,v in attr_dicts:
1283                 p = GetPropertyByName(k)
1284                 if not p:
1285                     raise AssertionError("No such property: '%s'"%k)
1286                 for an,av in v.iteritems():
1287                     p.SetAttribute(an, av)
1288
1289
1290             cur_page = False
1291             is_manager = isinstance(self,PropertyGridManager)
1292
1293             try:
1294                 set_sub_obj(self.GetGrid().GetRoot(),dict_)
1295             except:
1296                 import traceback
1297                 traceback.print_exc()
1298
1299             self.Refresh()
1300
1301         SetValues = SetPropertyValues
1302
1303         def _AutoFillMany(self,cat,dict_):
1304             for k,v in dict_.iteritems():
1305                 self._AutoFillOne(cat,k,v)
1306
1307
1308         def _AutoFillOne(self,cat,k,v):
1309             global _type2property
1310
1311             factory = _type2property.get(v.__class__,None)
1312
1313             if factory:
1314                 self.AppendIn( cat, factory(k,k,v) )
1315             elif hasattr(v,'__dict__'):
1316                 cat2 = self.AppendIn( cat, PropertyCategory(k) )
1317                 self._AutoFillMany(cat2,v.__dict__)
1318             elif isinstance(v,dict):
1319                 cat2 = self.AppendIn( cat, PropertyCategory(k) )
1320                 self._AutoFillMany(cat2,v)
1321             elif not k.startswith('_'):
1322                 raise AssertionError("member '%s' is of unregisted type/class '%s'"%(k,v.__class__))
1323
1324
1325         def AutoFill(self,obj,parent=None):
1326             "Clears properties and re-fills to match members and\nvalues of given object or dictionary obj."
1327
1328             self.edited_objects[parent] = obj
1329
1330             cur_page = False
1331             is_manager = isinstance(self,PropertyGridManager)
1332
1333             if not parent:
1334                 if is_manager:
1335                     page = self.GetCurrentPage()
1336                     page.Clear()
1337                     parent = page.GetRoot()
1338                 else:
1339                     self.Clear()
1340                     parent = self.GetGrid().GetRoot()
1341             else:
1342                 it = self.GetIterator(PG_ITERATE_PROPERTIES, parent)
1343                 it.Next()  # Skip the parent
1344                 while not it.AtEnd():
1345                     p = it.GetProperty()
1346                     if not p.IsSomeParent(parent):
1347                         break
1348
1349                     self.DeleteProperty(p)
1350
1351                     name = p.GetName()
1352                     it.Next()
1353
1354             if not is_manager or page == self.GetCurrentPage():
1355                 self.Freeze()
1356                 cur_page = True
1357
1358             try:
1359                 self._AutoFillMany(parent,obj.__dict__)
1360             except:
1361                 import traceback
1362                 traceback.print_exc()
1363
1364             if cur_page:
1365                 self.Thaw()
1366
1367         def RegisterEditor(self, editor, editorName=None):
1368             "Transform class into instance, if necessary."
1369             if not isinstance(editor, PGEditor):
1370                 editor = editor()
1371             if not editorName:
1372                 editorName = editor.__class__.__name__
1373             try:
1374                 self._editor_instances.append(editor)
1375             except:
1376                 self._editor_instances = [editor]
1377             RegisterEditor(editor, editorName)
1378
1379         def GetPropertyClientData(self, p):
1380             if isinstance(p, basestring):
1381                 p = self.GetPropertyByName(p)
1382             return p.GetClientData()
1383
1384         def SetPropertyClientData(self, p, data):
1385             if isinstance(p, basestring):
1386                 p = self.GetPropertyByName(p)
1387             return p.SetClientData(data)
1388     }
1389 #endif
1390
1391     // GetPropertyByName With nice assertion error message.
1392     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
1393
1394     static wxPGEditor* GetEditorByName( const wxString& editorName );
1395
1396     virtual void RefreshProperty( wxPGProperty* p ) = 0;
1397
1398 protected:
1399
1400     /**
1401         In derived class, implement to set editable state component with
1402         given name to given value.
1403     */
1404     virtual bool SetEditableStateItem( const wxString& name, wxVariant value )
1405     {
1406         wxUnusedVar(name);
1407         wxUnusedVar(value);
1408         return false;
1409     }
1410
1411     /**
1412         In derived class, implement to return editable state component with
1413         given name.
1414     */
1415     virtual wxVariant GetEditableStateItem( const wxString& name ) const
1416     {
1417         wxUnusedVar(name);
1418         return wxNullVariant;
1419     }
1420
1421     // Returns page state data for given (sub) page (-1 means current page).
1422     virtual wxPropertyGridPageState* GetPageState( int pageIndex ) const
1423     {
1424         if ( pageIndex <= 0 )
1425             return m_pState;
1426         return NULL;
1427     }
1428
1429     virtual bool DoSelectPage( int WXUNUSED(index) ) { return true; }
1430
1431     // Default call's m_pState's BaseGetPropertyByName
1432     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
1433
1434 #ifndef SWIG
1435
1436     // Deriving classes must set this (it must be only or current page).
1437     wxPropertyGridPageState*         m_pState;
1438
1439     // Intermediate version needed due to wxVariant copying inefficiency
1440     void DoSetPropertyAttribute( wxPGPropArg id,
1441                                  const wxString& name,
1442                                  wxVariant& value, long argFlags );
1443
1444     // Empty string object to return from member functions returning const
1445     // wxString&.
1446     wxString                    m_emptyString;
1447
1448 private:
1449     // Cannot be GetGrid() due to ambiguity issues.
1450     wxPropertyGrid* GetPropertyGrid()
1451     {
1452         return m_pState->GetGrid();
1453     }
1454
1455     // Cannot be GetGrid() due to ambiguity issues.
1456     const wxPropertyGrid* GetPropertyGrid() const
1457     {
1458         return (const wxPropertyGrid*) m_pState->GetGrid();
1459     }
1460 #endif // #ifndef SWIG
1461
1462     friend class wxPropertyGrid;
1463     friend class wxPropertyGridManager;
1464 };
1465
1466 #endif // wxUSE_PROPGRID
1467
1468 #endif // __WX_PROPGRID_PROPGRIDIFACE_H__