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