allow calling SetItemLabel() for items not attached to the menu or menu bar yet ...

[wxWidgets.git] / include / wx / persist.h

///////////////////////////////////////////////////////////////////////////////\r
// Name:        wx/persist.h\r
// Purpose:     common classes for persistence support\r
// Author:      Vadim Zeitlin\r
// Created:     2009-01-18\r
// RCS-ID:      $Id: wxhead.h,v 1.10 2008-04-15 23:34:19 zeitlin Exp $\r
// Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>\r
// Licence:     wxWindows licence\r
///////////////////////////////////////////////////////////////////////////////\r
\r
#ifndef _WX_PERSIST_H_\r
#define _WX_PERSIST_H_\r
\r
#include "wx/string.h"\r
#include "wx/hashmap.h"\r
#include "wx/confbase.h"\r
\r
class wxPersistentObject;\r
\r
WX_DECLARE_VOIDPTR_HASH_MAP(wxPersistentObject *, wxPersistentObjectsMap);\r
\r
// ----------------------------------------------------------------------------\r
// global functions\r
// ----------------------------------------------------------------------------\r
\r
/*\r
   We do _not_ declare this function as doing this would force us to specialize\r
   it for the user classes deriving from the standard persistent classes.\r
   However we do define overloads of wxCreatePersistentObject() for all the wx\r
   classes which means that template wxPersistentObject::Restore() picks up the\r
   right overload to use provided that the header defining the correct overload\r
   is included before calling it. And a compilation error happens if this is\r
   not done.\r
\r
template <class T>\r
wxPersistentObject *wxCreatePersistentObject(T *obj);\r
\r
 */\r
\r
// ----------------------------------------------------------------------------\r
// wxPersistenceManager: global aspects of persistent windows\r
// ----------------------------------------------------------------------------\r
\r
class WXDLLIMPEXP_CORE wxPersistenceManager\r
{\r
public:\r
    // accessor to the unique persistence manager object\r
    static wxPersistenceManager& Get();\r
\r
\r
    // globally disable restoring or saving the persistent properties (both are\r
    // enabled by default)\r
    void DisableSaving() { m_doSave = false; }\r
    void DisableRestoring() { m_doRestore = false; }\r
\r
\r
    // register an object with the manager: when using the first overload,\r
    // wxCreatePersistentObject() must be specialized for this object class;\r
    // with the second one the persistent adapter is created by the caller\r
    //\r
    // the object shouldn't be already registered with us\r
    template <class T>\r
    wxPersistentObject *Register(T *obj)\r
    {\r
        return Register(obj, wxCreatePersistentObject(obj));\r
    }\r
\r
    wxPersistentObject *Register(void *obj, wxPersistentObject *po);\r
\r
    // check if the object is registered and return the associated\r
    // wxPersistentObject if it is or NULL otherwise\r
    wxPersistentObject *Find(void *obj) const;\r
\r
    // unregister the object, this is called by wxPersistentObject itself so\r
    // there is usually no need to do it explicitly\r
    //\r
    // deletes the associated wxPersistentObject\r
    void Unregister(void *obj);\r
\r
    \r
    // save/restore the state of an object\r
    //\r
    // these methods do nothing if DisableSaving/Restoring() was called\r
    //\r
    // Restore() returns true if the object state was really restored\r
    void Save(void *obj);\r
    bool Restore(void *obj);\r
\r
    // combines both Save() and Unregister() calls\r
    void SaveAndUnregister(void *obj)\r
    {\r
        Save(obj);\r
        Unregister(obj);\r
    }\r
\r
    // combines both Register() and Restore() calls\r
    template <class T>\r
    bool RegisterAndRestore(T *obj)\r
    {\r
        return Register(obj) && Restore(obj);\r
    }\r
\r
    bool RegisterAndRestore(void *obj, wxPersistentObject *po)\r
    {\r
        return Register(obj, po) && Restore(obj);\r
    }\r
\r
\r
    // methods used by the persistent objects to save and restore the data\r
    //\r
    // currently these methods simply use wxConfig::Get()\r
    //\r
    // TODO: make this customizable by allowing\r
    //          (a) specifying custom wxConfig object to use\r
    //          (b) allowing to use something else entirely\r
    template <typename T>\r
    bool\r
    SaveValue(const wxPersistentObject& who, const wxString& name, T value)\r
    {\r
        wxConfigBase * const conf = GetConfig();\r
        if ( !conf )\r
            return false;\r
\r
        return conf->Write(GetKey(who, name), value);\r
    }\r
\r
    template <typename T>\r
    bool\r
    RestoreValue(const wxPersistentObject& who, const wxString& name, T *value)\r
    {\r
        wxConfigBase * const conf = GetConfig();\r
        if ( !conf )\r
            return false;\r
\r
        return conf->Read(GetKey(who, name), value);\r
    }\r
\r
private:\r
    // ctor is private, use Get()\r
    wxPersistenceManager()\r
    {\r
        m_doSave =\r
        m_doRestore = true;\r
    }\r
\r
    // helpers of Save/Restore(), will be customized later\r
    wxConfigBase *GetConfig() const { return wxConfigBase::Get(); }\r
    wxString GetKey(const wxPersistentObject& who, const wxString& name) const;\r
\r
\r
    // map with the registered objects as keys and associated\r
    // wxPersistentObjects as values\r
    wxPersistentObjectsMap m_persistentObjects;\r
\r
    // true if we should restore/save the settings (it doesn't make much sense\r
    // to use this class when both of them are false but setting one of them to\r
    // false may make sense in some situations)\r
    bool m_doSave,\r
         m_doRestore;\r
\r
    DECLARE_NO_COPY_CLASS(wxPersistenceManager);\r
};\r
\r
// ----------------------------------------------------------------------------\r
// wxPersistentObject: ABC for anything persistent\r
// ----------------------------------------------------------------------------\r
\r
class wxPersistentObject\r
{\r
public:\r
    // ctor associates us with the object whose options we save/restore\r
    wxPersistentObject(void *obj) : m_obj(obj) { }\r
\r
    // trivial but virtual dtor\r
    virtual ~wxPersistentObject() { }\r
\r
\r
    // methods used by wxPersistenceManager\r
    // ------------------------------------\r
\r
    // save/restore the corresponding objects settings\r
    //\r
    // these methods shouldn't be used directly as they don't respect the\r
    // global wxPersistenceManager::DisableSaving/Restoring() settings, use\r
    // wxPersistenceManager methods with the same name instead\r
    virtual void Save() const = 0;\r
    virtual bool Restore() = 0;\r
\r
\r
    // get the kind of the objects we correspond to, e.g. "Frame"\r
    virtual wxString GetKind() const = 0;\r
\r
    // get the name of the object we correspond to, e.g. "Main"\r
    virtual wxString GetName() const = 0;\r
\r
\r
    // return the associated object\r
    void *GetObject() const { return m_obj; }\r
\r
protected:\r
    // wrappers for wxPersistenceManager methods which don't require passing\r
    // "this" as the first parameter all the time\r
    template <typename T>\r
    bool SaveValue(const wxString& name, T value) const\r
    {\r
        return wxPersistenceManager::Get().SaveValue(*this, name, value);\r
    }\r
\r
    template <typename T>\r
    bool RestoreValue(const wxString& name, T *value)\r
    {\r
        return wxPersistenceManager::Get().RestoreValue(*this, name, value);\r
    }\r
\r
private:\r
    void * const m_obj;\r
\r
    DECLARE_NO_COPY_CLASS(wxPersistentObject)\r
};\r
\r
#endif // _WX_PERSIST_H_\r
\r