include/wx/propgrid/propgridiface.h

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