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