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