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