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