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. To get wxObject pointer from it,
 354         you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro.
 355
 356         If property value is unspecified, Null variant is returned.
 357     */
 358     wxVariant GetPropertyValue( wxPGPropArg id )
 359     {
 360         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant())
 361         return p->GetValue();
 362     }
 363
 364     wxString GetPropertyValueAsString( wxPGPropArg id ) const;
 365     long GetPropertyValueAsLong( wxPGPropArg id ) const;
 366     unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const
 367     {
 368         return (unsigned long) GetPropertyValueAsLong(id);
 369     }
 370     int GetPropertyValueAsInt( wxPGPropArg id ) const { return (int)GetPropertyValueAsLong(id); }
 371     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
 372     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 373     wxObject* GetPropertyValueAsWxObjectPtr( wxPGPropArg id ) const;
 374     void* GetPropertyValueAsVoidPtr( wxPGPropArg id ) const;
 375
 376     wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const
 377     {
 378         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("arrstring"), wxArrayString())
 379         return p->m_value.GetArrayString();
 380     }
 381
 382     wxPoint GetPropertyValueAsPoint( wxPGPropArg id ) const
 383     {
 384         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxPoint"), wxPoint())
 385         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxPoint);
 386     }
 387
 388     wxSize GetPropertyValueAsSize( wxPGPropArg id ) const
 389     {
 390         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxSize"), wxSize())
 391         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxSize);
 392     }
 393
 394     wxLongLong_t GetPropertyValueAsLongLong( wxPGPropArg id ) const
 395     {
 396         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(wxT("wxLongLong"), (long) GetPropertyValueAsLong(id))
 397         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxLongLong).GetValue();
 398     }
 399
 400     wxULongLong_t GetPropertyValueAsULongLong( wxPGPropArg id ) const
 401     {
 402         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(wxT("wxULongLong"), (unsigned long) GetPropertyValueAsULong(id))
 403         return WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxULongLong).GetValue();
 404     }
 405
 406     wxArrayInt GetPropertyValueAsArrayInt( wxPGPropArg id ) const
 407     {
 408         wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(wxT("wxArrayInt"), wxArrayInt())
 409         wxArrayInt arr = WX_PG_VARIANT_GETVALUEREF(p->GetValue(), wxArrayInt);
 410         return arr;
 411     }
 412
 413     wxDateTime GetPropertyValueAsDateTime( wxPGPropArg id ) const
 414     {
 415         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxDateTime())
 416
 417         if ( wxStrcmp(p->m_value.GetType(), wxT("datetime")) != 0 )
 418         {
 419             wxPGGetFailed(p, wxT("datetime"));
 420             return wxDateTime();
 421         }
 422         return p->m_value.GetDateTime();
 423     }
 424
 425     /** Returns a wxVariant list containing wxVariant versions of all
 426         property values. Order is not guaranteed.
 427         @param flags
 428         Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
 429         category will be its own wxVariantList of wxVariant.
 430         Use wxPG_INC_ATTRIBUTES to include property attributes as well.
 431         Each attribute will be stored as list variant named "@@<propname>@@attr."
 432         @remarks
 433     */
 434     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
 435         wxPGProperty* baseparent = NULL, long flags = 0 ) const
 436     {
 437         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
 438     }
 439
 440     wxString GetPropertyValueType( wxPGPropArg id )
 441     {
 442         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
 443         return p->GetValueType();
 444     }
 445
 446     /** Returns currently selected property. */
 447     wxPGProperty* GetSelection() const
 448     {
 449         return m_pState->GetSelection();
 450     }
 451
 452     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
 453         which can be useful for forward-iterating through arbitrary property
 454         containers.
 455
 456         @param flags
 457         See @ref propgrid_iterator_flags.
 458     */
 459     virtual wxPGVIterator GetVIterator( int flags ) const;
 460
 461     /** Hides or reveals a property.
 462         @param hide
 463         If true, hides property, otherwise reveals it.
 464         @param flags
 465         By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
 466     */
 467     bool HideProperty( wxPGPropArg id, bool hide = true, int flags = wxPG_RECURSE );
 468
 469     /** Initializes *all* property types. Causes references to most object
 470         files in the library, so calling this may cause significant increase
 471         in executable size when linking with static library.
 472     */
 473     static void InitAllTypeHandlers();
 474
 475     //@{
 476     /** Inserts property to the property container.
 477
 478         @param priorThis
 479         New property is inserted just prior to this. Available only
 480         in the first variant. There are two versions of this function
 481         to allow this parameter to be either an id or name to
 482         a property.
 483
 484         @param newproperty
 485         Pointer to the inserted property. wxPropertyGrid will take
 486         ownership of this object.
 487
 488         @param parent
 489         New property is inserted under this category. Available only
 490         in the second variant. There are two versions of this function
 491         to allow this parameter to be either an id or name to
 492         a property.
 493
 494         @param index
 495         Index under category. Available only in the second variant.
 496         If index is < 0, property is appended in category.
 497
 498         @return
 499         Returns id for the property,
 500
 501         @remarks
 502
 503         - wxPropertyGrid takes the ownership of the property pointer.
 504
 505         - While Append may be faster way to add items, make note that when
 506           both types of data storage (categoric and
 507           non-categoric) are active, Insert becomes even more slow. This is
 508           especially true if current mode is non-categoric.
 509
 510         Example of use:
 511
 512         @code
 513
 514             // append category
 515             wxPGProperty* my_cat_id = propertygrid->Append( new wxPropertyCategory("My Category") );
 516
 517             ...
 518
 519             // insert into category - using second variant
 520             wxPGProperty* my_item_id_1 = propertygrid->Insert( my_cat_id, 0, new wxStringProperty("My String 1") );
 521
 522             // insert before to first item - using first variant
 523             wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") );
 524
 525         @endcode
 526
 527     */
 528     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty );
 529     wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newproperty );
 530     //@}
 531
 532     /** Returns true if property is a category. */
 533     bool IsPropertyCategory( wxPGPropArg id ) const
 534     {
 535         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 536         return p->IsCategory();
 537     }
 538
 539     /** Inserts choice to a property that can accept one.
 540
 541         See AddPropertyChoice for more details.
 542     */
 543     void InsertPropertyChoice( wxPGPropArg id, const wxString& label, int index, int value = wxPG_INVALID_VALUE );
 544
 545     /** Returns true if property is enabled. */
 546     bool IsPropertyEnabled( wxPGPropArg id ) const
 547     {
 548         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 549         return (!(p->GetFlags() & wxPG_PROP_DISABLED))?true:false;
 550     }
 551
 552     /** Returns true if given property is expanded. Naturally, always returns false
 553         for properties that cannot be expanded.
 554     */
 555     bool IsPropertyExpanded( wxPGPropArg id ) const;
 556
 557     /** Returns true if property has been modified after value set or modify flag
 558         clear by software.
 559     */
 560     bool IsPropertyModified( wxPGPropArg id ) const
 561     {
 562         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 563         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
 564     }
 565
 566     /** Returns true if property is shown (ie. hideproperty with true not called for it). */
 567     bool IsPropertyShown( wxPGPropArg id ) const
 568     {
 569         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 570         return (!(p->GetFlags() & wxPG_PROP_HIDDEN))?true:false;
 571     }
 572
 573     /** Returns true if property value is set to unspecified.
 574     */
 575     bool IsPropertyValueUnspecified( wxPGPropArg id ) const
 576     {
 577         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
 578         return p->IsValueUnspecified();
 579     }
 580
 581     /** Disables (limit = true) or enables (limit = false) wxTextCtrl editor of a property,
 582         if it is not the sole mean to edit the value.
 583     */
 584     void LimitPropertyEditing( wxPGPropArg id, bool limit = true );
 585
 586     /** If state is shown in it's grid, refresh it now.
 587     */
 588     virtual void RefreshGrid();
 589
 590     /** Initializes additional property editors (SpinCtrl etc.). Causes references
 591         to most object files in the library, so calling this may cause significant increase
 592         in executable size when linking with static library.
 593     */
 594     static void RegisterAdditionalEditors();
 595
 596     /** Replaces property with id with newly created property. For example,
 597         this code replaces existing property named "Flags" with one that
 598         will have different set of items:
 599         @code
 600             pg->ReplaceProperty("Flags",
 601                 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
 602         @endcode
 603         For more info, see wxPropertyGrid::Insert.
 604     */
 605     wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property );
 606
 607
 608     /** @anchor propgridinterface_editablestate_flags
 609
 610         Flags for wxPropertyGridInterface::SaveEditableState() and
 611         wxPropertyGridInterface::RestoreEditableState().
 612     */
 613     enum EditableStateFlags
 614     {
 615         /** Include selected property. */
 616         SelectionState   = 0x01,
 617         /** Include expanded/collapsed property information. */
 618         ExpandedState    = 0x02,
 619         /** Include scrolled position. */
 620         ScrollPosState   = 0x04,
 621         /** Include selected page information. Only applies to wxPropertyGridManager. */
 622         PageState        = 0x08,
 623         /** Include splitter position. Stored for each page. */
 624         SplitterPosState = 0x10,
 625
 626         /** Include all supported user editable state information. This is usually the default value. */
 627         AllStates        = SelectionState | ExpandedState | ScrollPosState | PageState | SplitterPosState
 628     };
 629
 630     /** Restores user-editable state. See also wxPropertyGridInterface::SaveEditableState().
 631
 632         @param src
 633         String generated by SaveEditableState.
 634
 635         @param restoreStates
 636         Which parts to restore from source string. See @ref propgridinterface_editablestate_flags
 637         "list of editable state flags".
 638
 639         @return
 640         False if there was problem reading the string.
 641
 642         @remarks
 643         If some parts of state (such as scrolled or splitter position) fail to restore correctly,
 644         please make sure that you call this function after wxPropertyGrid size has been set
 645         (this may sometimes be tricky when sizers are used).
 646     */
 647     bool RestoreEditableState( const wxString& src,
 648                                int restoreStates = AllStates );
 649
 650     /** Used to acquire user-editable state (selected property, expanded properties, scrolled position,
 651         splitter positions).
 652
 653         @param includedStates
 654         Which parts of state to include. See @ref propgridinterface_editablestate_flags
 655         "list of editable state flags".
 656     */
 657     wxString SaveEditableState( int includedStates = AllStates ) const;
 658
 659     /** Lets user to set the strings listed in the choice dropdown of a wxBoolProperty.
 660         Defaults are "True" and "False", so changing them to, say, "Yes" and "No" may
 661         be useful in some less technical applications.
 662     */
 663     static void SetBoolChoices( const wxString& trueChoice, const wxString& falseChoice );
 664
 665     /** Sets or clears flag(s) of all properties in given array.
 666         @param flags
 667         Property flags to set or clear.
 668         @param inverse
 669         Set to true if you want to clear flag instead of setting them.
 670     */
 671     void SetPropertiesFlag( const wxArrayPGProperty& srcArr, wxPGProperty::FlagType flags,
 672                             bool inverse = false );
 673
 674     /** Sets an attribute for this property.
 675         @param name
 676         Text identifier of attribute. See @ref propgrid_property_attributes.
 677         @param value
 678         Value of attribute.
 679         @param argFlags
 680         Optional. Use wxPG_RECURSE to set the attribute to child properties recursively.
 681     */
 682     void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName, wxVariant value, long argFlags = 0 )
 683     {
 684         DoSetPropertyAttribute(id,attrName,value,argFlags);
 685     }
 686
 687     /** Sets attributes from a wxPGAttributeStorage.
 688     */
 689     void SetPropertyAttributes( wxPGPropArg id, const wxPGAttributeStorage& attributes )
 690     {
 691         wxPG_PROP_ARG_CALL_PROLOG()
 692         p->SetAttributes(attributes);
 693     }
 694
 695     /** Sets text, bitmap, and colours for given column's cell.
 696
 697         @remarks
 698         - You can set label cell by setting column to 0.
 699         - You can use wxPG_LABEL as text to use default text for column.
 700     */
 701     void SetPropertyCell( wxPGPropArg id,
 702                           int column,
 703                           const wxString& text = wxEmptyString,
 704                           const wxBitmap& bitmap = wxNullBitmap,
 705                           const wxColour& fgCol = wxNullColour,
 706                           const wxColour& bgCol = wxNullColour )
 707     {
 708         wxPG_PROP_ARG_CALL_PROLOG()
 709         p->SetCell( column, new wxPGCell(text, bitmap, fgCol, bgCol) );
 710     }
 711
 712     /** Set choices of a property to specified set of labels and values.
 713
 714         @remarks
 715         This operation clears the property value.
 716     */
 717     void SetPropertyChoices( wxPGPropArg id, wxPGChoices& choices)
 718     {
 719         wxPG_PROP_ARG_CALL_PROLOG()
 720         p->SetChoices(choices);
 721     }
 722
 723
 724     /** If property's set of choices is shared, then calling this method converts
 725         it to private.
 726     */
 727     void SetPropertyChoicesExclusive( wxPGPropArg id )
 728     {
 729         wxPG_PROP_ARG_CALL_PROLOG()
 730         p->SetChoicesExclusive();
 731     }
 732
 733     /** Sets client data (void*) of a property.
 734         @remarks
 735         This untyped client data has to be deleted manually.
 736     */
 737     void SetPropertyClientData( wxPGPropArg id, void* clientData )
 738     {
 739         wxPG_PROP_ARG_CALL_PROLOG()
 740         p->SetClientData(clientData);
 741     }
 742
 743     /** Sets editor for a property.
 744
 745         @param editor
 746         For builtin editors, use wxPGEditor_X, where X is builtin editor's
 747         name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
 748
 749         For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
 750     */
 751     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
 752     {
 753         wxPG_PROP_ARG_CALL_PROLOG()
 754         wxCHECK_RET( editor, wxT("unknown/NULL editor") );
 755         p->SetEditor(editor);
 756         RefreshProperty(p);
 757     }
 758
 759     /** Sets editor control of a property. As editor argument, use
 760         editor name string, such as "TextCtrl" or "Choice".
 761     */
 762     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
 763     {
 764         SetPropertyEditor(id,GetEditorByName(editorName));
 765     }
 766
 767     /** Sets label of a property.
 768
 769         @remarks
 770         - Properties under same parent may have same labels. However,
 771         property names must still remain unique.
 772     */
 773     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
 774
 775     /** Set modified status of a property and all its children.
 776     */
 777     void SetPropertyModifiedStatus( wxPGPropArg id, bool modified )
 778     {
 779         wxPG_PROP_ARG_CALL_PROLOG()
 780         p->SetModifiedStatus(modified);
 781     }
 782
 783     /** Sets property (and, recursively, its children) to have read-only value. In other words,
 784         user cannot change the value in the editor, but they can still copy it.
 785         @remarks
 786         This is mainly for use with textctrl editor. Not all other editors fully
 787         support it.
 788         @param flags
 789         By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
 790     */
 791     void SetPropertyReadOnly( wxPGPropArg id, bool set = true, int flags = wxPG_RECURSE )
 792     {
 793         wxPG_PROP_ARG_CALL_PROLOG()
 794         if ( flags & wxPG_RECURSE )
 795             p->SetFlagRecursively(wxPG_PROP_READONLY, set);
 796         else
 797             p->SetFlag(wxPG_PROP_READONLY);
 798     }
 799
 800     /** Sets property's value to unspecified. If it has children (it may be category),
 801         then the same thing is done to them.
 802     */
 803     void SetPropertyValueUnspecified( wxPGPropArg id );
 804
 805     /** Sets various property values from a list of wxVariants. If property with
 806         name is missing from the grid, new property is created under given default
 807         category (or root if omitted).
 808     */
 809     void SetPropertyValues( const wxVariantList& list, wxPGPropArg defaultCategory = wxNullProperty )
 810     {
 811         wxPGProperty *p;
 812         if ( defaultCategory.HasName() ) p = defaultCategory.GetPtr(this);
 813         else p = defaultCategory.GetPtr0();
 814         m_pState->DoSetPropertyValues(list, p);
 815     }
 816
 817     void SetPropertyValues( const wxVariant& list, wxPGPropArg defaultCategory = wxNullProperty )
 818     {
 819         SetPropertyValues(list.GetList(),defaultCategory);
 820     }
 821
 822     /** Associates the help string with property.
 823         @remarks
 824         By default, text is shown either in the manager's "description"
 825         text box or in the status bar. If extra window style wxPG_EX_HELP_AS_TOOLTIPS
 826         is used, then the text will appear as a tooltip.
 827     */
 828     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
 829     {
 830         wxPG_PROP_ARG_CALL_PROLOG()
 831         p->SetHelpString(helpString);
 832     }
 833
 834     /** Set wxBitmap in front of the value.
 835         @remarks
 836         - Bitmap will be scaled to a size returned by wxPropertyGrid::GetImageSize();
 837     */
 838     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp )
 839     {
 840         wxPG_PROP_ARG_CALL_PROLOG()
 841         p->SetValueImage(bmp);
 842         RefreshProperty(p);
 843     }
 844
 845     /** Sets max length of property's text.
 846     */
 847     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
 848
 849     /** Sets validator of a property.
 850     */
 851     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
 852     {
 853         wxPG_PROP_ARG_CALL_PROLOG()
 854         p->SetValidator(validator);
 855     }
 856
 857     /** Sets value (long integer) of a property.
 858     */
 859     void SetPropertyValue( wxPGPropArg id, long value )
 860     {
 861         wxVariant v(value);
 862         SetPropVal( id, v );
 863     }
 864
 865     /** Sets value (integer) of a property.
 866     */
 867     void SetPropertyValue( wxPGPropArg id, int value )
 868     {
 869         wxVariant v((long)value);
 870         SetPropVal( id, v );
 871     }
 872     /** Sets value (floating point) of a property.
 873     */
 874     void SetPropertyValue( wxPGPropArg id, double value )
 875     {
 876         wxVariant v(value);
 877         SetPropVal( id, v );
 878     }
 879     /** Sets value (bool) of a property.
 880     */
 881     void SetPropertyValue( wxPGPropArg id, bool value )
 882     {
 883         wxVariant v(value);
 884         SetPropVal( id, v );
 885     }
 886     void SetPropertyValue( wxPGPropArg id, const wxChar* value )
 887     {
 888         SetPropertyValueString( id, wxString(value) );
 889     }
 890     void SetPropertyValue( wxPGPropArg id, const wxString& value )
 891     {
 892         SetPropertyValueString( id, value );
 893     }
 894
 895     /** Sets value (wxArrayString) of a property.
 896     */
 897     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
 898     {
 899         wxVariant v(value);
 900         SetPropVal( id, v );
 901     }
 902
 903     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
 904     {
 905         wxVariant v(value);
 906         SetPropVal( id, v );
 907     }
 908
 909     /** Sets value (wxObject*) of a property.
 910     */
 911     void SetPropertyValue( wxPGPropArg id, wxObject* value )
 912     {
 913         wxVariant v(value);
 914         SetPropVal( id, v );
 915     }
 916
 917     void SetPropertyValue( wxPGPropArg id, wxObject& value )
 918     {
 919         wxVariant v(&value);
 920         SetPropVal( id, v );
 921     }
 922
 923     /** Sets value (wxPoint&) of a property.
 924     */
 925     void SetPropertyValue( wxPGPropArg id, const wxPoint& value )
 926     {
 927         wxVariant v = WXVARIANT(value);
 928         SetPropVal( id, v );
 929     }
 930     /** Sets value (wxSize&) of a property.
 931     */
 932     void SetPropertyValue( wxPGPropArg id, const wxSize& value )
 933     {
 934         wxVariant v = WXVARIANT(value);
 935         SetPropVal( id, v );
 936     }
 937     /** Sets value (wxLongLong&) of a property.
 938     */
 939     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value )
 940     {
 941         wxVariant v = WXVARIANT(wxLongLong(value));
 942         SetPropVal( id, v );
 943     }
 944     /** Sets value (wxULongLong&) of a property.
 945     */
 946     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value )
 947     {
 948         wxVariant v = WXVARIANT(wxULongLong(value));
 949         SetPropVal( id, v );
 950     }
 951     /** Sets value (wxArrayInt&) of a property.
 952     */
 953     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
 954     {
 955         wxVariant v = WXVARIANT(value);
 956         SetPropVal( id, v );
 957     }
 958
 959     /** Sets value (wxString) of a property.
 960
 961         @remarks
 962         This method uses wxPGProperty::SetValueFromString, which all properties
 963         should implement. This means that there should not be a type error,
 964         and instead the string is converted to property's actual value type.
 965     */
 966     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
 967
 968     /** Sets value (wxVariant&) of a property.
 969
 970         @remarks
 971         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
 972         validation process and send property change event.
 973     */
 974     void SetPropertyValue( wxPGPropArg id, wxVariant value )
 975     {
 976         SetPropVal( id, value );
 977     }
 978
 979     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
 980         in a property.
 981         @param vfbFlags
 982         See @link vfbflags list of valid flags values@endlink
 983     */
 984     void SetValidationFailureBehavior( int vfbFlags );
 985
 986     // GetPropertyByName With nice assertion error message.
 987     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
 988
 989     static wxPGEditor* GetEditorByName( const wxString& editorName );
 990
 991     virtual void RefreshProperty( wxPGProperty* p ) = 0;
 992 };
 993