include/wx/propgrid/propgridiface.h

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