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