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 /** @section wxPGPropArgCls
  23
  24     Most property grid functions have this type as their argument, as it can
  25     convey a property by either a pointer or name.
  26 */
  27 class WXDLLIMPEXP_PROPGRID wxPGPropArgCls
  28 {
  29 public:
  30     wxPGPropArgCls() { }
  31     wxPGPropArgCls( const wxPGProperty* property )
  32     {
  33         m_ptr.property = (wxPGProperty*) property;
  34         m_flags = IsProperty;
  35     }
  36     wxPGPropArgCls( const wxString& str )
  37     {
  38         m_ptr.stringName = &str;
  39         m_flags = IsWxString;
  40     }
  41     wxPGPropArgCls( const wxPGPropArgCls& id )
  42     {
  43         m_ptr = id.m_ptr;
  44         m_flags = id.m_flags;
  45     }
  46     // This is only needed for wxPython bindings
  47     wxPGPropArgCls( wxString* str, bool WXUNUSED(deallocPtr) )
  48     {
  49         m_ptr.stringName = str;
  50         m_flags = IsWxString | OwnsWxString;
  51     }
  52     ~wxPGPropArgCls()
  53     {
  54         if ( m_flags & OwnsWxString )
  55             delete m_ptr.stringName;
  56     }
  57     wxPGProperty* GetPtr() const
  58     {
  59         wxCHECK( m_flags == IsProperty, NULL );
  60         return m_ptr.property;
  61     }
  62     wxPGPropArgCls( const char* str )
  63     {
  64         m_ptr.charName = str;
  65         m_flags = IsCharPtr;
  66     }
  67 #if wxUSE_WCHAR_T
  68     wxPGPropArgCls( const wchar_t* str )
  69     {
  70         m_ptr.wcharName = str;
  71         m_flags = IsWCharPtr;
  72     }
  73 #endif
  74     /** This constructor is required for NULL. */
  75     wxPGPropArgCls( int )
  76     {
  77         m_ptr.property = NULL;
  78         m_flags = IsProperty;
  79     }
  80     wxPGProperty* GetPtr( wxPropertyGridInterface* iface ) const;
  81     wxPGProperty* GetPtr( const wxPropertyGridInterface* iface ) const
  82     {
  83         return GetPtr((wxPropertyGridInterface*)iface);
  84     }
  85     wxPGProperty* GetPtr0() const { return m_ptr.property; }
  86     bool HasName() const { return (m_flags != IsProperty); }
  87     const wxString& GetName() const { return *m_ptr.stringName; }
  88 private:
  89
  90     enum
  91     {
  92         IsProperty      = 0x00,
  93         IsWxString      = 0x01,
  94         IsCharPtr       = 0x02,
  95         IsWCharPtr      = 0x04,
  96         OwnsWxString    = 0x10
  97     };
  98
  99     union
 100     {
 101         wxPGProperty* property;
 102         const char* charName;
 103 #if wxUSE_WCHAR_T
 104         const wchar_t* wcharName;
 105 #endif
 106         const wxString* stringName;
 107     } m_ptr;
 108     unsigned char m_flags;
 109 };
 110
 111 typedef const wxPGPropArgCls& wxPGPropArg;
 112
 113 // -----------------------------------------------------------------------
 114
 115 WXDLLIMPEXP_PROPGRID
 116 void wxPGTypeOperationFailed( const wxPGProperty* p,
 117                               const wxString& typestr,
 118                               const wxString& op );
 119 WXDLLIMPEXP_PROPGRID
 120 void wxPGGetFailed( const wxPGProperty* p, const wxString& typestr );
 121
 122 // -----------------------------------------------------------------------
 123
 124 // Helper macro that does necessary preparations when calling
 125 // some wxPGProperty's member function.
 126 #define wxPG_PROP_ARG_CALL_PROLOG_0(PROPERTY) \
 127     PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
 128     if ( !p ) return;
 129
 130 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(PROPERTY, RETVAL) \
 131     PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
 132     if ( !p ) return RETVAL;
 133
 134 #define wxPG_PROP_ARG_CALL_PROLOG() \
 135     wxPG_PROP_ARG_CALL_PROLOG_0(wxPGProperty)
 136
 137 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL(RVAL) \
 138     wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(wxPGProperty, RVAL)
 139
 140 #define wxPG_PROP_ID_CONST_CALL_PROLOG() \
 141     wxPG_PROP_ARG_CALL_PROLOG_0(const wxPGProperty)
 142
 143 #define wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(RVAL) \
 144     wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(const wxPGProperty, RVAL)
 145
 146 // -----------------------------------------------------------------------
 147
 148
 149 /** @class wxPropertyGridInterface
 150
 151     Most of the shared property manipulation interface shared by wxPropertyGrid,
 152     wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
 153
 154     @remarks
 155     - In separate wxPropertyGrid component this class was known as
 156     wxPropertyContainerMethods.
 157
 158     @library{wxpropgrid}
 159     @category{propgrid}
 160 */
 161 class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
 162 {
 163 public:
 164
 165     /** Destructor */
 166     virtual ~wxPropertyGridInterface() { }
 167
 168     /**
 169         Appends property to the list.
 170
 171         wxPropertyGrid assumes ownership of the object.
 172         Becomes child of most recently added category.
 173         @remarks
 174         - wxPropertyGrid takes the ownership of the property pointer.
 175         - If appending a category with name identical to a category already in
 176           the wxPropertyGrid, then newly created category is deleted, and most
 177           recently added category (under which properties are appended) is set
 178           to the one with same name. This allows easier adding of items to same
 179           categories in multiple passes.
 180         - Does not automatically redraw the control, so you may need to call
 181           Refresh when calling this function after control has been shown for
 182           the first time.
 183     */
 184     wxPGProperty* Append( wxPGProperty* property );
 185
 186     wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newproperty );
 187
 188     /**
 189         In order to add new items into a property with fixed children (for
 190         instance, wxFlagsProperty), you need to call this method. After
 191         populating has been finished, you need to call EndAddChildren.
 192     */
 193     void BeginAddChildren( wxPGPropArg id );
 194
 195     /** Deletes all properties.
 196     */
 197     virtual void Clear() = 0;
 198
 199     /**
 200         Clears current selection, if any.
 201
 202         @param validation
 203             If set to @false, deselecting the property will always work,
 204             even if its editor had invalid value in it.
 205
 206         @return Returns @true if successful or if there was no selection. May
 207                 fail if validation was enabled and active editor had invalid
 208                 value.
 209
 210         @remarks In wxPropertyGrid 1.4, this member function used to send
 211                  wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer
 212                  does that.
 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     /** Returns client data (void*) of a property. */
 415     void* GetPropertyClientData( wxPGPropArg id ) const
 416     {
 417         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 418         return p->GetClientData();
 419     }
 420
 421     /**
 422         Returns first property which label matches given string.
 423
 424         NULL if none found. Note that this operation is extremely slow when
 425         compared to GetPropertyByName().
 426     */
 427     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 428
 429     /** Returns property with given name. NULL if none found.
 430     */
 431     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 432
 433     /** Returns child property 'subname' of property 'name'. Same as
 434         calling GetPropertyByName("name.subname"), albeit slightly faster.
 435     */
 436     wxPGProperty* GetPropertyByName( const wxString& name,
 437                                      const wxString& subname ) const;
 438
 439     /** Returns property's editor. */
 440     const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const
 441     {
 442         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 443         return p->GetEditorClass();
 444     }
 445
 446     /** Returns help string associated with a property. */
 447     wxString GetPropertyHelpString( wxPGPropArg id ) const
 448     {
 449         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 450         return p->GetHelpString();
 451     }
 452
 453     /** Returns property's custom value image (NULL of none). */
 454     wxBitmap* GetPropertyImage( wxPGPropArg id ) const
 455     {
 456         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 457         return p->GetValueImage();
 458     }
 459
 460     /** Returns label of a property. */
 461     const wxString& GetPropertyLabel( wxPGPropArg id )
 462     {
 463         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 464         return p->GetLabel();
 465     }
 466
 467     /** Returns name of a property, by which it is globally accessible. */
 468     wxString GetPropertyName( wxPGProperty* property )
 469     {
 470         return property->GetName();
 471     }
 472
 473     /** Returns parent item of a property. */
 474     wxPGProperty* GetPropertyParent( wxPGPropArg id )
 475     {
 476         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
 477         return p->GetParent();
 478     }
 479
 480 #if wxUSE_VALIDATORS
 481     /** Returns validator of a property as a reference, which you
 482         can pass to any number of SetPropertyValidator.
 483     */
 484     wxValidator* GetPropertyValidator( wxPGPropArg id )
 485     {
 486         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 487         return p->GetValidator();
 488     }
 489 #endif
 490
 491     /** Returns value as wxVariant. To get wxObject pointer from it,
 492         you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro.
 493
 494         If property value is unspecified, Null variant is returned.
 495     */
 496     wxVariant GetPropertyValue( wxPGPropArg id )
 497     {
 498         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant())
 499         return p->GetValue();
 500     }
 501
 502     wxString GetPropertyValueAsString( wxPGPropArg id ) const;
 503     long GetPropertyValueAsLong( wxPGPropArg id ) const;
 504     unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const
 505     {
 506         return (unsigned long) GetPropertyValueAsLong(id);
 507     }
 508     int GetPropertyValueAsInt( wxPGPropArg id ) const
 509         { return (int)GetPropertyValueAsLong(id); }
 510     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
 511     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 512
 513 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(TYPENAME, DEFVAL) \
 514     wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
 515     wxString typeName(wxS(TYPENAME)); \
 516     wxVariant value = p->GetValue(); \
 517     if ( value.GetType() != typeName ) \
 518     { \
 519         wxPGGetFailed(p, typeName); \
 520         return DEFVAL; \
 521     }
 522
 523 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(TYPENAME, DEFVAL) \
 524     wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
 525     wxVariant value = p->GetValue(); \
 526     if ( value.GetType() != wxS(TYPENAME) ) \
 527         return DEFVAL; \
 528
 529     wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const
 530     {
 531         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("arrstring",
 532                                                    wxArrayString())
 533         return value.GetArrayString();
 534     }
 535
 536 #ifdef wxLongLong_t
 537     wxLongLong_t GetPropertyValueAsLongLong( wxPGPropArg id ) const
 538     {
 539         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
 540         return p->GetValue().GetLongLong().GetValue();
 541     }
 542
 543     wxULongLong_t GetPropertyValueAsULongLong( wxPGPropArg id ) const
 544     {
 545         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
 546         return p->GetValue().GetULongLong().GetValue();
 547     }
 548 #endif
 549
 550     wxArrayInt GetPropertyValueAsArrayInt( wxPGPropArg id ) const
 551     {
 552         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("wxArrayInt",
 553                                                    wxArrayInt())
 554         wxArrayInt arr;
 555         arr << value;
 556         return arr;
 557     }
 558
 559 #if wxUSE_DATETIME
 560     wxDateTime GetPropertyValueAsDateTime( wxPGPropArg id ) const
 561     {
 562         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("datetime",
 563                                                    wxDateTime())
 564         return value.GetDateTime();
 565     }
 566 #endif
 567
 568     /** Returns a wxVariant list containing wxVariant versions of all
 569         property values. Order is not guaranteed.
 570         @param flags
 571         Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
 572         category will be its own wxVariantList of wxVariant.
 573         Use wxPG_INC_ATTRIBUTES to include property attributes as well.
 574         Each attribute will be stored as list variant named
 575         "@@<propname>@@attr."
 576         @remarks
 577     */
 578     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
 579         wxPGProperty* baseparent = NULL, long flags = 0 ) const
 580     {
 581         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
 582     }
 583
 584     /**
 585         Returns currently selected property. NULL if none.
 586
 587         @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this
 588                  member function returns the focused property, that is the
 589                  one which can have active editor.
 590     */
 591     wxPGProperty* GetSelection() const;
 592
 593     /**
 594         Returns list of currently selected properties.
 595
 596         @remarks wxArrayPGProperty should be compatible with std::vector API.
 597     */
 598     const wxArrayPGProperty& GetSelectedProperties() const
 599     {
 600         return m_pState->m_selection;
 601     }
 602
 603     wxPropertyGridPageState* GetState() const { return m_pState; }
 604
 605     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
 606         which can be useful for forward-iterating through arbitrary property
 607         containers.
 608
 609         @param flags
 610         See @ref propgrid_iterator_flags.
 611     */
 612     virtual wxPGVIterator GetVIterator( int flags ) const;
 613
 614     /** Hides or reveals a property.
 615         @param hide
 616             If true, hides property, otherwise reveals it.
 617         @param flags
 618             By default changes are applied recursively. Set this paramter
 619             wxPG_DONT_RECURSE to prevent this.
 620     */
 621     bool HideProperty( wxPGPropArg id,
 622                        bool hide = true,
 623                        int flags = wxPG_RECURSE );
 624
 625 #if wxPG_INCLUDE_ADVPROPS
 626     /** Initializes *all* property types. Causes references to most object
 627         files in the library, so calling this may cause significant increase
 628         in executable size when linking with static library.
 629     */
 630     static void InitAllTypeHandlers();
 631 #else
 632     static void InitAllTypeHandlers() { }
 633 #endif
 634
 635     //@{
 636     /** Inserts property to the property container.
 637
 638         @param priorThis
 639         New property is inserted just prior to this. Available only
 640         in the first variant. There are two versions of this function
 641         to allow this parameter to be either an id or name to
 642         a property.
 643
 644         @param newproperty
 645         Pointer to the inserted property. wxPropertyGrid will take
 646         ownership of this object.
 647
 648         @param parent
 649         New property is inserted under this category. Available only
 650         in the second variant. There are two versions of this function
 651         to allow this parameter to be either an id or name to
 652         a property.
 653
 654         @param index
 655         Index under category. Available only in the second variant.
 656         If index is < 0, property is appended in category.
 657
 658         @return
 659         Returns id for the property,
 660
 661         @remarks
 662
 663         - wxPropertyGrid takes the ownership of the property pointer.
 664
 665         - While Append may be faster way to add items, make note that when
 666           both types of data storage (categoric and
 667           non-categoric) are active, Insert becomes even more slow. This is
 668           especially true if current mode is non-categoric.
 669
 670         Example of use:
 671
 672         @code
 673
 674             // append category
 675             wxPGProperty* my_cat_id = propertygrid->Append(
 676                 new wxPropertyCategory("My Category") );
 677
 678             ...
 679
 680             // insert into category - using second variant
 681             wxPGProperty* my_item_id_1 = propertygrid->Insert(
 682                 my_cat_id, 0, new wxStringProperty("My String 1") );
 683
 684             // insert before to first item - using first variant
 685             wxPGProperty* my_item_id_2 = propertygrid->Insert(
 686                 my_item_id, new wxStringProperty("My String 2") );
 687
 688         @endcode
 689
 690     */
 691     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty );
 692     wxPGProperty* Insert( wxPGPropArg parent,
 693                           int index,
 694                           wxPGProperty* newproperty );
 695     //@}
 696
 697     /** Returns true if property is a category. */
 698     bool IsPropertyCategory( wxPGPropArg id ) const
 699     {
 700         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 701         return p->IsCategory();
 702     }
 703
 704     /** Returns true if property is enabled. */
 705     bool IsPropertyEnabled( wxPGPropArg id ) const
 706     {
 707         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 708         return (!(p->GetFlags() & wxPG_PROP_DISABLED))?true:false;
 709     }
 710
 711     /**
 712         Returns true if given property is expanded.
 713
 714         Naturally, always returns false for properties that cannot be expanded.
 715     */
 716     bool IsPropertyExpanded( wxPGPropArg id ) const;
 717
 718     /**
 719         Returns true if property has been modified after value set or modify
 720         flag clear by software.
 721     */
 722     bool IsPropertyModified( wxPGPropArg id ) const
 723     {
 724         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 725         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
 726     }
 727
 728     /**
 729         Returns true if property is selected.
 730     */
 731     bool IsPropertySelected( wxPGPropArg id ) const
 732     {
 733         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 734         return m_pState->DoIsPropertySelected(p);
 735     }
 736
 737     /**
 738         Returns true if property is shown (ie hideproperty with true not
 739         called for it).
 740     */
 741     bool IsPropertyShown( wxPGPropArg id ) const
 742     {
 743         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 744         return (!(p->GetFlags() & wxPG_PROP_HIDDEN))?true:false;
 745     }
 746
 747     /** Returns true if property value is set to unspecified.
 748     */
 749     bool IsPropertyValueUnspecified( wxPGPropArg id ) const
 750     {
 751         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 752         return p->IsValueUnspecified();
 753     }
 754
 755     /**
 756         Disables (limit = true) or enables (limit = false) wxTextCtrl editor of
 757         a property, if it is not the sole mean to edit the value.
 758     */
 759     void LimitPropertyEditing( wxPGPropArg id, bool limit = true );
 760
 761     /** If state is shown in it's grid, refresh it now.
 762     */
 763     virtual void RefreshGrid( wxPropertyGridPageState* state = NULL );
 764
 765 #if wxPG_INCLUDE_ADVPROPS
 766     /**
 767         Initializes additional property editors (SpinCtrl etc.). Causes
 768         references to most object files in the library, so calling this may
 769         cause significant increase in executable size when linking with static
 770         library.
 771     */
 772     static void RegisterAdditionalEditors();
 773 #else
 774     static void RegisterAdditionalEditors() { }
 775 #endif
 776
 777     /** Replaces property with id with newly created property. For example,
 778         this code replaces existing property named "Flags" with one that
 779         will have different set of items:
 780         @code
 781             pg->ReplaceProperty("Flags",
 782                 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
 783         @endcode
 784         For more info, see wxPropertyGrid::Insert.
 785     */
 786     wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property );
 787
 788     /** @anchor propgridinterface_editablestate_flags
 789
 790         Flags for wxPropertyGridInterface::SaveEditableState() and
 791         wxPropertyGridInterface::RestoreEditableState().
 792     */
 793     enum EditableStateFlags
 794     {
 795         /** Include selected property. */
 796         SelectionState   = 0x01,
 797         /** Include expanded/collapsed property information. */
 798         ExpandedState    = 0x02,
 799         /** Include scrolled position. */
 800         ScrollPosState   = 0x04,
 801         /** Include selected page information.
 802             Only applies to wxPropertyGridManager. */
 803         PageState        = 0x08,
 804         /** Include splitter position. Stored for each page. */
 805         SplitterPosState = 0x10,
 806         /** Include description box size.
 807             Only applies to wxPropertyGridManager. */
 808         DescBoxState     = 0x20,
 809
 810         /**
 811             Include all supported user editable state information.
 812             This is usually the default value. */
 813         AllStates        = SelectionState |
 814                            ExpandedState |
 815                            ScrollPosState |
 816                            PageState |
 817                            SplitterPosState |
 818                            DescBoxState
 819     };
 820
 821     /**
 822         Restores user-editable state.
 823
 824         See also wxPropertyGridInterface::SaveEditableState().
 825
 826         @param src
 827             String generated by SaveEditableState.
 828
 829         @param restoreStates
 830             Which parts to restore from source string. See @ref
 831             propgridinterface_editablestate_flags "list of editable state
 832             flags".
 833
 834         @return
 835             False if there was problem reading the string.
 836
 837         @remarks
 838         If some parts of state (such as scrolled or splitter position) fail to
 839         restore correctly, please make sure that you call this function after
 840         wxPropertyGrid size has been set (this may sometimes be tricky when
 841         sizers are used).
 842     */
 843     bool RestoreEditableState( const wxString& src,
 844                                int restoreStates = AllStates );
 845
 846     /**
 847         Used to acquire user-editable state (selected property, expanded
 848         properties, scrolled position, splitter positions).
 849
 850         @param includedStates
 851         Which parts of state to include. See @ref
 852         propgridinterface_editablestate_flags "list of editable state flags".
 853     */
 854     wxString SaveEditableState( int includedStates = AllStates ) const;
 855
 856     /**
 857         Lets user to set the strings listed in the choice dropdown of a
 858         wxBoolProperty. Defaults are "True" and "False", so changing them to,
 859         say, "Yes" and "No" may be useful in some less technical applications.
 860     */
 861     static void SetBoolChoices( const wxString& trueChoice,
 862                                 const wxString& falseChoice );
 863
 864     /**
 865         Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER
 866         window style needs to be used to indicate that columns are auto-
 867         resizeable.
 868
 869         @returns Returns @false on failure.
 870
 871         @remarks You should call this for individual pages of
 872                  wxPropertyGridManager (if used).
 873     */
 874     bool SetColumnProportion( unsigned int column, int proportion );
 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     /** Sets client data (void*) of a property.
 971         @remarks
 972         This untyped client data has to be deleted manually.
 973     */
 974     void SetPropertyClientData( wxPGPropArg id, void* clientData )
 975     {
 976         wxPG_PROP_ARG_CALL_PROLOG()
 977         p->SetClientData(clientData);
 978     }
 979
 980     /** Sets editor for a property.
 981
 982         @param editor
 983         For builtin editors, use wxPGEditor_X, where X is builtin editor's
 984         name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
 985         list).
 986
 987         For custom editors, use pointer you received from
 988         wxPropertyGrid::RegisterEditorClass().
 989     */
 990     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
 991     {
 992         wxPG_PROP_ARG_CALL_PROLOG()
 993         wxCHECK_RET( editor, wxT("unknown/NULL editor") );
 994         p->SetEditor(editor);
 995         RefreshProperty(p);
 996     }
 997
 998     /** Sets editor control of a property. As editor argument, use
 999         editor name string, such as "TextCtrl" or "Choice".
1000     */
1001     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
1002     {
1003         SetPropertyEditor(id,GetEditorByName(editorName));
1004     }
1005
1006     /** Sets label of a property.
1007     */
1008     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
1009
1010     /**
1011         Sets name of a property.
1012
1013         @param id
1014             Name or pointer of property which name to change.
1015
1016         @param newName
1017             New name for property.
1018     */
1019     void SetPropertyName( wxPGPropArg id, const wxString& newName )
1020     {
1021         wxPG_PROP_ARG_CALL_PROLOG()
1022         m_pState->DoSetPropertyName( p, newName );
1023     }
1024
1025     /**
1026         Sets property (and, recursively, its children) to have read-only value.
1027         In other words, user cannot change the value in the editor, but they
1028         can still copy it.
1029         @remarks
1030         This is mainly for use with textctrl editor. Not all other editors fully
1031         support it.
1032         @param flags
1033         By default changes are applied recursively. Set this paramter
1034         wxPG_DONT_RECURSE to prevent this.
1035     */
1036     void SetPropertyReadOnly( wxPGPropArg id,
1037                               bool set = true,
1038                               int flags = wxPG_RECURSE )
1039     {
1040         wxPG_PROP_ARG_CALL_PROLOG()
1041         if ( flags & wxPG_RECURSE )
1042             p->SetFlagRecursively(wxPG_PROP_READONLY, set);
1043         else
1044             p->ChangeFlag(wxPG_PROP_READONLY, set);
1045     }
1046
1047     /** Sets property's value to unspecified.
1048         If it has children (it may be category), then the same thing is done to
1049         them.
1050     */
1051     void SetPropertyValueUnspecified( wxPGPropArg id )
1052     {
1053         wxPG_PROP_ARG_CALL_PROLOG()
1054         p->SetValueToUnspecified();
1055     }
1056
1057     /**
1058         Sets property values from a list of wxVariants.
1059     */
1060     void SetPropertyValues( const wxVariantList& list,
1061                             wxPGPropArg defaultCategory = wxNullProperty )
1062     {
1063         wxPGProperty *p;
1064         if ( defaultCategory.HasName() ) p = defaultCategory.GetPtr(this);
1065         else p = defaultCategory.GetPtr0();
1066         m_pState->DoSetPropertyValues(list, p);
1067     }
1068
1069     /**
1070         Sets property values from a list of wxVariants.
1071     */
1072     void SetPropertyValues( const wxVariant& list,
1073                             wxPGPropArg defaultCategory = wxNullProperty )
1074     {
1075         SetPropertyValues(list.GetList(),defaultCategory);
1076     }
1077
1078     /** Associates the help string with property.
1079         @remarks
1080         By default, text is shown either in the manager's "description"
1081         text box or in the status bar. If extra window style
1082         wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a
1083         tooltip.
1084     */
1085     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
1086     {
1087         wxPG_PROP_ARG_CALL_PROLOG()
1088         p->SetHelpString(helpString);
1089     }
1090
1091     /** Set wxBitmap in front of the value.
1092         @remarks
1093         - Bitmap will be scaled to a size returned by
1094         wxPropertyGrid::GetImageSize();
1095     */
1096     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp )
1097     {
1098         wxPG_PROP_ARG_CALL_PROLOG()
1099         p->SetValueImage(bmp);
1100         RefreshProperty(p);
1101     }
1102
1103     /** Sets max length of property's text.
1104     */
1105     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
1106
1107 #if wxUSE_VALIDATORS
1108     /** Sets validator of a property.
1109     */
1110     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
1111     {
1112         wxPG_PROP_ARG_CALL_PROLOG()
1113         p->SetValidator(validator);
1114     }
1115 #endif
1116
1117     /** Sets value (long integer) of a property.
1118     */
1119     void SetPropertyValue( wxPGPropArg id, long value )
1120     {
1121         wxVariant v(value);
1122         SetPropVal( id, v );
1123     }
1124
1125     /** Sets value (integer) of a property.
1126     */
1127     void SetPropertyValue( wxPGPropArg id, int value )
1128     {
1129         wxVariant v((long)value);
1130         SetPropVal( id, v );
1131     }
1132     /** Sets value (floating point) of a property.
1133     */
1134     void SetPropertyValue( wxPGPropArg id, double value )
1135     {
1136         wxVariant v(value);
1137         SetPropVal( id, v );
1138     }
1139     /** Sets value (bool) of a property.
1140     */
1141     void SetPropertyValue( wxPGPropArg id, bool value )
1142     {
1143         wxVariant v(value);
1144         SetPropVal( id, v );
1145     }
1146 #if wxUSE_WCHAR_T
1147     void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
1148     {
1149         SetPropertyValueString( id, wxString(value) );
1150     }
1151 #endif
1152     void SetPropertyValue( wxPGPropArg id, const char* value )
1153     {
1154         SetPropertyValueString( id, wxString(value) );
1155     }
1156     void SetPropertyValue( wxPGPropArg id, const wxString& value )
1157     {
1158         SetPropertyValueString( id, value );
1159     }
1160
1161     /** Sets value (wxArrayString) of a property.
1162     */
1163     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
1164     {
1165         wxVariant v(value);
1166         SetPropVal( id, v );
1167     }
1168
1169 #if wxUSE_DATETIME
1170     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
1171     {
1172         wxVariant v(value);
1173         SetPropVal( id, v );
1174     }
1175 #endif
1176
1177     /** Sets value (wxObject*) of a property.
1178     */
1179     void SetPropertyValue( wxPGPropArg id, wxObject* value )
1180     {
1181         wxVariant v(value);
1182         SetPropVal( id, v );
1183     }
1184
1185     void SetPropertyValue( wxPGPropArg id, wxObject& value )
1186     {
1187         wxVariant v(&value);
1188         SetPropVal( id, v );
1189     }
1190
1191 #ifdef wxLongLong_t
1192     /** Sets value (wxLongLong&) of a property.
1193     */
1194     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value )
1195     {
1196         wxVariant v = WXVARIANT(wxLongLong(value));
1197         SetPropVal( id, v );
1198     }
1199     /** Sets value (wxULongLong&) of a property.
1200     */
1201     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value )
1202     {
1203         wxVariant v = WXVARIANT(wxULongLong(value));
1204         SetPropVal( id, v );
1205     }
1206 #endif
1207
1208     /** Sets value (wxArrayInt&) of a property.
1209     */
1210     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
1211     {
1212         wxVariant v = WXVARIANT(value);
1213         SetPropVal( id, v );
1214     }
1215
1216     /** Sets value (wxString) of a property.
1217
1218         @remarks
1219         This method uses wxPGProperty::SetValueFromString, which all properties
1220         should implement. This means that there should not be a type error,
1221         and instead the string is converted to property's actual value type.
1222     */
1223     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
1224
1225     /** Sets value (wxVariant&) of a property.
1226
1227         @remarks
1228         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1229         through validation process and send property change event.
1230     */
1231     void SetPropertyValue( wxPGPropArg id, wxVariant value )
1232     {
1233         SetPropVal( id, value );
1234     }
1235
1236     /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
1237         accepts reference. */
1238     void SetPropVal( wxPGPropArg id, wxVariant& value );
1239
1240     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
1241         in a property.
1242         @param vfbFlags
1243         See @link vfbflags list of valid flags values@endlink
1244     */
1245     void SetValidationFailureBehavior( int vfbFlags );
1246
1247     /**
1248         Sorts all properties recursively.
1249
1250         @param flags
1251             This can contain any of the following options:
1252               wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their
1253                 immediate children. Sorting done by wxPG_AUTO_SORT option
1254                 uses this.
1255
1256         @see SortChildren, wxPropertyGrid::SetSortFunction
1257     */
1258     void Sort( int flags = 0 );
1259
1260     /**
1261         Sorts children of a property.
1262
1263         @param id
1264             Name or pointer to a property.
1265
1266         @param flags
1267             This can contain any of the following options:
1268               wxPG_RECURSE: Sorts recursively.
1269
1270         @see Sort, wxPropertyGrid::SetSortFunction
1271     */
1272     void SortChildren( wxPGPropArg id, int flags = 0 )
1273     {
1274         wxPG_PROP_ARG_CALL_PROLOG()
1275         m_pState->DoSortChildren(p, flags);
1276     }
1277
1278     // GetPropertyByName With nice assertion error message.
1279     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
1280
1281     static wxPGEditor* GetEditorByName( const wxString& editorName );
1282
1283     // NOTE: This function reselects the property and may cause
1284     //       excess flicker, so to just call Refresh() on a rect
1285     //       of single property, call DrawItem() instead.
1286     virtual void RefreshProperty( wxPGProperty* p ) = 0;
1287
1288 protected:
1289
1290     bool DoClearSelection( bool validation = false,
1291                            int selFlags = 0 );
1292
1293     /**
1294         In derived class, implement to set editable state component with
1295         given name to given value.
1296     */
1297     virtual bool SetEditableStateItem( const wxString& name, wxVariant value )
1298     {
1299         wxUnusedVar(name);
1300         wxUnusedVar(value);
1301         return false;
1302     }
1303
1304     /**
1305         In derived class, implement to return editable state component with
1306         given name.
1307     */
1308     virtual wxVariant GetEditableStateItem( const wxString& name ) const
1309     {
1310         wxUnusedVar(name);
1311         return wxNullVariant;
1312     }
1313
1314     // Returns page state data for given (sub) page (-1 means current page).
1315     virtual wxPropertyGridPageState* GetPageState( int pageIndex ) const
1316     {
1317         if ( pageIndex <= 0 )
1318             return m_pState;
1319         return NULL;
1320     }
1321
1322     virtual bool DoSelectPage( int WXUNUSED(index) ) { return true; }
1323
1324     // Default call's m_pState's BaseGetPropertyByName
1325     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
1326
1327     // Deriving classes must set this (it must be only or current page).
1328     wxPropertyGridPageState*         m_pState;
1329
1330     // Intermediate version needed due to wxVariant copying inefficiency
1331     void DoSetPropertyAttribute( wxPGPropArg id,
1332                                  const wxString& name,
1333                                  wxVariant& value, long argFlags );
1334
1335     // Empty string object to return from member functions returning const
1336     // wxString&.
1337     wxString                    m_emptyString;
1338
1339 private:
1340     // Cannot be GetGrid() due to ambiguity issues.
1341     wxPropertyGrid* GetPropertyGrid()
1342     {
1343         if ( !m_pState )
1344             return NULL;
1345         return m_pState->GetGrid();
1346     }
1347
1348     // Cannot be GetGrid() due to ambiguity issues.
1349     const wxPropertyGrid* GetPropertyGrid() const
1350     {
1351         if ( !m_pState )
1352             return NULL;
1353         return static_cast<const wxPropertyGrid*>(m_pState->GetGrid());
1354     }
1355
1356     friend class wxPropertyGrid;
1357     friend class wxPropertyGridManager;
1358 };
1359
1360 #endif // wxUSE_PROPGRID
1361
1362 #endif // __WX_PROPGRID_PROPGRIDIFACE_H__