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