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         /** Include description box size.
 798             Only applies to wxPropertyGridManager. */
 799         DescBoxState     = 0x20,
 800
 801         /**
 802             Include all supported user editable state information.
 803             This is usually the default value. */
 804         AllStates        = SelectionState |
 805                            ExpandedState |
 806                            ScrollPosState |
 807                            PageState |
 808                            SplitterPosState |
 809                            DescBoxState
 810     };
 811
 812     /**
 813         Restores user-editable state.
 814
 815         See also wxPropertyGridInterface::SaveEditableState().
 816
 817         @param src
 818             String generated by SaveEditableState.
 819
 820         @param restoreStates
 821             Which parts to restore from source string. See @ref
 822             propgridinterface_editablestate_flags "list of editable state
 823             flags".
 824
 825         @return
 826             False if there was problem reading the string.
 827
 828         @remarks
 829         If some parts of state (such as scrolled or splitter position) fail to
 830         restore correctly, please make sure that you call this function after
 831         wxPropertyGrid size has been set (this may sometimes be tricky when
 832         sizers are used).
 833     */
 834     bool RestoreEditableState( const wxString& src,
 835                                int restoreStates = AllStates );
 836
 837     /**
 838         Used to acquire user-editable state (selected property, expanded
 839         properties, scrolled position, splitter positions).
 840
 841         @param includedStates
 842         Which parts of state to include. See @ref
 843         propgridinterface_editablestate_flags "list of editable state flags".
 844     */
 845     wxString SaveEditableState( int includedStates = AllStates ) const;
 846
 847     /**
 848         Lets user to set the strings listed in the choice dropdown of a
 849         wxBoolProperty. Defaults are "True" and "False", so changing them to,
 850         say, "Yes" and "No" may be useful in some less technical applications.
 851     */
 852     static void SetBoolChoices( const wxString& trueChoice,
 853                                 const wxString& falseChoice );
 854
 855     /** Sets or clears flag(s) of all properties in given array.
 856         @param flags
 857         Property flags to set or clear.
 858         @param inverse
 859         Set to true if you want to clear flag instead of setting them.
 860     */
 861     void SetPropertiesFlag( const wxArrayPGProperty& srcArr,
 862                             wxPGProperty::FlagType flags,
 863                             bool inverse = false );
 864
 865     /** Sets an attribute for this property.
 866         @param name
 867             Text identifier of attribute. See @ref propgrid_property_attributes.
 868         @param value
 869             Value of attribute.
 870         @param argFlags
 871             Optional. Use wxPG_RECURSE to set the attribute to child properties
 872             recursively.
 873     */
 874     void SetPropertyAttribute( wxPGPropArg id,
 875                                const wxString& attrName,
 876                                wxVariant value,
 877                                long argFlags = 0 )
 878     {
 879         DoSetPropertyAttribute(id,attrName,value,argFlags);
 880     }
 881
 882     /** Sets property attribute for all applicapple properties.
 883         Be sure to use this method only after all properties have been
 884         added to the grid.
 885     */
 886     void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );
 887
 888     /** Sets attributes from a wxPGAttributeStorage.
 889     */
 890     void SetPropertyAttributes( wxPGPropArg id,
 891                                 const wxPGAttributeStorage& attributes )
 892     {
 893         wxPG_PROP_ARG_CALL_PROLOG()
 894         p->SetAttributes(attributes);
 895     }
 896
 897     /** Sets text, bitmap, and colours for given column's cell.
 898
 899         @remarks
 900         - You can set label cell by setting column to 0.
 901         - You can use wxPG_LABEL as text to use default text for column.
 902     */
 903     void SetPropertyCell( wxPGPropArg id,
 904                           int column,
 905                           const wxString& text = wxEmptyString,
 906                           const wxBitmap& bitmap = wxNullBitmap,
 907                           const wxColour& fgCol = wxNullColour,
 908                           const wxColour& bgCol = wxNullColour )
 909     {
 910         wxPG_PROP_ARG_CALL_PROLOG()
 911         p->SetCell( column, new wxPGCell(text, bitmap, fgCol, bgCol) );
 912     }
 913
 914 #ifndef SWIG
 915     /** Sets client data (void*) of a property.
 916         @remarks
 917         This untyped client data has to be deleted manually.
 918     */
 919     void SetPropertyClientData( wxPGPropArg id, void* clientData )
 920     {
 921         wxPG_PROP_ARG_CALL_PROLOG()
 922         p->SetClientData(clientData);
 923     }
 924
 925     /** Sets editor for a property.
 926
 927         @param editor
 928         For builtin editors, use wxPGEditor_X, where X is builtin editor's
 929         name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
 930         list).
 931
 932         For custom editors, use pointer you received from
 933         wxPropertyGrid::RegisterEditorClass().
 934     */
 935     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
 936     {
 937         wxPG_PROP_ARG_CALL_PROLOG()
 938         wxCHECK_RET( editor, wxT("unknown/NULL editor") );
 939         p->SetEditor(editor);
 940         RefreshProperty(p);
 941     }
 942 #endif
 943
 944     /** Sets editor control of a property. As editor argument, use
 945         editor name string, such as "TextCtrl" or "Choice".
 946     */
 947     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
 948     {
 949         SetPropertyEditor(id,GetEditorByName(editorName));
 950     }
 951
 952     /** Sets label of a property.
 953     */
 954     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
 955
 956     /**
 957         Sets name of a property.
 958
 959         @param id
 960             Name or pointer of property which name to change.
 961
 962         @param newName
 963             New name for property.
 964     */
 965     void SetPropertyName( wxPGPropArg id, const wxString& newName )
 966     {
 967         wxPG_PROP_ARG_CALL_PROLOG()
 968         m_pState->DoSetPropertyName( p, newName );
 969     }
 970
 971     /**
 972         Sets property (and, recursively, its children) to have read-only value.
 973         In other words, user cannot change the value in the editor, but they
 974         can still copy it.
 975         @remarks
 976         This is mainly for use with textctrl editor. Not all other editors fully
 977         support it.
 978         @param flags
 979         By default changes are applied recursively. Set this paramter
 980         wxPG_DONT_RECURSE to prevent this.
 981     */
 982     void SetPropertyReadOnly( wxPGPropArg id,
 983                               bool set = true,
 984                               int flags = wxPG_RECURSE )
 985     {
 986         wxPG_PROP_ARG_CALL_PROLOG()
 987         if ( flags & wxPG_RECURSE )
 988             p->SetFlagRecursively(wxPG_PROP_READONLY, set);
 989         else
 990             p->SetFlag(wxPG_PROP_READONLY);
 991     }
 992
 993     /** Sets property's value to unspecified.
 994         If it has children (it may be category), then the same thing is done to
 995         them.
 996     */
 997     void SetPropertyValueUnspecified( wxPGPropArg id );
 998
 999 #ifndef SWIG
