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