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