1000     /** Sets various property values from a list of wxVariants. If property with
1001         name is missing from the grid, new property is created under given
1002         default category (or root if omitted).
1003     */
1004     void SetPropertyValues( const wxVariantList& list,
1005                             wxPGPropArg defaultCategory = wxNullProperty )
1006     {
1007         wxPGProperty *p;
1008         if ( defaultCategory.HasName() ) p = defaultCategory.GetPtr(this);
1009         else p = defaultCategory.GetPtr0();
1010         m_pState->DoSetPropertyValues(list, p);
1011     }
1012
1013     void SetPropertyValues( const wxVariant& list,
1014                             wxPGPropArg defaultCategory = wxNullProperty )
1015     {
1016         SetPropertyValues(list.GetList(),defaultCategory);
1017     }
1018 #endif
1019
1020     /** Associates the help string with property.
1021         @remarks
1022         By default, text is shown either in the manager's "description"
1023         text box or in the status bar. If extra window style
1024         wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a
1025         tooltip.
1026     */
1027     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
1028     {
1029         wxPG_PROP_ARG_CALL_PROLOG()
1030         p->SetHelpString(helpString);
1031     }
1032
1033     /** Set wxBitmap in front of the value.
1034         @remarks
1035         - Bitmap will be scaled to a size returned by
1036         wxPropertyGrid::GetImageSize();
1037     */
1038     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp )
1039     {
1040         wxPG_PROP_ARG_CALL_PROLOG()
1041         p->SetValueImage(bmp);
1042         RefreshProperty(p);
1043     }
1044
1045     /** Sets max length of property's text.
1046     */
1047     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
1048
1049 #if wxUSE_VALIDATORS
1050     /** Sets validator of a property.
1051     */
1052     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
1053     {
1054         wxPG_PROP_ARG_CALL_PROLOG()
1055         p->SetValidator(validator);
1056     }
1057 #endif
1058
1059 #ifndef SWIG
1060     /** Sets value (long integer) of a property.
1061     */
1062     void SetPropertyValue( wxPGPropArg id, long value )
1063     {
1064         wxVariant v(value);
1065         SetPropVal( id, v );
1066     }
1067
1068     /** Sets value (integer) of a property.
1069     */
1070     void SetPropertyValue( wxPGPropArg id, int value )
1071     {
1072         wxVariant v((long)value);
1073         SetPropVal( id, v );
1074     }
1075     /** Sets value (floating point) of a property.
1076     */
1077     void SetPropertyValue( wxPGPropArg id, double value )
1078     {
1079         wxVariant v(value);
1080         SetPropVal( id, v );
1081     }
1082     /** Sets value (bool) of a property.
1083     */
1084     void SetPropertyValue( wxPGPropArg id, bool value )
1085     {
1086         wxVariant v(value);
1087         SetPropVal( id, v );
1088     }
1089 #if wxUSE_WCHAR_T
1090     void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
1091     {
1092         SetPropertyValueString( id, wxString(value) );
1093     }
1094 #endif
1095     void SetPropertyValue( wxPGPropArg id, const char* value )
1096     {
1097         SetPropertyValueString( id, wxString(value) );
1098     }
1099     void SetPropertyValue( wxPGPropArg id, const wxString& value )
1100     {
1101         SetPropertyValueString( id, value );
1102     }
1103
1104     /** Sets value (wxArrayString) of a property.
1105     */
1106     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
1107     {
1108         wxVariant v(value);
1109         SetPropVal( id, v );
1110     }
1111
1112 #if wxUSE_DATETIME
1113     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
1114     {
1115         wxVariant v(value);
1116         SetPropVal( id, v );
1117     }
1118 #endif
1119
1120     /** Sets value (wxObject*) of a property.
1121     */
1122     void SetPropertyValue( wxPGPropArg id, wxObject* value )
1123     {
1124         wxVariant v(value);
1125         SetPropVal( id, v );
1126     }
1127
1128     void SetPropertyValue( wxPGPropArg id, wxObject& value )
1129     {
1130         wxVariant v(&value);
1131         SetPropVal( id, v );
1132     }
1133
1134 #if wxUSE_LONGLONG_NATIVE
1135     /** Sets value (wxLongLong&) of a property.
1136     */
1137     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value )
1138     {
1139         wxVariant v = WXVARIANT(wxLongLong(value));
1140         SetPropVal( id, v );
1141     }
1142     /** Sets value (wxULongLong&) of a property.
1143     */
1144     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value )
1145     {
1146         wxVariant v = WXVARIANT(wxULongLong(value));
1147         SetPropVal( id, v );
1148     }
1149 #endif
1150
1151     /** Sets value (wxArrayInt&) of a property.
1152     */
1153     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
1154     {
1155         wxVariant v = WXVARIANT(value);
1156         SetPropVal( id, v );
1157     }
1158 #endif  // !SWIG
1159
1160     /** Sets value (wxString) of a property.
1161
1162         @remarks
1163         This method uses wxPGProperty::SetValueFromString, which all properties
1164         should implement. This means that there should not be a type error,
1165         and instead the string is converted to property's actual value type.
1166     */
1167     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
1168
1169     /** Sets value (wxVariant&) of a property.
1170
1171         @remarks
1172         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1173         through validation process and send property change event.
1174     */
1175     void SetPropertyValue( wxPGPropArg id, wxVariant value )
1176     {
1177         SetPropVal( id, value );
1178     }
1179
1180 #ifndef SWIG
1181     /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
1182         accepts reference. */
1183     void SetPropVal( wxPGPropArg id, wxVariant& value );
1184 #endif
1185
1186     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
1187         in a property.
1188         @param vfbFlags
1189         See @link vfbflags list of valid flags values@endlink
1190     */
1191     void SetValidationFailureBehavior( int vfbFlags );
1192
1193 #ifdef SWIG
1194     %pythoncode {
1195         def MapType(class_,factory):
1196             "Registers Python type/class to property mapping.\n\nfactory: Property builder function/class."
1197             global _type2property
1198             try:
1199                 mappings = _type2property
1200             except NameError:
1201                 raise AssertionError("call only after a propertygrid or manager instance constructed")
1202
1203             mappings[class_] = factory
1204
1205
1206         def DoDefaultTypeMappings(self):
1207             "Map built-in properties."
1208             global _type2property
1209             try:
1210                 mappings = _type2property
1211
1212                 return
1213             except NameError:
1214                 mappings = {}
1215                 _type2property = mappings
1216
1217             mappings[str] = StringProperty
1218             mappings[unicode] = StringProperty
1219             mappings[int] = IntProperty
1220             mappings[float] = FloatProperty
1221             mappings[bool] = BoolProperty
1222             mappings[list] = ArrayStringProperty
1223             mappings[tuple] = ArrayStringProperty
1224             mappings[wx.Font] = FontProperty
1225             mappings[wx.Colour] = ColourProperty
1226             "mappings[wx.Size] = SizeProperty"
1227             "mappings[wx.Point] = PointProperty"
1228             "mappings[wx.FontData] = FontDataProperty"
1229
1230         def DoDefaultValueTypeMappings(self):
1231             "Map pg value type ids to getter methods."
1232             global _vt2getter
1233             try:
1234                 vt2getter = _vt2getter
1235
1236                 return
1237             except NameError:
1238                 vt2getter = {}
1239                 _vt2getter = vt2getter
1240
1241         def GetPropertyValues(self,dict_=None, as_strings=False, inc_attributes=False):
1242             "Returns values in the grid."
1243             ""
1244             "dict_: if not given, then a new one is created. dict_ can be"
1245             "  object as well, in which case it's __dict__ is used."
1246             "as_strings: if True, then string representations of values"
1247             "  are fetched instead of native types. Useful for config and such."
1248             "inc_attributes: if True, then property attributes are added"
1249             "  as @<propname>@<attr>."
1250             ""
1251             "Return value: dictionary with values. It is always a dictionary,"
1252             "so if dict_ was object with __dict__ attribute, then that attribute"
1253             "is returned."
1254
1255             if dict_ is None:
1256                 dict_ = {}
1257             elif hasattr(dict_,'__dict__'):
1258                 dict_ = dict_.__dict__
1259
1260             if not as_strings:
1261                 getter = self.GetPropertyValue
1262             else:
1263                 getter = self.GetPropertyValueAsString
1264
1265             it = self.GetVIterator(PG_ITERATE_PROPERTIES)
1266             while not it.AtEnd():
1267                 p = it.GetProperty()
1268                 name = p.GetName()
1269
1270                 dict_[name] = getter(p)
1271
1272                 if inc_attributes:
1273                     attrs = p.GetAttributes()
1274                     if attrs and len(attrs):
1275                         dict_['@%s@attr'%name] = attrs
1276
1277                 it.Next()
1278
1279             return dict_
1280
1281         GetValues = GetPropertyValues
1282
1283
1284         def SetPropertyValues(self,dict_):
1285             "Sets property values from dict_, which can be either\ndictionary or an object with __dict__ attribute."
1286             ""
1287             "autofill: If true, keys with not relevant properties"
1288             "  are auto-created. For more info, see AutoFill."
1289             ""
1290             "Notes:"
1291             "  * Keys starting with underscore are ignored."
1292             "  * Attributes can be set with entries named @<propname>@<attr>."
1293             ""
1294
1295             autofill = False
1296
1297             if dict_ is None:
1298                 dict_ = {}
1299             elif hasattr(dict_,'__dict__'):
1300                 dict_ = dict_.__dict__
1301
1302             attr_dicts = []
1303
1304             def set_sub_obj(k0,dict_):
1305                 for k,v in dict_.iteritems():
1306                     if k[0] != '_':
1307                         if k.endswith('@attr'):
1308                             attr_dicts.append((k[1:-5],v))
1309                         else:
1310                             try:
1311                                 self.SetPropertyValue(k,v)
1312                             except:
1313                                 try:
1314                                     if autofill:
1315                                         self._AutoFillOne(k0,k,v)
1316                                         continue
1317                                 except:
1318                                     if isinstance(v,dict):
1319                                         set_sub_obj(k,v)
1320                                     elif hasattr(v,'__dict__'):
1321                                         set_sub_obj(k,v.__dict__)
1322
1323
1324             for k,v in attr_dicts:
1325                 p = GetPropertyByName(k)
1326                 if not p:
1327                     raise AssertionError("No such property: '%s'"%k)
1328                 for an,av in v.iteritems():
1329                     p.SetAttribute(an, av)
1330
1331
1332             cur_page = False
1333             is_manager = isinstance(self,PropertyGridManager)
1334
1335             try:
1336                 set_sub_obj(self.GetGrid().GetRoot(),dict_)
1337             except:
1338                 import traceback
1339                 traceback.print_exc()
1340
1341             self.Refresh()
1342
1343         SetValues = SetPropertyValues
1344
1345         def _AutoFillMany(self,cat,dict_):
1346             for k,v in dict_.iteritems():
1347                 self._AutoFillOne(cat,k,v)
1348
1349
1350         def _AutoFillOne(self,cat,k,v):
1351             global _type2property
1352
1353             factory = _type2property.get(v.__class__,None)
1354
1355             if factory:
1356                 self.AppendIn( cat, factory(k,k,v) )
1357             elif hasattr(v,'__dict__'):
1358                 cat2 = self.AppendIn( cat, PropertyCategory(k) )
1359                 self._AutoFillMany(cat2,v.__dict__)
1360             elif isinstance(v,dict):
1361                 cat2 = self.AppendIn( cat, PropertyCategory(k) )
1362                 self._AutoFillMany(cat2,v)
1363             elif not k.startswith('_'):
1364                 raise AssertionError("member '%s' is of unregisted type/class '%s'"%(k,v.__class__))
1365
1366
1367         def AutoFill(self,obj,parent=None):
1368             "Clears properties and re-fills to match members and\nvalues of given object or dictionary obj."
1369
1370             self.edited_objects[parent] = obj
1371
1372             cur_page = False
1373             is_manager = isinstance(self,PropertyGridManager)
1374
1375             if not parent:
1376                 if is_manager:
1377                     page = self.GetCurrentPage()
1378                     page.Clear()
1379                     parent = page.GetRoot()
1380                 else:
1381                     self.Clear()
1382                     parent = self.GetGrid().GetRoot()
1383             else:
1384                 it = self.GetIterator(PG_ITERATE_PROPERTIES, parent)
1385                 it.Next()  # Skip the parent
1386                 while not it.AtEnd():
1387                     p = it.GetProperty()
1388                     if not p.IsSomeParent(parent):
1389                         break
1390
1391                     self.DeleteProperty(p)
1392
1393                     name = p.GetName()
1394                     it.Next()
1395
1396             if not is_manager or page == self.GetCurrentPage():
1397                 self.Freeze()
1398                 cur_page = True
1399
1400             try:
1401                 self._AutoFillMany(parent,obj.__dict__)
1402             except:
1403                 import traceback
1404                 traceback.print_exc()
1405
1406             if cur_page:
1407                 self.Thaw()
1408
1409         def RegisterEditor(self, editor, editorName=None):
1410             "Transform class into instance, if necessary."
1411             if not isinstance(editor, PGEditor):
1412                 editor = editor()
1413             if not editorName:
1414                 editorName = editor.__class__.__name__
1415             try:
1416                 self._editor_instances.append(editor)
1417             except:
1418                 self._editor_instances = [editor]
1419             RegisterEditor(editor, editorName)
1420
1421         def GetPropertyClientData(self, p):
1422             if isinstance(p, basestring):
1423                 p = self.GetPropertyByName(p)
1424             return p.GetClientData()
1425
1426         def SetPropertyClientData(self, p, data):
1427             if isinstance(p, basestring):
1428                 p = self.GetPropertyByName(p)
1429             return p.SetClientData(data)
1430     }
1431 #endif
1432
1433     // GetPropertyByName With nice assertion error message.
1434     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
1435
1436     static wxPGEditor* GetEditorByName( const wxString& editorName );
1437
1438     virtual void RefreshProperty( wxPGProperty* p ) = 0;
1439
1440 protected:
1441
1442     /**
1443         In derived class, implement to set editable state component with
1444         given name to given value.
1445     */
1446     virtual bool SetEditableStateItem( const wxString& name, wxVariant value )
1447     {
1448         wxUnusedVar(name);
1449         wxUnusedVar(value);
1450         return false;
1451     }
1452
1453     /**
1454         In derived class, implement to return editable state component with
1455         given name.
1456     */
1457     virtual wxVariant GetEditableStateItem( const wxString& name ) const
1458     {
1459         wxUnusedVar(name);
1460         return wxNullVariant;
1461     }
1462
1463     // Returns page state data for given (sub) page (-1 means current page).
1464     virtual wxPropertyGridPageState* GetPageState( int pageIndex ) const
1465     {
1466         if ( pageIndex <= 0 )
1467             return m_pState;
1468         return NULL;
1469     }
1470
1471     virtual bool DoSelectPage( int WXUNUSED(index) ) { return true; }
1472
1473     // Default call's m_pState's BaseGetPropertyByName
1474     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
1475
1476 #ifndef SWIG
1477
1478     // Deriving classes must set this (it must be only or current page).
1479     wxPropertyGridPageState*         m_pState;
1480
1481     // Intermediate version needed due to wxVariant copying inefficiency
1482     void DoSetPropertyAttribute( wxPGPropArg id,
1483                                  const wxString& name,
1484                                  wxVariant& value, long argFlags );
1485
1486     // Empty string object to return from member functions returning const
1487     // wxString&.
1488     wxString                    m_emptyString;
1489
1490 private:
1491     // Cannot be GetGrid() due to ambiguity issues.
1492     wxPropertyGrid* GetPropertyGrid()
1493     {
1494         return m_pState->GetGrid();
1495     }
1496
1497     // Cannot be GetGrid() due to ambiguity issues.
1498     const wxPropertyGrid* GetPropertyGrid() const
1499     {
1500         return (const wxPropertyGrid*) m_pState->GetGrid();
1501     }
1502 #endif // #ifndef SWIG
1503
1504     friend class wxPropertyGrid;
1505     friend class wxPropertyGridManager;
1506 };
1507
1508 #endif // wxUSE_PROPGRID
1509
1510 #endif // __WX_PROPGRID_PROPGRIDIFACE_H__