wxWidgets/include/wx/propgrid/propgridiface.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/propgrid/propgridiface.h
// Purpose:     wxPropertyGridInterface class
// Author:      Jaakko Salli
// Modified by:
// Created:     2008-08-24
// Copyright:   (c) Jaakko Salli
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

#ifndef __WX_PROPGRID_PROPGRIDIFACE_H__
#define __WX_PROPGRID_PROPGRIDIFACE_H__

#include "wx/defs.h"

#if wxUSE_PROPGRID

#include "wx/propgrid/property.h"
#include "wx/propgrid/propgridpagestate.h"

// -----------------------------------------------------------------------

// Most property grid functions have this type as their argument, as it can
// convey a property by either a pointer or name.
class WXDLLIMPEXP_PROPGRID wxPGPropArgCls
{
public:
    wxPGPropArgCls( const wxPGProperty* property )
    {
        m_property = const_cast<wxPGProperty*>(property);
        m_isProperty = true;
    }
    wxPGPropArgCls( const wxString& str )
    {
        m_name = str;
        m_property = NULL;
        m_isProperty = false;
    }
    wxPGPropArgCls( const wxPGPropArgCls& id )
    {
        m_isProperty = id.m_isProperty;
        m_property = id.m_property;
        m_name = id.m_name;
    }
    // This is only needed for wxPython bindings.
    wxPGPropArgCls( wxString* str, bool WXUNUSED(deallocPtr) )
    {
        m_name = *str;
        delete str; // we own this string
        m_property = NULL;
        m_isProperty = false;
    }
    wxPGProperty* GetPtr() const
    {
        wxCHECK( m_isProperty, NULL );
        return m_property;
    }
#ifndef wxNO_IMPLICIT_WXSTRING_ENCODING
    wxPGPropArgCls( const char* str )
    {
        m_name = str;
        m_property = NULL;
        m_isProperty = false;
    }
#endif // !wxNO_IMPLICIT_WXSTRING_ENCODING
    wxPGPropArgCls( const wchar_t* str )
    {
        m_name = str;
        m_property = NULL;
        m_isProperty = false;
    }
    // This constructor is required for NULL.
    wxPGPropArgCls( int )
    {
        m_property = NULL;
        m_isProperty = true;
    }
    wxPGProperty* GetPtr( wxPropertyGridInterface* iface ) const;
    wxPGProperty* GetPtr( const wxPropertyGridInterface* iface ) const
    {
        return GetPtr(const_cast<wxPropertyGridInterface*>(iface));
    }
    wxPGProperty* GetPtr0() const { return m_property; }
    bool HasName() const { return !m_isProperty; }
    const wxString& GetName() const { return m_name; }

private:
    bool m_isProperty;
    wxPGProperty* m_property;
    wxString m_name;
};

typedef const wxPGPropArgCls& wxPGPropArg;

// -----------------------------------------------------------------------

WXDLLIMPEXP_PROPGRID
void wxPGTypeOperationFailed( const wxPGProperty* p,
                              const wxString& typestr,
                              const wxString& op );
WXDLLIMPEXP_PROPGRID
void wxPGGetFailed( const wxPGProperty* p, const wxString& typestr );

// -----------------------------------------------------------------------

// Helper macro that does necessary preparations when calling
// some wxPGProperty's member function.
#define wxPG_PROP_ARG_CALL_PROLOG_0(PROPERTY) \
    PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
    if ( !p ) return;

#define wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(PROPERTY, RETVAL) \
    PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
    if ( !p ) return RETVAL;

#define wxPG_PROP_ARG_CALL_PROLOG() \
    wxPG_PROP_ARG_CALL_PROLOG_0(wxPGProperty)

#define wxPG_PROP_ARG_CALL_PROLOG_RETVAL(RVAL) \
    wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(wxPGProperty, RVAL)

#define wxPG_PROP_ID_CONST_CALL_PROLOG() \
    wxPG_PROP_ARG_CALL_PROLOG_0(const wxPGProperty)

#define wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(RVAL) \
    wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(const wxPGProperty, RVAL)

// -----------------------------------------------------------------------


// Most of the shared property manipulation interface shared by wxPropertyGrid,
// wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
// In separate wxPropertyGrid component this class was known as
// wxPropertyContainerMethods.
// wxPropertyGridInterface's property operation member functions all accept
// a special wxPGPropArg id argument, using which you can refer to properties
// either by their pointer (for performance) or by their name (for conveniency).
class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
{
public:

