interface/wx/propgrid/propgridiface.h

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