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