    // Destructor.
    virtual ~wxPropertyGridInterface() { }

    // Appends property to the list.
    // wxPropertyGrid assumes ownership of the object.
    // Becomes child of most recently added category.
    // wxPropertyGrid takes the ownership of the property pointer.
    // If appending a category with name identical to a category already in
    // the wxPropertyGrid, then newly created category is deleted, and most
    // recently added category (under which properties are appended) is set
    // to the one with same name. This allows easier adding of items to same
    // categories in multiple passes.
    // Does not automatically redraw the control, so you may need to call
    // Refresh when calling this function after control has been shown for
    // the first time.
    // This functions deselects selected property, if any. Validation
    // failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
    // selection is cleared even if editor had invalid value.
    wxPGProperty* Append( wxPGProperty* property );

    // Same as Append(), but appends under given parent property.
    wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newproperty );

    // In order to add new items into a property with fixed children (for
    // instance, wxFlagsProperty), you need to call this method. After
    // populating has been finished, you need to call EndAddChildren.
    void BeginAddChildren( wxPGPropArg id );

    // Deletes all properties.
    virtual void Clear() = 0;

    // Clears current selection, if any.
    // validation - If set to false, deselecting the property will always work,
    //   even if its editor had invalid value in it.
    // Returns true if successful or if there was no selection. May
    // fail if validation was enabled and active editor had invalid
    // value.
    bool ClearSelection( bool validation = false );

    // Resets modified status of all properties.
    void ClearModifiedStatus();

    // Collapses given category or property with children.
    // Returns true if actually collapses.
    bool Collapse( wxPGPropArg id );

    // Collapses all items that can be collapsed.
    // Return false if failed (may fail if editor value cannot be validated).
    bool CollapseAll() { return ExpandAll(false); }

    // Changes value of a property, as if from an editor.
    // Use this instead of SetPropertyValue() if you need the value to run
    // through validation process, and also send the property change event.
    // Returns true if value was successfully changed.
    bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );

    // Removes and deletes a property and any children.
    // id - Pointer or name of a property.
    // If you delete a property in a wxPropertyGrid event
    // handler, the actual deletion is postponed until the next
    // idle event.
    // This functions deselects selected property, if any.
    // Validation failure option wxPG_VFB_STAY_IN_PROPERTY is not
    // respected, ie. selection is cleared even if editor had
    // invalid value.
    void DeleteProperty( wxPGPropArg id );

    // Removes a property. Does not delete the property object, but
    // instead returns it.
    // id - Pointer or name of a property.
    // Removed property cannot have any children.
    // Also, if you remove property in a wxPropertyGrid event
    // handler, the actual removal is postponed until the next
    // idle event.
    wxPGProperty* RemoveProperty( wxPGPropArg id );

    // Disables a property.
    bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); }

    // Returns true if all property grid data changes have been committed.
    // Usually only returns false if value in active editor has been
    // invalidated by a wxValidator.
    bool EditorValidate();

    // Enables or disables property, depending on whether enable is true or
    // false. Disabled property usually appears as having grey text.
    // id - Name or pointer to a property.
    // enable - If false, property is disabled instead.
    bool EnableProperty( wxPGPropArg id, bool enable = true );

    // Called after population of property with fixed children has finished.
    void EndAddChildren( wxPGPropArg id );

    // Expands given category or property with children.
    // Returns true if actually expands.
    bool Expand( wxPGPropArg id );

    // Expands all items that can be expanded.
    bool ExpandAll( bool expand = true );

    // Returns id of first child of given property.
    // Does not return sub-properties!
    wxPGProperty* GetFirstChild( wxPGPropArg id )
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)

        if ( !p->GetChildCount() || p->HasFlag(wxPG_PROP_AGGREGATE) )
            return wxNullProperty;

        return p->Item(0);
    }

    // Returns iterator class instance.
    // flags - See wxPG_ITERATOR_FLAGS. Value wxPG_ITERATE_DEFAULT causes
    //   iteration over everything except private child properties.
    // firstProp - Property to start iteration from. If NULL, then first
    //   child of root is used.
    wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
                                        wxPGProperty* firstProp = NULL )
    {
        return wxPropertyGridIterator( m_pState, flags, firstProp );
    }

    wxPropertyGridConstIterator
    GetIterator( int flags = wxPG_ITERATE_DEFAULT,
                 wxPGProperty* firstProp = NULL ) const
    {
        return wxPropertyGridConstIterator( m_pState, flags, firstProp );
    }

    // Returns iterator class instance.
    // flags - See wxPG_ITERATOR_FLAGS. Value wxPG_ITERATE_DEFAULT causes
    //   iteration over everything except private child properties.
    // startPos - Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
    //   from the first property from the top, and wxBOTTOM means that the
    //   iteration will instead begin from bottommost valid item.
    wxPropertyGridIterator GetIterator( int flags, int startPos )
    {
        return wxPropertyGridIterator( m_pState, flags, startPos );
    }

    wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const
    {
        return wxPropertyGridConstIterator( m_pState, flags, startPos );
    }

    // Returns id of first item that matches given criteria.
    wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL )
    {
        wxPropertyGridIterator it( m_pState, flags, wxNullProperty, 1 );
        return *it;
    }

    const wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ) const
    {
        return const_cast<wxPropertyGridInterface*>(this)->GetFirst(flags);
    }

    // Returns pointer to a property with given name (case-sensitive).
    // If there is no property with such name, NULL pointer is returned.
    // Properties which have non-category, non-root parent
    // cannot be accessed globally by their name. Instead, use
    // "<property>.<subproperty>" instead of "<subproperty>".
    wxPGProperty* GetProperty( const wxString& name ) const
    {
        return GetPropertyByName(name);
    }

    // Returns map-like storage of property's attributes.
    // Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set,
    // then builtin-attributes are not included in the storage.
    const wxPGAttributeStorage& GetPropertyAttributes( wxPGPropArg id ) const
    {
        // If 'id' refers to invalid property, then we will return dummy
        // attributes (i.e. root property's attributes, which contents
        // should always be empty and of no consequence).
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_pState->DoGetRoot()->GetAttributes())
        return p->GetAttributes();
    }

    // Adds to 'targetArr' pointers to properties that have given
    // flags 'flags' set. However, if 'inverse' is set to true, then
    // only properties without given flags are stored.
    // flags - Property flags to use.
    // iterFlags - Iterator flags to use. Default is everything expect private children.
    void GetPropertiesWithFlag( wxArrayPGProperty* targetArr,
                                wxPGProperty::FlagType flags,
                                bool inverse = false,
                                int iterFlags = wxPG_ITERATE_PROPERTIES |
                                                wxPG_ITERATE_HIDDEN |
                                                wxPG_ITERATE_CATEGORIES) const;

    // Returns value of given attribute. If none found, returns wxNullVariant.
    wxVariant GetPropertyAttribute( wxPGPropArg id,
                                    const wxString& attrName ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullVariant)
        return p->GetAttribute(attrName);
    }

    // Returns pointer of property's nearest parent category. If no category
    // found, returns NULL.
    wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const
    {
        wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(NULL)
        return m_pState->GetPropertyCategory(p);
    }

    // Returns client data (void*) of a property.
    void* GetPropertyClientData( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
        return p->GetClientData();
    }

    // Returns first property which label matches given string.
    // NULL if none found. Note that this operation is extremely slow when
    // compared to GetPropertyByName().
    wxPGProperty* GetPropertyByLabel( const wxString& label ) const;

    // Returns pointer to a property with given name (case-sensitive).
    // If there is no property with such name, @NULL pointer is returned.
    wxPGProperty* GetPropertyByName( const wxString& name ) const;

    // Returns child property 'subname' of property 'name'. Same as
    // calling GetPropertyByName("name.subname"), albeit slightly faster.
    wxPGProperty* GetPropertyByName( const wxString& name,
                                     const wxString& subname ) const;

    // Returns property's editor.
    const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
        return p->GetEditorClass();
    }

    // Returns help string associated with a property.
    wxString GetPropertyHelpString( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxEmptyString)
        return p->GetHelpString();
    }

    // Returns property's custom value image (NULL of none).
    wxBitmap* GetPropertyImage( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
        return p->GetValueImage();
    }

    // Returns label of a property.
    const wxString& GetPropertyLabel( wxPGPropArg id )
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString)
        return p->GetLabel();
    }

    // Returns name of a property, by which it is globally accessible.
    wxString GetPropertyName( wxPGProperty* property )
    {
        return property->GetName();
    }

    // Returns parent item of a property.
    wxPGProperty* GetPropertyParent( wxPGPropArg id )
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty)
        return p->GetParent();
    }

