include/wx/persist.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/persist.h
   3 // Purpose:     common classes for persistence support
   4 // Author:      Vadim Zeitlin
   5 // Created:     2009-01-18
   6 // RCS-ID:      $Id: wxhead.h,v 1.10 2008-04-15 23:34:19 zeitlin Exp $
   7 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_PERSIST_H_
  12 #define _WX_PERSIST_H_
  13
  14 #include "wx/string.h"
  15 #include "wx/hashmap.h"
  16 #include "wx/confbase.h"
  17
  18 class wxPersistentObject;
  19
  20 WX_DECLARE_VOIDPTR_HASH_MAP(wxPersistentObject *, wxPersistentObjectsMap);
  21
  22 // ----------------------------------------------------------------------------
  23 // global functions
  24 // ----------------------------------------------------------------------------
  25
  26 /*
  27    We do _not_ declare this function as doing this would force us to specialize
  28    it for the user classes deriving from the standard persistent classes.
  29    However we do define overloads of wxCreatePersistentObject() for all the wx
  30    classes which means that template wxPersistentObject::Restore() picks up the
  31    right overload to use provided that the header defining the correct overload
  32    is included before calling it. And a compilation error happens if this is
  33    not done.
  34
  35 template <class T>
  36 wxPersistentObject *wxCreatePersistentObject(T *obj);
  37
  38  */
  39
  40 // ----------------------------------------------------------------------------
  41 // wxPersistenceManager: global aspects of persistent windows
  42 // ----------------------------------------------------------------------------
  43
  44 class WXDLLIMPEXP_CORE wxPersistenceManager
  45 {
  46 public:
  47     // accessor to the unique persistence manager object
  48     static wxPersistenceManager& Get();
  49
  50
  51     // globally disable restoring or saving the persistent properties (both are
  52     // enabled by default)
  53     void DisableSaving() { m_doSave = false; }
  54     void DisableRestoring() { m_doRestore = false; }
  55
  56
  57     // register an object with the manager: when using the first overload,
  58     // wxCreatePersistentObject() must be specialized for this object class;
  59     // with the second one the persistent adapter is created by the caller
  60     //
  61     // the object shouldn't be already registered with us
  62     template <class T>
  63     wxPersistentObject *Register(T *obj)
  64     {
  65         return Register(obj, wxCreatePersistentObject(obj));
  66     }
  67
  68     wxPersistentObject *Register(void *obj, wxPersistentObject *po);
  69
  70     // check if the object is registered and return the associated
  71     // wxPersistentObject if it is or NULL otherwise
  72     wxPersistentObject *Find(void *obj) const;
  73
  74     // unregister the object, this is called by wxPersistentObject itself so
  75     // there is usually no need to do it explicitly
  76     //
  77     // deletes the associated wxPersistentObject
  78     void Unregister(void *obj);
  79
  80
  81     // save/restore the state of an object
  82     //
  83     // these methods do nothing if DisableSaving/Restoring() was called
  84     //
  85     // Restore() returns true if the object state was really restored
  86     void Save(void *obj);
  87     bool Restore(void *obj);
  88
  89     // combines both Save() and Unregister() calls
  90     void SaveAndUnregister(void *obj)
  91     {
  92         Save(obj);
  93         Unregister(obj);
  94     }
  95
  96     // combines both Register() and Restore() calls
  97     template <class T>
  98     bool RegisterAndRestore(T *obj)
  99     {
 100         return Register(obj) && Restore(obj);
 101     }
 102
 103     bool RegisterAndRestore(void *obj, wxPersistentObject *po)
 104     {
 105         return Register(obj, po) && Restore(obj);
 106     }
 107
 108
 109     // methods used by the persistent objects to save and restore the data
 110     //
 111     // currently these methods simply use wxConfig::Get()
 112     //
 113     // TODO: make this customizable by allowing
 114     //          (a) specifying custom wxConfig object to use
 115     //          (b) allowing to use something else entirely
 116     template <typename T>
 117     bool
 118     SaveValue(const wxPersistentObject& who, const wxString& name, T value)
 119     {
 120         wxConfigBase * const conf = GetConfig();
 121         if ( !conf )
 122             return false;
 123
 124         return conf->Write(GetKey(who, name), value);
 125     }
 126
 127     template <typename T>
 128     bool
 129     RestoreValue(const wxPersistentObject& who, const wxString& name, T *value)
 130     {
 131         wxConfigBase * const conf = GetConfig();
 132         if ( !conf )
 133             return false;
 134
 135         return conf->Read(GetKey(who, name), value);
 136     }
 137
 138 private:
 139     // ctor is private, use Get()
 140     wxPersistenceManager()
 141     {
 142         m_doSave =
 143         m_doRestore = true;
 144     }
 145
 146     // helpers of Save/Restore(), will be customized later
 147     wxConfigBase *GetConfig() const { return wxConfigBase::Get(); }
 148     wxString GetKey(const wxPersistentObject& who, const wxString& name) const;
 149
 150
 151     // map with the registered objects as keys and associated
 152     // wxPersistentObjects as values
 153     wxPersistentObjectsMap m_persistentObjects;
 154
 155     // true if we should restore/save the settings (it doesn't make much sense
 156     // to use this class when both of them are false but setting one of them to
 157     // false may make sense in some situations)
 158     bool m_doSave,
 159          m_doRestore;
 160
 161     DECLARE_NO_COPY_CLASS(wxPersistenceManager);
 162 };
 163
 164 // ----------------------------------------------------------------------------
 165 // wxPersistentObject: ABC for anything persistent
 166 // ----------------------------------------------------------------------------
 167
 168 class wxPersistentObject
 169 {
 170 public:
 171     // ctor associates us with the object whose options we save/restore
 172     wxPersistentObject(void *obj) : m_obj(obj) { }
 173
 174     // trivial but virtual dtor
 175     virtual ~wxPersistentObject() { }
 176
 177
 178     // methods used by wxPersistenceManager
 179     // ------------------------------------
 180
 181     // save/restore the corresponding objects settings
 182     //
 183     // these methods shouldn't be used directly as they don't respect the
 184     // global wxPersistenceManager::DisableSaving/Restoring() settings, use
 185     // wxPersistenceManager methods with the same name instead
 186     virtual void Save() const = 0;
 187     virtual bool Restore() = 0;
 188
 189
 190     // get the kind of the objects we correspond to, e.g. "Frame"
 191     virtual wxString GetKind() const = 0;
 192
 193     // get the name of the object we correspond to, e.g. "Main"
 194     virtual wxString GetName() const = 0;
 195
 196
 197     // return the associated object
 198     void *GetObject() const { return m_obj; }
 199
 200 protected:
 201     // wrappers for wxPersistenceManager methods which don't require passing
 202     // "this" as the first parameter all the time
 203     template <typename T>
 204     bool SaveValue(const wxString& name, T value) const
 205     {
 206         return wxPersistenceManager::Get().SaveValue(*this, name, value);
 207     }
 208
 209     template <typename T>
 210     bool RestoreValue(const wxString& name, T *value)
 211     {
 212         return wxPersistenceManager::Get().RestoreValue(*this, name, value);
 213     }
 214
 215 private:
 216     void * const m_obj;
 217
 218     DECLARE_NO_COPY_CLASS(wxPersistentObject)
 219 };
 220
 221 #endif // _WX_PERSIST_H_
 222