interface/wx/propgrid/propgridiface.h

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