#if wxUSE_VALIDATORS
    // Returns validator of a property as a reference, which you
    // can pass to any number of SetPropertyValidator.
    wxValidator* GetPropertyValidator( wxPGPropArg id )
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
        return p->GetValidator();
    }
#endif

    // Returns value as wxVariant. To get wxObject pointer from it,
    // you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro.
    // If property value is unspecified, wxNullVariant is returned.
    wxVariant GetPropertyValue(wxPGPropArg id);

    wxString GetPropertyValueAsString( wxPGPropArg id ) const;
    long GetPropertyValueAsLong( wxPGPropArg id ) const;
    unsigned long GetPropertyValueAsULong( wxPGPropArg id ) const
    {
        return (unsigned long) GetPropertyValueAsLong(id);
    }
    int GetPropertyValueAsInt( wxPGPropArg id ) const
        { return (int)GetPropertyValueAsLong(id); }
    bool GetPropertyValueAsBool( wxPGPropArg id ) const;
    double GetPropertyValueAsDouble( wxPGPropArg id ) const;

    wxArrayString GetPropertyValueAsArrayString(wxPGPropArg id) const;

#if defined(wxLongLong_t) && wxUSE_LONGLONG
    wxLongLong_t GetPropertyValueAsLongLong(wxPGPropArg id) const;

    wxULongLong_t GetPropertyValueAsULongLong(wxPGPropArg id) const;
