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