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 flags
 717             Default is wxPG_RECURSE which causes colour to be set recursively.
 718             Omit this flag to only set colour for the property in question
 719             and not any of its children.
 720     */
 721     void SetPropertyBackgroundColour( wxPGPropArg id,
 722                                       const wxColour& colour,
 723                                       int flags = wxPG_RECURSE );
 724
 725     /**
 726         Sets text, bitmap, and colours for given column's cell.
 727
 728         @remarks
 729         - You can set label cell by using column 0.
 730         - You can use wxPG_LABEL as text to use default text for column.
 731     */
 732     void SetPropertyCell( wxPGPropArg id,
 733                           int column,
 734                           const wxString& text = wxEmptyString,
 735                           const wxBitmap& bitmap = wxNullBitmap,
 736                           const wxColour& fgCol = wxNullColour,
 737                           const wxColour& bgCol = wxNullColour );
 738
 739     /**
 740         Sets client data (void*) of a property.
 741
 742         @remarks
 743         This untyped client data has to be deleted manually.
 744     */
 745     void SetPropertyClientData( wxPGPropArg id, void* clientData );
 746
 747     /**
 748         Resets text and background colours of given property.
 749     */
 750     void SetPropertyColoursToDefault( wxPGPropArg id );
 751
 752     /**
 753         Sets editor for a property.
 754
 755         @param id
 756             @todo docme
 757         @param editor
 758             For builtin editors, use wxPGEditor_X, where X is builtin editor's
 759             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
 760             list).
 761
 762         For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
 763     */
 764     void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor );
 765
 766     /**
 767         Sets editor control of a property. As editor argument, use
 768         editor name string, such as "TextCtrl" or "Choice".
 769     */
 770     void SetPropertyEditor( wxPGPropArg id, const wxString& editorName );
 771
 772     /**
 773         Sets label of a property.
 774
 775         @remarks
 776         - Properties under same parent may have same labels. However,
 777         property names must still remain unique.
 778     */
 779     void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );
 780
 781     /**
 782         Sets name of a property.
 783
 784         @param id
 785             Name or pointer of property which name to change.
 786
 787         @param newName
 788             New name for property.
 789     */
 790     void SetPropertyName( wxPGPropArg id, const wxString& newName );
 791
 792     /**
 793         Sets property (and, recursively, its children) to have read-only value.
 794         In other words, user cannot change the value in the editor, but they can
 795         still copy it.
 796
 797         @remarks This is mainly for use with textctrl editor. Only some other
 798                 editors fully support it.
 799
 800         @param id
 801             Property name or pointer.
 802
 803         @param set
 804             Use @true to enable read-only, @false to disable it.
 805
 806         @param flags
 807             By default changes are applied recursively. Set this parameter
 808             wxPG_DONT_RECURSE to prevent this.
 809     */
 810     void SetPropertyReadOnly( wxPGPropArg id, bool set = true,
 811                               int flags = wxPG_RECURSE );
 812
 813     /**
 814         Sets property's value to unspecified. If it has children (it may be
 815         category), then the same thing is done to them.
 816     */
 817     void SetPropertyValueUnspecified( wxPGPropArg id );
 818
 819     /**
 820         Sets property values from a list of wxVariants.
 821     */
 822     void SetPropertyValues( const wxVariantList& list,
 823                             wxPGPropArg defaultCategory = wxNullProperty );
 824
 825     /**
 826         Sets property values from a list of wxVariants.
 827     */
 828     void SetPropertyValues( const wxVariant& list,
 829                             wxPGPropArg defaultCategory = wxNullProperty );
 830
 831     /**
 832         Associates the help string with property.
 833
 834         @remarks By default, text is shown either in the manager's "description"
 835                 text box or in the status bar. If extra window style
 836                 wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as
 837                 a tooltip.
 838     */
 839     void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString );
 840
 841     /**
 842         Set wxBitmap in front of the value.
 843
 844         @remarks Bitmap will be scaled to a size returned by
 845                 wxPropertyGrid::GetImageSize();
 846     */
 847     void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp );
 848
 849     /**
 850         Sets max length of property's text.
 851     */
 852     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
 853
 854
 855     /**
 856         Sets text colour of a property.
 857
 858         @param id
 859             Property name or pointer.
 860
 861         @param colour
 862             New background colour.
 863
 864         @param flags
 865             Default is wxPG_RECURSE which causes colour to be set recursively.
 866             Omit this flag to only set colour for the property in question
 867             and not any of its children.
 868     */
 869     void SetPropertyTextColour( wxPGPropArg id,
 870                                 const wxColour& colour,
 871                                 int flags = wxPG_RECURSE );
 872
 873     /**
 874         Sets validator of a property.
 875     */
 876     void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator );
 877
 878     /** Sets value (integer) of a property. */
 879     void SetPropertyValue( wxPGPropArg id, long value );
 880
 881     /** Sets value (integer) of a property. */
 882     void SetPropertyValue( wxPGPropArg id, int value );
 883
 884     /** Sets value (floating point) of a property. */
 885     void SetPropertyValue( wxPGPropArg id, double value );
 886
 887     /** Sets value (bool) of a property. */
 888     void SetPropertyValue( wxPGPropArg id, bool value );
 889
 890     /** Sets value (string) of a property. */
 891     void SetPropertyValue( wxPGPropArg id, const wxString& value );
 892
 893     /** Sets value (wxArrayString) of a property. */
 894     void SetPropertyValue( wxPGPropArg id, const wxArrayString& value );
 895
 896     /** Sets value (wxDateTime) of a property. */
 897     void SetPropertyValue( wxPGPropArg id, const wxDateTime& value );
 898
 899     /** Sets value (wxObject*) of a property. */
 900     void SetPropertyValue( wxPGPropArg id, wxObject* value );
 901
 902     /** Sets value (wxObject&) of a property. */
 903     void SetPropertyValue( wxPGPropArg id, wxObject& value );
 904
 905     /** Sets value (native 64-bit int) of a property. */
 906     void SetPropertyValue( wxPGPropArg id, wxLongLong_t value );
 907
 908     /** Sets value (native 64-bit unsigned int) of a property. */
 909     void SetPropertyValue( wxPGPropArg id, wxULongLong_t value );
 910
 911     /** Sets value (wxArrayInt&) of a property. */
 912     void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value );
 913
 914     /**
 915         Sets value (wxString) of a property.
 916
 917         @remarks This method uses wxPGProperty::SetValueFromString(), which all
 918                 properties should implement. This means that there should not be
 919                 a type error, and instead the string is converted to property's
 920                 actual value type.
 921     */
 922     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
 923
 924     /**
 925         Sets value (wxVariant&) of a property.
 926
 927         @remarks Use wxPropertyGrid::ChangePropertyValue() instead if you need to
 928                 run through validation process and send property change event.
 929     */
 930     void SetPropertyValue( wxPGPropArg id, wxVariant value );
 931
 932     /**
 933         Adjusts how wxPropertyGrid behaves when invalid value is entered
 934         in a property.
 935
 936         @param vfbFlags
 937             See @ref propgrid_vfbflags for possible values.
 938     */
 939     void SetValidationFailureBehavior( int vfbFlags );
 940
 941     /**
 942         Sorts all properties recursively.
 943
 944         @param flags
 945             This can contain any of the following options:
 946               wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their
 947                 immediate children. Sorting done by wxPG_AUTO_SORT option
 948                 uses this.
 949
 950         @see SortChildren, wxPropertyGrid::SetSortFunction
 951     */
 952     void Sort( int flags = 0 );
 953
 954     /**
 955         Sorts children of a property.
 956
 957         @param id
 958             Name or pointer to a property.
 959
 960         @param flags
 961             This can contain any of the following options:
 962               wxPG_RECURSE: Sorts recursively.
 963
 964         @see Sort, wxPropertyGrid::SetSortFunction
 965     */
 966     void SortChildren( wxPGPropArg id, int flags = 0 );
 967
 968     /**
 969         Returns editor pointer of editor with given name;
 970     */
 971     static wxPGEditor* GetEditorByName( const wxString& editorName );
 972 };
 973