#endif

    wxArrayInt GetPropertyValueAsArrayInt(wxPGPropArg id) const;

#if wxUSE_DATETIME
    wxDateTime GetPropertyValueAsDateTime(wxPGPropArg id) const;
#endif

    // Returns a wxVariant list containing wxVariant versions of all
    // property values. Order is not guaranteed.
    // flags - Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
    // category will be its own wxVariantList of wxVariant.
    // Use wxPG_INC_ATTRIBUTES to include property attributes as well.
    // Each attribute will be stored as list variant named
    // "@<propname>@attr."
    wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
        wxPGProperty* baseparent = NULL, long flags = 0 ) const
    {
        return m_pState->DoGetPropertyValues(listname, baseparent, flags);
    }

    // Returns currently selected property. NULL if none.
    // When wxPG_EX_MULTIPLE_SELECTION extra style is used, this
    // member function returns the focused property, that is the
    // one which can have active editor.
    wxPGProperty* GetSelection() const;

    // Returns list of currently selected properties.
    // wxArrayPGProperty should be compatible with std::vector API.
    const wxArrayPGProperty& GetSelectedProperties() const
    {
        return m_pState->m_selection;
    }

    wxPropertyGridPageState* GetState() const { return m_pState; }

    // Similar to GetIterator(), but instead returns wxPGVIterator instance,
    // which can be useful for forward-iterating through arbitrary property
    // containers.
    // flags - See wxPG_ITERATOR_FLAGS.
    virtual wxPGVIterator GetVIterator( int flags ) const;

    // Hides or reveals a property.
    // hide - If true, hides property, otherwise reveals it.
    // flags - By default changes are applied recursively. Set this parameter
    //   wxPG_DONT_RECURSE to prevent this.
    bool HideProperty( wxPGPropArg id,
                       bool hide = true,
                       int flags = wxPG_RECURSE );

#if wxPG_INCLUDE_ADVPROPS
    // Initializes *all* property types. Causes references to most object
    // files in the library, so calling this may cause significant increase
    // in executable size when linking with static library.
    static void InitAllTypeHandlers();
#else
    static void InitAllTypeHandlers() { }
