interface/wx/propgrid/propgridiface.h

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