interface/wx/propgrid/propgridiface.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        property.h
   3 // Purpose:     interface of wxPGProperty
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id:
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // -----------------------------------------------------------------------
  10
  11 /** @class wxPropertyGridInterface
  12
  13     Most of the shared property manipulation interface shared by wxPropertyGrid,
  14     wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
  15
  16     @remarks
  17     - In separate wxPropertyGrid component this class was known as wxPropertyContainerMethods.
  18
  19     @library{wxpropgrid}
  20     @category{propgrid}
  21 */
  22 class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
  23 {
  24 public:
  25
  26     /** Destructor */
  27     virtual ~wxPropertyGridInterface() { }
  28
  29     /** Appends property to the list. wxPropertyGrid assumes ownership of the object.
  30         Becomes child of most recently added category.
  31         @remarks
  32         - wxPropertyGrid takes the ownership of the property pointer.
  33         - If appending a category with name identical to a category already in the
  34           wxPropertyGrid, then newly created category is deleted, and most recently
  35           added category (under which properties are appended) is set to the one with
  36           same name. This allows easier adding of items to same categories in multiple
  37           passes.
  38         - Does not automatically redraw the control, so you may need to call Refresh
  39           when calling this function after control has been shown for the first time.
  40     */
  41     wxPGProperty* Append( wxPGProperty* property );
  42
  43     wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newproperty );
  44
  45     /** Inorder to add new items into a property with fixed children (for instance, wxFlagsProperty),
  46         you need to call this method. After populating has been finished, you need to call EndAddChildren.
  47     */
  48     void BeginAddChildren( wxPGPropArg id );
  49
  50     /** Deletes all properties.
  51     */
  52     virtual void Clear() = 0;
  53
  54     /** Deselect current selection, if any. Returns true if success
  55         (ie. validator did not intercept). */
  56     bool ClearSelection();
  57
  58     /** Resets modified status of all properties.
  59     */
  60     void ClearModifiedStatus()
  61     {
  62         SetPropertyModifiedStatus(m_pState->m_properties, false);
  63         m_pState->m_anyModified = false;
  64     }
  65
  66     /** Collapses given category or property with children.
  67         Returns true if actually collapses.
  68     */
  69     bool Collapse( wxPGPropArg id );
  70
  71     /** Collapses all items that can be collapsed.
  72
  73         @retval
  74         Return false if failed (may fail if editor value cannot be validated).
  75     */
  76     bool CollapseAll() { return ExpandAll(false); }
  77
  78     /** Changes value of a property, as if from an editor. Use this instead of SetPropertyValue()
  79         if you need the value to run through validation process, and also send the property
  80         change event.
  81
  82         @retval
  83         Returns true if value was successfully changed.
  84     */
  85     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
  86
  87     /** Resets value of a property to its default. */
  88     bool ClearPropertyValue( wxPGPropArg id )
  89     {
  90         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
  91         p->SetValue(p->GetDefaultValue());
  92         RefreshProperty(p);
  93         return true;
  94     }
  95
  96     /** Deletes a property by id. If category is deleted, all children are automatically deleted as well. */
  97     void DeleteProperty( wxPGPropArg id );
  98
  99     /** Disables property. */
 100     bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); }
 101
 102     /** Returns true if all property grid data changes have been committed. Usually
 103         only returns false if value in active editor has been invalidated by a
 104         wxValidator.
 105     */
 106     bool EditorValidate();
 107
 108     /** Enables or disables property, depending on whether enable is true or false. */
 109     bool EnableProperty( wxPGPropArg id, bool enable = true );
 110
 111     /** Called after population of property with fixed children has finished.
 112     */
 113     void EndAddChildren( wxPGPropArg id );
 114
 115     /** Expands given category or property with children.
 116         Returns true if actually expands.
 117     */
 118     bool Expand( wxPGPropArg id );
 119
 120     /** Expands all items that can be expanded.
 121     */
 122     bool ExpandAll( bool expand = true );
 123
 124     /** Returns list of expanded properties.
 125     */
 126     wxArrayPGProperty GetExpandedProperties() const
 127     {
 128         wxArrayPGProperty array;
 129         GetPropertiesWithFlag(&array, wxPG_PROP_COLLAPSED, true,
 130             wxPG_ITERATE_ALL_PARENTS_RECURSIVELY|wxPG_ITERATE_HIDDEN);
 131         return array;
 132     }
 133
 134     /** Returns id of first child of given property.
 135         @remarks
 136         Does not return sub-properties!
 137     */
 138     wxPGProperty* GetFirstChild( wxPGPropArg id )
 139     {
 140         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
 141
 142         if ( !p->GetChildCount() || p->HasFlag(wxPG_PROP_AGGREGATE) )
 143             return wxNullProperty;
 144
 145         return p->Item(0);
 146     }
 147
 148     //@{
 149     /** Returns iterator class instance.
 150         @param flags
 151         See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
 152         iteration over everything except private child properties.
 153         @param firstProp
 154         Property to start iteration from. If NULL, then first child of root is used.
 155         @param startPos
 156         Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start from
 157         the first property from the top, and wxBOTTOM means that the iteration will
 158         instead begin from bottommost valid item.
 159     */
 160     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL )
 161     {
 162         return wxPropertyGridIterator( m_pState, flags, firstProp );
 163     }
 164
 165     wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL ) const
 166     {
 167         return wxPropertyGridConstIterator( m_pState, flags, firstProp );
 168     }
 169
 170     wxPropertyGridIterator GetIterator( int flags, int startPos )
 171     {
 172         return wxPropertyGridIterator( m_pState, flags, startPos );
 173     }
 174
 175     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
 176     {
 177         return wxPropertyGridConstIterator( m_pState, flags, startPos );
 178     }
 179     //@}
 180
 181     /** Returns id of first item, whether it is a category or property.
 182         @param flags
 183         @link iteratorflags List of iterator flags@endlink
 184     */
 185     wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL )
 186     {
 187         wxPropertyGridIterator it( m_pState, flags, wxNullProperty, 1 );
 188         return *it;
 189     }
 190
 191     const wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ) const
 192     {
 193         return ((wxPropertyGridInterface*)this)->GetFirst(flags);
 194     }
 195
 196     /** Returns id of property with given name (case-sensitive). If there is no
 197         property with such name, returned property id is invalid ( i.e. it will return
 198         false with IsOk method).
 199         @remarks
 200         - Sub-properties (i.e. properties which have parent that is not category or
 201           root) can not be accessed globally by their name. Instead, use
 202           "<property>.<subproperty>" in place of "<subproperty>".
 203     */
 204     wxPGProperty* GetProperty( const wxString& name ) const
 205     {
 206         return GetPropertyByName(name);
 207     }
 208
 209     /** Returns map-like storage of property's attributes.
 210         @remarks
 211         Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set,
 212         then builtin-attributes are not included in the storage.
 213     */
 214     const wxPGAttributeStorage& GetPropertyAttributes( wxPGPropArg id ) const
 215     {
 216         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(*((const wxPGAttributeStorage*)NULL));
 217         return p->GetAttributes();
 218     }
 219
 220     /** Adds to 'targetArr' pointers to properties that have given
 221         flags 'flags' set. However, if 'inverse' is set to true, then
 222         only properties without given flags are stored.
 223         @param flags
 224         Property flags to use.
 225         @param iterFlags
 226         Iterator flags to use. Default is everything expect private children.
 227     */
 228     void GetPropertiesWithFlag( wxArrayPGProperty* targetArr,
 229                                 wxPGProperty::FlagType flags,
 230                                 bool inverse = false,
 231                                 int iterFlags = (wxPG_ITERATE_PROPERTIES|wxPG_ITERATE_HIDDEN|wxPG_ITERATE_CATEGORIES) ) const;
 232
 233     /** Returns value of given attribute. If none found, returns NULL-variant.
 234     */
 235     wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const
 236     {
 237         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullVariant)
 238         return p->GetAttribute(attrName);
 239     }
 240
 241     /** Returns pointer of property's nearest parent category. If no category
 242         found, returns NULL.
 243     */
 244     wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const
 245     {
 246         wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(NULL)
 247         return m_pState->GetPropertyCategory(p);
 248     }
 249
 250     /** Returns client data (void*) of a property. */
 251     void* GetPropertyClientData( wxPGPropArg id ) const
 252     {
 253         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 254         return p->GetClientData();
 255     }
 256
 257     /** Returns first property which label matches given string. NULL if none found.
 258         Note that this operation is extremely slow when compared to GetPropertyByName().
 259     */
 260     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 261
 262     /** Returns property with given name. NULL if none found.
 263     */
 264     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 265
 266     /** Returns child property 'subname' of property 'name'. Same as
 267         calling GetPropertyByName("name.subname"), albeit slightly faster.
 268     */
 269     wxPGProperty* GetPropertyByName( const wxString& name, const wxString& subname ) const;
 270
 271     /** Returns property's editor. */
 272     const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const
 273     {
 274         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 275         return p->GetEditorClass();
 276     }
 277
 278     /** Returns help string associated with a property. */
 279     wxString GetPropertyHelpString( wxPGPropArg id ) const
 280     {
 281         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 282         return p->GetHelpString();
 283     }
 284
 285     /** Returns property's custom value image (NULL of none). */
 286     wxBitmap* GetPropertyImage( wxPGPropArg id ) const
 287     {
 288         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 289         return p->GetValueImage();
 290     }
 291
 292     /** Returns property's position under its parent. */
 293     unsigned int GetPropertyIndex( wxPGPropArg id )
 294     {
 295         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(INT_MAX)
 296         return p->GetIndexInParent();
 297     }
 298
 299     /** Returns label of a property. */
 300     const wxString& GetPropertyLabel( wxPGPropArg id )
 301     {
 302         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 303         return p->GetLabel();
 304     }
 305
 306     /** Returns name of a property, by which it is globally accessible. */
 307     wxString GetPropertyName( wxPGPropArg id )
 308     {
 309         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 310         return p->GetName();
 311     }
 312
 313     /** Returns parent item of a property. */
 314     wxPGProperty* GetPropertyParent( wxPGPropArg id )
 315     {
 316         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
 317         return p->GetParent();
 318     }
 319
 320     /** Returns validator of a property as a reference, which you
 321         can pass to any number of SetPropertyValidator.
 322     */
 323     wxValidator* GetPropertyValidator( wxPGPropArg id )
 324     {
 325         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
 326         return p->GetValidator();
 327     }
 328
 329     /** Returns value as wxVariant.
 330
 331         If property value is unspecified, Null variant is returned.
 332     */
 333     wxVariant GetPropertyValue( wxPGPropArg id )
 334     {
 335         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant())
 336         return p->GetValue();
 337     }
 338
 339     wxString GetPropertyValueAsString( wxPGPropArg id ) const;
 340     long GetPropertyValueAsLong( wxPGPropArg id ) const;
 341     unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const
 342     {
 343         return (unsigned long) GetPropertyValueAsLong(id);
 344     }
 345     int GetPropertyValueAsInt( wxPGPropArg id ) const { return (int)GetPropertyValueAsLong(id); }
 346     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
 347     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 348     void* GetPropertyValueAsVoidPtr( wxPGPropArg id ) const;
 349
 350     wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const
 351     {
 352         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("arrstring"), wxArrayString())
 353         return p->m_value.GetArrayString();
 354     }
 355
 356     wxPoint GetPropertyValueAsPoint( wxPGPropArg id ) const
 357     {
 358         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxPoint"), wxPoint())
 359         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxPoint);
 360     }
 361
 362     wxSize GetPropertyValueAsSize( wxPGPropArg id ) const
 363     {
 364         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxSize"), wxSize())
 365         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxSize);
 366     }
 367
 368     wxLongLong_t GetPropertyValueAsLongLong( wxPGPropArg id ) const
 369     {
 370         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(wxT("wxLongLong"), (long) GetPropertyValueAsLong(id))
 371         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxLongLong).GetValue();
 372     }
 373
 374     wxULongLong_t GetPropertyValueAsULongLong( wxPGPropArg id ) const
 375     {
 376         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(wxT("wxULongLong"), (unsigned long) GetPropertyValueAsULong(id))
 377         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxULongLong).GetValue();
 378     }
 379
 380     wxArrayInt GetPropertyValueAsArrayInt( wxPGPropArg id ) const
 381     {
 382         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxArrayInt"), wxArrayInt())
 383         wxArrayInt arr = WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxArrayInt);
 384         return arr;
 385     }
 386
 387     wxDateTime GetPropertyValueAsDateTime( wxPGPropArg id ) const
 388     {
 389         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxDateTime())
 390
 391         if ( wxStrcmp(p->m_value.GetType(), wxT("datetime")) != 0 )
 392         {
 393             wxPGGetFailed(p, wxT("datetime"));
 394             return wxDateTime();
 395         }
 396         return p->m_value.GetDateTime();
 397     }
 398
 399     /** Returns a wxVariant list containing wxVariant versions of all
 400         property values. Order is not guaranteed.
 401         @param flags
 402         Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
 403         category will be its own wxVariantList of wxVariant.
 404         Use wxPG_INC_ATTRIBUTES to include property attributes as well.
 405         Each attribute will be stored as list variant named "@@<propname>@@attr."
 406         @remarks
 407     */
 408     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
 409         wxPGProperty* baseparent = NULL, long flags = 0 ) const
 410     {
 411         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
 412     }
 413
 414     wxString GetPropertyValueType( wxPGPropArg id )
 415     {
 416         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 417         return p->GetValueType();
 418     }
 419
 420     /** Returns currently selected property. */
 421     wxPGProperty* GetSelection() const
 422     {
 423         return m_pState->GetSelection();
 424     }
 425
 426     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
 427         which can be useful for forward-iterating through arbitrary property
 428         containers.
 429
 430         @param flags
 431         See @ref propgrid_iterator_flags.
 432     */
 433     virtual wxPGVIterator GetVIterator( int flags ) const;
 434
 435     /** Hides or reveals a property.
 436         @param hide
 437         If true, hides property, otherwise reveals it.
 438         @param flags
 439         By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
 440     */
 441     bool HideProperty( wxPGPropArg id, bool hide = true, int flags = wxPG_RECURSE );
 442
 443     /** Initializes *all* property types. Causes references to most object
 444         files in the library, so calling this may cause significant increase
 445         in executable size when linking with static library.
 446     */
 447     static void InitAllTypeHandlers();
 448
 449     //@{
 450     /** Inserts property to the property container.
 451
 452         @param priorThis
 453         New property is inserted just prior to this. Available only
 454         in the first variant. There are two versions of this function
 455         to allow this parameter to be either an id or name to
 456         a property.
 457
 458         @param newproperty
 459         Pointer to the inserted property. wxPropertyGrid will take
 460         ownership of this object.
 461
 462         @param parent
 463         New property is inserted under this category. Available only
 464         in the second variant. There are two versions of this function
 465         to allow this parameter to be either an id or name to
 466         a property.
 467
 468         @param index
 469         Index under category. Available only in the second variant.
 470         If index is < 0, property is appended in category.
 471
 472         @return
 473         Returns id for the property,
 474
 475         @remarks
 476
 477         - wxPropertyGrid takes the ownership of the property pointer.
 478
 479         - While Append may be faster way to add items, make note that when
 480           both types of data storage (categoric and
 481           non-categoric) are active, Insert becomes even more slow. This is
 482           especially true if current mode is non-categoric.
 483
 484         Example of use:
 485
 486         @code
 487
 488             // append category
 489             wxPGProperty* my_cat_id = propertygrid->Append( new wxPropertyCategory("My Category") );
 490
 491             ...
 492
 493             // insert into category - using second variant
 494             wxPGProperty* my_item_id_1 = propertygrid->Insert( my_cat_id, 0, new wxStringProperty("My String 1") );
 495
 496             // insert before to first item - using first variant
 497             wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") );
 498
 499         @endcode
 500
 501     */
 502     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty );
 503     wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newproperty );
 504     //@}
 505
 506     /** Returns true if property is a category. */
 507     bool IsPropertyCategory( wxPGPropArg id ) const
 508     {
 509         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 510         return p->IsCategory();
 511     }
 512
 513     /** Returns true if property is enabled. */
 514     bool IsPropertyEnabled( wxPGPropArg id ) const
 515     {
 516         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 517         return (!(p->GetFlags() & wxPG_PROP_DISABLED))?true:false;
 518     }
 519
 520     /** Returns true if given property is expanded. Naturally, always returns false
 521         for properties that cannot be expanded.
 522     */
 523     bool IsPropertyExpanded( wxPGPropArg id ) const;
 524
 525     /** Returns true if property has been modified after value set or modify flag
 526         clear by software.
 527     */
 528     bool IsPropertyModified( wxPGPropArg id ) const
 529     {
 530         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 531         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
 532     }
 533
 534     /** Returns true if property is shown (ie. hideproperty with true not called for it). */
 535     bool IsPropertyShown( wxPGPropArg id ) const
 536     {
 537         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 538         return (!(p->GetFlags() & wxPG_PROP_HIDDEN))?true:false;
 539     }
 540
 541     /** Returns true if property value is set to unspecified.
 542     */
 543     bool IsPropertyValueUnspecified( wxPGPropArg id ) const
 544     {
 545         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 546         return p->IsValueUnspecified();
 547     }
 548
 549     /** Disables (limit = true) or enables (limit = false) wxTextCtrl editor of a property,
 550         if it is not the sole mean to edit the value.
 551     */
 552     void LimitPropertyEditing( wxPGPropArg id, bool limit = true );
 553
 554     /** If state is shown in it's grid, refresh it now.
 555     */
 556     virtual void RefreshGrid();
 557
 558     /** Initializes additional property editors (SpinCtrl etc.). Causes references
 559         to most object files in the library, so calling this may cause significant increase
 560         in executable size when linking with static library.
 561     */
 562     static void RegisterAdditionalEditors();
 563
 564     /** Replaces property with id with newly created property. For example,
 565         this code replaces existing property named "Flags" with one that
 566         will have different set of items:
 567         @code
 568             pg->ReplaceProperty("Flags",
 569                 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
 570         @endcode
 571         For more info, see wxPropertyGrid::Insert.
 572     */
 573     wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property );
 574
 575
 576     /** @anchor propgridinterface_editablestate_flags
 577
 578         Flags for wxPropertyGridInterface::SaveEditableState() and
 579         wxPropertyGridInterface::RestoreEditableState().
 580     */
 581     enum EditableStateFlags
 582     {
 583         /** Include selected property. */
 584         SelectionState   = 0x01,
 585         /** Include expanded/collapsed property information. */
 586         ExpandedState    = 0x02,
 587         /** Include scrolled position. */
 588         ScrollPosState   = 0x04,
 589         /** Include selected page information. Only applies to wxPropertyGridManager. */
 590         PageState        = 0x08,
 591         /** Include splitter position. Stored for each page. */
 592         SplitterPosState = 0x10,
 593
 594         /** Include all supported user editable state information. This is usually the default value. */
 595         AllStates        = SelectionState | ExpandedState | ScrollPosState | PageState | SplitterPosState
 596     };
 597
 598     /** Restores user-editable state. See also wxPropertyGridInterface::SaveEditableState().
 599
 600         @param src
 601         String generated by SaveEditableState.
 602
 603         @param restoreStates
 604         Which parts to restore from source string. See @ref propgridinterface_editablestate_flags
 605         "list of editable state flags".
 606
 607         @return
 608         False if there was problem reading the string.
 609
 610         @remarks
 611         If some parts of state (such as scrolled or splitter position) fail to restore correctly,
 612         please make sure that you call this function after wxPropertyGrid size has been set
 613         (this may sometimes be tricky when sizers are used).
 614     */
 615     bool RestoreEditableState( const wxString& src,
 616                                int restoreStates = AllStates );
 617
 618     /** Used to acquire user-editable state (selected property, expanded properties, scrolled position,
 619         splitter positions).
 620
 621         @param includedStates
 622         Which parts of state to include. See @ref propgridinterface_editablestate_flags
 623         "list of editable state flags".
 624     */
 625     wxString SaveEditableState( int includedStates = AllStates ) const;
 626
 627     /** Lets user to set the strings listed in the choice dropdown of a wxBoolProperty.
 628         Defaults are "True" and "False", so changing them to, say, "Yes" and "No" may
 629         be useful in some less technical applications.
 630     */
 631     static void SetBoolChoices( const wxString& trueChoice, const wxString& falseChoice );
 632
 633     /** Sets or clears flag(s) of all properties in given array.
 634         @param flags
 635         Property flags to set or clear.
 636         @param inverse
 637         Set to true if you want to clear flag instead of setting them.
 638     */
 639     void SetPropertiesFlag( const wxArrayPGProperty& srcArr, wxPGProperty::FlagType flags,
 640                             bool inverse = false );
 641
 642     /** Sets an attribute for this property.
 643         @param name
 644         Text identifier of attribute. See @ref propgrid_property_attributes.
 645         @param value
 646         Value of attribute.
 647         @param argFlags
 648         Optional. Use wxPG_RECURSE to set the attribute to child properties recursively.
 649     */
 650     void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName, wxVariant value, long argFlags = 0 )
 651     {
 652         DoSetPropertyAttribute(id,attrName,value,argFlags);
 653     }
 654
 655     /** Sets attributes from a wxPGAttributeStorage.
 656     */
 657     void SetPropertyAttributes( wxPGPropArg id, const wxPGAttributeStorage& attributes )
 658     {
 659         wxPG_PROP_ARG_CALL_PROLOG()
 660         p->SetAttributes(attributes);
 661     }
 662
 663     /** Sets text, bitmap, and colours for given column's cell.
 664
 665         @remarks
 666         - You can set label cell by setting column to 0.
 667         - You can use wxPG_LABEL as text to use default text for column.
 668     */
 669     void SetPropertyCell( wxPGPropArg id,
 670                           int column,
 671                           const wxString& text = wxEmptyString,
 672                           const wxBitmap& bitmap = wxNullBitmap,
 673                           const wxColour& fgCol = wxNullColour,
 674                           const wxColour& bgCol = wxNullColour )
 675     {
 676         wxPG_PROP_ARG_CALL_PROLOG()
 677         p->SetCell( column, new wxPGCell(text, bitmap, fgCol, bgCol) );
 678     }
 679
 680     /** Sets client data (void*) of a property.
 681         @remarks
 682         This untyped client data has to be deleted manually.
 683     */
 684     void SetPropertyClientData( wxPGPropArg id, void* clientData )
 685     {
 686         wxPG_PROP_ARG_CALL_PROLOG()
 687         p->SetClientData(clientData);
 688     }
 689
 690     /** Sets editor for a property.
 691
 692         @param editor
 693         For builtin editors, use wxPGEditor_X, where X is builtin editor's
 694         name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
 695
 696         For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
 697     */
 698     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
 699     {
 700         wxPG_PROP_ARG_CALL_PROLOG()
 701         wxCHECK_RET( editor, wxT("unknown/NULL editor") );
 702         p->SetEditor(editor);
 703         RefreshProperty(p);
 704     }
 705
 706     /** Sets editor control of a property. As editor argument, use
 707         editor name string, such as "TextCtrl" or "Choice".
 708     */
 709     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
 710     {
 711         SetPropertyEditor(id,GetEditorByName(editorName));
 712     }
 713
 714     /** Sets label of a property.
 715
 716         @remarks
 717         - Properties under same parent may have same labels. However,
 718         property names must still remain unique.
 719     */
 720     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
 721
 722     /** Set modified status of a property and all its children.
 723     */
 724     void SetPropertyModifiedStatus( wxPGPropArg id, bool modified )
 725     {
 726         wxPG_PROP_ARG_CALL_PROLOG()
 727         p->SetModifiedStatus(modified);
 728     }
 729
 730     /** Sets property (and, recursively, its children) to have read-only value. In other words,
 731         user cannot change the value in the editor, but they can still copy it.
 732         @remarks
 733         This is mainly for use with textctrl editor. Not all other editors fully
 734         support it.
 735         @param flags
 736         By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
 737     */
 738     void SetPropertyReadOnly( wxPGPropArg id, bool set = true, int flags = wxPG_RECURSE )
 739     {
 740         wxPG_PROP_ARG_CALL_PROLOG()
 741         if ( flags & wxPG_RECURSE )
 742             p->SetFlagRecursively(wxPG_PROP_READONLY, set);
 743         else
 744             p->SetFlag(wxPG_PROP_READONLY);
 745     }
 746
 747     /** Sets property's value to unspecified. If it has children (it may be category),
 748         then the same thing is done to them.
 749     */
 750     void SetPropertyValueUnspecified( wxPGPropArg id );
 751
 752     /** Sets various property values from a list of wxVariants. If property with
 753         name is missing from the grid, new property is created under given default
 754         category (or root if omitted).
 755     */
 756     void SetPropertyValues( const wxVariantList& list, wxPGPropArg defaultCategory = wxNullProperty )
 757     {
 758         wxPGProperty *p;
 759         if ( defaultCategory.HasName() ) p = defaultCategory.GetPtr(this);
 760         else p = defaultCategory.GetPtr0();
 761         m_pState->DoSetPropertyValues(list, p);
 762     }
 763
 764     void SetPropertyValues( const wxVariant& list, wxPGPropArg defaultCategory = wxNullProperty )
 765     {
 766         SetPropertyValues(list.GetList(),defaultCategory);
 767     }
 768
 769     /** Associates the help string with property.
 770         @remarks
 771         By default, text is shown either in the manager's "description"
 772         text box or in the status bar. If extra window style wxPG_EX_HELP_AS_TOOLTIPS
 773         is used, then the text will appear as a tooltip.
 774     */
 775     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
 776     {
 777         wxPG_PROP_ARG_CALL_PROLOG()
 778         p->SetHelpString(helpString);
 779     }
 780
 781     /** Set wxBitmap in front of the value.
 782         @remarks
 783         - Bitmap will be scaled to a size returned by wxPropertyGrid::GetImageSize();
 784     */
 785     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp )
 786     {
 787         wxPG_PROP_ARG_CALL_PROLOG()
 788         p->SetValueImage(bmp);
 789         RefreshProperty(p);
 790     }
 791
 792     /** Sets max length of property's text.
 793     */
 794     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
 795
 796     /** Sets validator of a property.
 797     */
 798     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
 799     {
 800         wxPG_PROP_ARG_CALL_PROLOG()
 801         p->SetValidator(validator);
 802     }
 803
 804     /** Sets value (long integer) of a property.
 805     */
 806     void SetPropertyValue( wxPGPropArg id, long value )
 807     {
 808         wxVariant v(value);
 809         SetPropVal( id, v );
 810     }
 811
 812     /** Sets value (integer) of a property.
 813     */
 814     void SetPropertyValue( wxPGPropArg id, int value )
 815     {
 816         wxVariant v((long)value);
 817         SetPropVal( id, v );
 818     }
 819     /** Sets value (floating point) of a property.
 820     */
 821     void SetPropertyValue( wxPGPropArg id, double value )
 822     {
 823         wxVariant v(value);
 824         SetPropVal( id, v );
 825     }
 826     /** Sets value (bool) of a property.
 827     */
 828     void SetPropertyValue( wxPGPropArg id, bool value )
 829     {
 830         wxVariant v(value);
 831         SetPropVal( id, v );
 832     }
 833     void SetPropertyValue( wxPGPropArg id, const wxChar* value )
 834     {
 835         SetPropertyValueString( id, wxString(value) );
 836     }
 837     void SetPropertyValue( wxPGPropArg id, const wxString& value )
 838     {
 839         SetPropertyValueString( id, value );
 840     }
 841
 842     /** Sets value (wxArrayString) of a property.
 843     */
 844     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
 845     {
 846         wxVariant v(value);
 847         SetPropVal( id, v );
 848     }
 849
 850     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
 851     {
 852         wxVariant v(value);
 853         SetPropVal( id, v );
 854     }
 855
 856     /** Sets value (wxObject*) of a property.
 857     */
 858     void SetPropertyValue( wxPGPropArg id, wxObject* value )
 859     {
 860         wxVariant v(value);
 861         SetPropVal( id, v );
 862     }
 863
 864     void SetPropertyValue( wxPGPropArg id, wxObject& value )
 865     {
 866         wxVariant v(&value);
 867         SetPropVal( id, v );
 868     }
 869
 870     /** Sets value (wxPoint&) of a property.
 871     */
 872     void SetPropertyValue( wxPGPropArg id, const wxPoint& value )
 873     {
 874         wxVariant v = WXVARIANT(value);
 875         SetPropVal( id, v );
 876     }
 877     /** Sets value (wxSize&) of a property.
 878     */
 879     void SetPropertyValue( wxPGPropArg id, const wxSize& value )
 880     {
 881         wxVariant v = WXVARIANT(value);
 882         SetPropVal( id, v );
 883     }
 884     /** Sets value (wxLongLong&) of a property.
 885     */
 886     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value )
 887     {
 888         wxVariant v = WXVARIANT(wxLongLong(value));
 889         SetPropVal( id, v );
 890     }
 891     /** Sets value (wxULongLong&) of a property.
 892     */
 893     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value )
 894     {
 895         wxVariant v = WXVARIANT(wxULongLong(value));
 896         SetPropVal( id, v );
 897     }
 898     /** Sets value (wxArrayInt&) of a property.
 899     */
 900     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
 901     {
 902         wxVariant v = WXVARIANT(value);
 903         SetPropVal( id, v );
 904     }
 905
 906     /** Sets value (wxString) of a property.
 907
 908         @remarks
 909         This method uses wxPGProperty::SetValueFromString, which all properties
 910         should implement. This means that there should not be a type error,
 911         and instead the string is converted to property's actual value type.
 912     */
 913     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
 914
 915     /** Sets value (wxVariant&) of a property.
 916
 917         @remarks
 918         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
 919         validation process and send property change event.
 920     */
 921     void SetPropertyValue( wxPGPropArg id, wxVariant value )
 922     {
 923         SetPropVal( id, value );
 924     }
 925
 926     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
 927         in a property.
 928         @param vfbFlags
 929         See @link vfbflags list of valid flags values@endlink
 930     */
 931     void SetValidationFailureBehavior( int vfbFlags );
 932
 933     // GetPropertyByName With nice assertion error message.
 934     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
 935
 936     static wxPGEditor* GetEditorByName( const wxString& editorName );
 937
 938     virtual void RefreshProperty( wxPGProperty* p ) = 0;
 939 };
 940