#endif

    // Inserts property to the property container.
    // priorThis - New property is inserted just prior to this. Available only
    //   in the first variant. There are two versions of this function
    //   to allow this parameter to be either an id or name to
    //   a property.
    // newproperty - Pointer to the inserted property. wxPropertyGrid will take
    //   ownership of this object.
    // Returns id for the property,
    // wxPropertyGrid takes the ownership of the property pointer.
    // While Append may be faster way to add items, make note that when
    // both types of data storage (categoric and
    // non-categoric) are active, Insert becomes even more slow. This is
    // especially true if current mode is non-categoric.
    // Example of use:
    //  // append category
    //  wxPGProperty* my_cat_id = propertygrid->Append(
    //     new wxPropertyCategory("My Category") );
    //  ...
    //  // insert into category - using second variant
    //  wxPGProperty* my_item_id_1 = propertygrid->Insert(
    //     my_cat_id, 0, new wxStringProperty("My String 1") );
    // // insert before to first item - using first variant
    //  wxPGProperty* my_item_id_2 = propertygrid->Insert(
    //     my_item_id, new wxStringProperty("My String 2") );
    wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty );

    // Inserts property to the property container.
    //See the other overload for more details.
    // parent - New property is inserted under this category. Available only
    //   in the second variant. There are two versions of this function
    //   to allow this parameter to be either an id or name to
    //   a property.
    // index - Index under category. Available only in the second variant.
    //   If index is < 0, property is appended in category.
    // newproperty - Pointer to the inserted property. wxPropertyGrid will take
    // ownership of this object.
    // Returns id for the property.
    wxPGProperty* Insert( wxPGPropArg parent,
                          int index,
                          wxPGProperty* newproperty );

    // Returns true if property is a category.
    bool IsPropertyCategory( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
        return p->IsCategory();
    }

    // Returns true if property is enabled.
    bool IsPropertyEnabled( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
        return !p->HasFlag(wxPG_PROP_DISABLED);
    }

    // Returns true if given property is expanded.
    // Naturally, always returns false for properties that cannot be expanded.
    bool IsPropertyExpanded( wxPGPropArg id ) const;

    // Returns true if property has been modified after value set or modify
    // flag clear by software.
    bool IsPropertyModified( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
#if WXWIN_COMPATIBILITY_3_0
        return p->HasFlag(wxPG_PROP_MODIFIED)?true:false;
#else
        return p->HasFlag(wxPG_PROP_MODIFIED);
#endif
    }

    // Returns true if property is selected.
    bool IsPropertySelected( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
        return m_pState->DoIsPropertySelected(p);
    }

    // Returns true if property is shown (i.e. HideProperty with true not
    // called for it).
    bool IsPropertyShown( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
        return !p->HasFlag(wxPG_PROP_HIDDEN);
    }

    // Returns true if property value is set to unspecified.
    bool IsPropertyValueUnspecified( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
        return p->IsValueUnspecified();
    }

    // Disables (limit = true) or enables (limit = false) wxTextCtrl editor
    // of a property, if it is not the sole mean to edit the value.
    void LimitPropertyEditing( wxPGPropArg id, bool limit = true );

    // If state is shown in it's grid, refresh it now.
    virtual void RefreshGrid( wxPropertyGridPageState* state = NULL );

#if wxPG_INCLUDE_ADVPROPS
    // Initializes additional property editors (SpinCtrl etc.). Causes
    // references to most object files in the library, so calling this may
    // cause significant increase in executable size when linking with static
    // library.
    static void RegisterAdditionalEditors();
#else
    static void RegisterAdditionalEditors() { }
#endif

    // Replaces property with id with newly created property. For example,
    // this code replaces existing property named "Flags" with one that
    // will have different set of items:
    //   pg->ReplaceProperty("Flags",
    //            wxFlagsProperty("Flags", wxPG_LABEL, newItems))
    // For more info, see wxPropertyGrid::Insert.
    wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property );

    // Flags for wxPropertyGridInterface::SaveEditableState()
    // and wxPropertyGridInterface::RestoreEditableState().
    enum EditableStateFlags
    {
        // Include selected property.
        SelectionState   = 0x01,
        // Include expanded/collapsed property information.
        ExpandedState    = 0x02,
        // Include scrolled position.
        ScrollPosState   = 0x04,
        // Include selected page information.
        // Only applies to wxPropertyGridManager.
        PageState        = 0x08,
        // Include splitter position. Stored for each page.
        SplitterPosState = 0x10,
        // Include description box size.
        // Only applies to wxPropertyGridManager.
        DescBoxState     = 0x20,

        // Include all supported user editable state information.
        // This is usually the default value.
        AllStates        = SelectionState |
                           ExpandedState |
                           ScrollPosState |
                           PageState |
                           SplitterPosState |
                           DescBoxState
    };

    // Restores user-editable state.
    // See also wxPropertyGridInterface::SaveEditableState().
    // src - String generated by SaveEditableState.
    // restoreStates - Which parts to restore from source string. See @ref
    //   propgridinterface_editablestate_flags "list of editable state
    //   flags".
    // Returns false if there was problem reading the string.
    // If some parts of state (such as scrolled or splitter position) fail to
    // restore correctly, please make sure that you call this function after
    // wxPropertyGrid size has been set (this may sometimes be tricky when
    // sizers are used).
    bool RestoreEditableState( const wxString& src,
                               int restoreStates = AllStates );

    // Used to acquire user-editable state (selected property, expanded
    // properties, scrolled position, splitter positions).
    // includedStates - Which parts of state to include. See EditableStateFlags.
    wxString SaveEditableState( int includedStates = AllStates ) const;

    // Lets user set the strings listed in the choice dropdown of a
    // wxBoolProperty. Defaults are "True" and "False", so changing them to,
    // say, "Yes" and "No" may be useful in some less technical applications.
    static void SetBoolChoices( const wxString& trueChoice,
                                const wxString& falseChoice );

    // Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER
    // window style needs to be used to indicate that columns are auto-
    // resizable.
    // Returns false on failure.
    // You should call this for individual pages of wxPropertyGridManager
    // (if used).
    bool SetColumnProportion( unsigned int column, int proportion );

    // Returns auto-resize proportion of the given column.
    int GetColumnProportion( unsigned int column ) const
    {
        return m_pState->DoGetColumnProportion(column);
    }

    // Sets an attribute for this property.
    // name - Text identifier of attribute. See @ref propgrid_property_attributes.
    // value - Value of attribute.
    // argFlags - Optional. Use wxPG_RECURSE to set the attribute to child
    //   properties recursively.
    // Setting attribute's value to wxNullVariant will simply remove it
    // from property's set of attributes.
    void SetPropertyAttribute( wxPGPropArg id,
                               const wxString& attrName,
                               wxVariant value,
                               long argFlags = 0 )
    {
        DoSetPropertyAttribute(id,attrName,value,argFlags);
    }

    // Sets property attribute for all applicable properties.
    // Be sure to use this method only after all properties have been
    // added to the grid.
    void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );

    // Sets background colour of a property.
    // id - Property name or pointer.
    // colour - New background colour.
    // flags - Default is wxPG_RECURSE which causes colour to be set recursively.
    //   Omit this flag to only set colour for the property in question
    //   and not any of its children.
    void SetPropertyBackgroundColour( wxPGPropArg id,
                                      const wxColour& colour,
                                      int flags = wxPG_RECURSE );

    // Resets text and background colours of given property.
    // id - Property name or pointer.
    // flags - Default is wxPG_DONT_RECURSE which causes colour to be reset
    //   only for the property in question (for backward compatibility).
