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