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