#if WXWIN_COMPATIBILITY_3_0
    void SetPropertyColoursToDefault(wxPGPropArg id);
    void SetPropertyColoursToDefault(wxPGPropArg id, int flags);
#else
    void SetPropertyColoursToDefault(wxPGPropArg id, int flags = wxPG_DONT_RECURSE);
#endif // WXWIN_COMPATIBILITY_3_0

    // Sets text colour of a property.
    // id - Property name or pointer.
    // colour - New background colour.
    // flags - Default is wxPG_RECURSE which causes colour to be set recursively.
    //   Omit this flag to only set colour for the property in question
    //   and not any of its children.
    void SetPropertyTextColour( wxPGPropArg id,
                                const wxColour& col,
                                int flags = wxPG_RECURSE );

    // Returns background colour of first cell of a property.
    wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour())
        return p->GetCell(0).GetBgCol();
    }

    // Returns text colour of first cell of a property.
    wxColour GetPropertyTextColour( wxPGPropArg id ) const
    {
        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour())
        return p->GetCell(0).GetFgCol();
    }

    // Sets text, bitmap, and colours for given column's cell.
    // You can set label cell by setting column to 0.
    // You can use wxPG_LABEL as text to use default text for column.
    void SetPropertyCell( wxPGPropArg id,
                          int column,
                          const wxString& text = wxEmptyString,
                          const wxBitmapBundle& bitmap = wxBitmapBundle(),
                          const wxColour& fgCol = wxNullColour,
                          const wxColour& bgCol = wxNullColour );

    // Sets client data (void*) of a property.
    // This untyped client data has to be deleted manually.
    void SetPropertyClientData( wxPGPropArg id, void* clientData )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        p->SetClientData(clientData);
    }

    // Sets editor for a property.
    // editor - For builtin editors, use wxPGEditor_X, where X is builtin editor's
    // name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
    // list).
    // For custom editors, use pointer you received from
    // wxPropertyGrid::RegisterEditorClass().
    void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        wxCHECK_RET( editor, wxS("unknown/NULL editor") );
        p->SetEditor(editor);
        RefreshProperty(p);
    }

    // Sets editor control of a property. As editor argument, use
    // editor name string, such as "TextCtrl" or "Choice".
    void SetPropertyEditor( wxPGPropArg id, const wxString& editorName )
    {
        SetPropertyEditor(id,GetEditorByName(editorName));
    }

    // Sets label of a property.
    // Properties under same parent may have same labels. However,
    // property names must still remain unique.
    void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel );

    // Sets name of a property.
    // id - Name or pointer of property which name to change.
    // newName - New name for property.
    void SetPropertyName( wxPGPropArg id, const wxString& newName )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        m_pState->DoSetPropertyName( p, newName );
    }

    // Sets property (and, recursively, its children) to have read-only value.
    // In other words, user cannot change the value in the editor, but they
    // can still copy it.
    // This is mainly for use with textctrl editor. Not all other editors fully
    // support it.
    // By default changes are applied recursively. Set parameter "flags"
    // to wxPG_DONT_RECURSE to prevent this.
    void SetPropertyReadOnly( wxPGPropArg id,
                              bool set = true,
                              int flags = wxPG_RECURSE );

    // Sets property's value to unspecified.
    // If it has children (it may be category), then the same thing is done to
    // them.
    void SetPropertyValueUnspecified( wxPGPropArg id )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        p->SetValueToUnspecified();
    }

    // Sets property values from a list of wxVariants.
    void SetPropertyValues( const wxVariantList& list,
                            wxPGPropArg defaultCategory = wxNullProperty )
    {
        wxPGProperty* p = defaultCategory.HasName() ?
                          defaultCategory.GetPtr(this) : defaultCategory.GetPtr0();
        m_pState->DoSetPropertyValues(list, p);
    }

    // Sets property values from a list of wxVariants.
    void SetPropertyValues( const wxVariant& list,
                            wxPGPropArg defaultCategory = wxNullProperty )
    {
        SetPropertyValues(list.GetList(),defaultCategory);
    }

    // Associates the help string with property.
    // By default, text is shown either in the manager's "description"
    // text box or in the status bar. If extra window style
    // wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a
    // tooltip.
    void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        p->SetHelpString(helpString);
    }

    // Set wxBitmap in front of the value.
    // Bitmap will be scaled to a size returned by
    // wxPropertyGrid::GetImageSize();
    void SetPropertyImage( wxPGPropArg id, const wxBitmapBundle& bmp )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        p->SetValueImage(bmp);
        RefreshProperty(p);
    }

    // Sets max length of property's text.
    bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );

