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