#if wxUSE_VALIDATORS
    // Sets validator of a property.
    void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        p->SetValidator(validator);
    }
#endif

    // Sets value (long integer) of a property.
    void SetPropertyValue( wxPGPropArg id, long value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }

    // Sets value (integer) of a property.
    void SetPropertyValue( wxPGPropArg id, int value )
    {
        wxVariant v((long)value);
        SetPropVal( id, v );
    }

    // Sets value (floating point) of a property.
    void SetPropertyValue( wxPGPropArg id, double value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }

    // Sets value (bool) of a property.
    void SetPropertyValue( wxPGPropArg id, bool value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }

    // Sets value (wchar_t*) of a property.
    void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
    {
        SetPropertyValueString( id, wxString(value) );
    }

#ifndef wxNO_IMPLICIT_WXSTRING_ENCODING
    // Sets value (char*) of a property.
    void SetPropertyValue( wxPGPropArg id, const char* value )
    {
        SetPropertyValueString( id, wxString(value) );
    }
#endif // !wxNO_IMPLICIT_WXSTRING_ENCODING

    // Sets value (string) of a property.
    void SetPropertyValue( wxPGPropArg id, const wxString& value )
    {
        SetPropertyValueString( id, value );
    }

    // Sets value (wxArrayString) of a property.
    void SetPropertyValue( wxPGPropArg id, const wxArrayString& value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }

#if wxUSE_DATETIME
    // Sets value (wxDateTime) of a property.
    void SetPropertyValue( wxPGPropArg id, const wxDateTime& value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }
#endif

    // Sets value (wxObject*) of a property.
    void SetPropertyValue( wxPGPropArg id, wxObject* value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }

    // Sets value (wxObject&) of a property.
    void SetPropertyValue( wxPGPropArg id, wxObject& value )
    {
        wxVariant v(&value);
        SetPropVal( id, v );
    }

#if wxUSE_LONGLONG
#ifdef wxLongLong_t
    // Sets value (native 64-bit int) of a property.
    void SetPropertyValue(wxPGPropArg id, wxLongLong_t value)
    {
        wxVariant v = wxLongLong(value);
        SetPropVal(id, v);
    }
#endif
    // Sets value (wxLongLong) of a property.
    void SetPropertyValue( wxPGPropArg id, wxLongLong value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }
#ifdef wxULongLong_t
    // Sets value (native 64-bit unsigned int) of a property.
    void SetPropertyValue(wxPGPropArg id, wxULongLong_t value)
    {
        wxVariant v = wxULongLong(value);
        SetPropVal(id, v);
    }
#endif
    // Sets value (wxULongLong) of a property.
    void SetPropertyValue( wxPGPropArg id, wxULongLong value )
    {
        wxVariant v(value);
        SetPropVal( id, v );
    }
#endif

    // Sets value (wxArrayInt&) of a property.
    void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value )
    {
        wxVariant v = WXVARIANT(value);
        SetPropVal( id, v );
    }

    // Sets value (wxString) of a property.
    // This method uses wxPGProperty::SetValueFromString, which all properties
    // should implement. This means that there should not be a type error,
    // and instead the string is converted to property's actual value type.
    void SetPropertyValueString( wxPGPropArg id, const wxString& value );

    // Sets value (wxVariant) of a property.
    // Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
    // through validation process and send property change event.
    void SetPropertyValue( wxPGPropArg id, wxVariant value )
    {
        SetPropVal( id, value );
    }

    // Sets value (wxVariant&) of a property. Same as SetPropertyValue,
    // but accepts reference.
    void SetPropVal( wxPGPropArg id, wxVariant& value );

    // Adjusts how wxPropertyGrid behaves when invalid value is entered
    // in a property.
    // vfbFlags - See wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS for possible values.
    void SetValidationFailureBehavior( int vfbFlags );

    // Sorts all properties recursively.
    // flags - This can contain any of the following options:
    //    wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their
    //    immediate children. Sorting done by wxPG_AUTO_SORT option
    //    uses this.
    // See SortChildren, wxPropertyGrid::SetSortFunction
    void Sort( int flags = 0 );

    // Sorts children of a property.
    // id - Name or pointer to a property.
    // flags - This can contain any of the following options:
    //   wxPG_RECURSE: Sorts recursively.
    // See Sort, wxPropertyGrid::SetSortFunction
    void SortChildren( wxPGPropArg id, int flags = 0 )
    {
        wxPG_PROP_ARG_CALL_PROLOG()
        m_pState->DoSortChildren(p, flags);
    }

    // GetPropertyByName() with nice assertion error message.
    wxPGProperty* GetPropertyByNameA( const wxString& name ) const;

    // Returns editor pointer of editor with given name.
    static wxPGEditor* GetEditorByName( const wxString& editorName );

    // NOTE: This function reselects the property and may cause
    //       excess flicker, so to just call Refresh() on a rect
    //       of single property, call DrawItem() instead.
    virtual void RefreshProperty( wxPGProperty* p ) = 0;

protected:

    bool DoClearSelection( bool validation = false,
                           int selFlags = 0 );

    // In derived class, implement to set editable state component with
    // given name to given value.
    virtual bool SetEditableStateItem( const wxString& name, wxVariant value )
    {
        wxUnusedVar(name);
        wxUnusedVar(value);
        return false;
    }

    // In derived class, implement to return editable state component with
    // given name.
    virtual wxVariant GetEditableStateItem( const wxString& name ) const
    {
        wxUnusedVar(name);
        return wxNullVariant;
    }

    // Returns page state data for given (sub) page (-1 means current page).
    virtual wxPropertyGridPageState* GetPageState( int pageIndex ) const
    {
        return pageIndex <= 0 ? m_pState : NULL;
    }

    virtual bool DoSelectPage( int WXUNUSED(index) ) { return true; }

    // Default call's m_pState's BaseGetPropertyByName
    virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;

    // Deriving classes must set this (it must be only or current page).
    wxPropertyGridPageState*         m_pState;

    // Intermediate version needed due to wxVariant copying inefficiency
    void DoSetPropertyAttribute( wxPGPropArg id,
                                 const wxString& name,
                                 wxVariant& value, long argFlags );

    // Empty string object to return from member functions returning const
    // wxString&.
    wxString                    m_emptyString;

private:
    // Cannot be GetGrid() due to ambiguity issues.
    wxPropertyGrid* GetPropertyGrid()
    {
        return m_pState ? m_pState->GetGrid() : NULL;
    }

    // Cannot be GetGrid() due to ambiguity issues.
    const wxPropertyGrid* GetPropertyGrid() const
    {
        return m_pState ? m_pState->GetGrid() : NULL;
    }
};

#endif // wxUSE_PROPGRID

#endif // __WX_PROPGRID_PROPGRIDIFACE_H__