X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b69470e4eeb3301c0f606e15edaafd7425cc70dc..0fa541e8706f74887efeba9e475eae618873da2a:/interface/wx/persist.h diff --git a/interface/wx/persist.h b/interface/wx/persist.h new file mode 100644 index 0000000000..beae4c785f --- /dev/null +++ b/interface/wx/persist.h @@ -0,0 +1,273 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wx/persist.h +// Purpose: interface of wxPersistenceManager and related classes +// Author: Vadim Zeitlin +// RCS-ID: $Id$ +// Copyright: (c) 2009 Vadim Zeitlin +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Provides support for automatically saving and restoring object properties + to persistent storage. + + This class is the central element of wxWidgets persistence framework, see + @ref overview_persistence for its overview. + + This is a singleton class and its unique instance can be retrieved using + Get() method. + + @library{wxcore} + */ +class wxPersistenceManager +{ +public: + /** + Returns the unique persistence manager object. + */ + static wxPersistenceManager& Get(); + + /** + Globally disable saving the persistence object properties. + + By default, saving properties in Save() is enabled but the program may + wish to disable if, for example, it detects that it is running on a + system which shouldn't be modified in any way and so configuration + file (or Windows registry) shouldn't be written to. + + @see DisableRestoring() + */ + bool DisableSaving(); + + /** + Globally disable restoring the persistence object properties. + + By default, restoring properties in Restore() is enabled but this + function allows to disable it. This is mostly useful for testing. + + @see DisableSaving() + */ + bool DisableRestoring(); + + + /** + Register an object with the manager automatically creating a + persistence adapter for it. + + This is equivalent to calling Register(void *, wxPersistentObject *) + with wxCreatePersistentObject(obj) as the second argument. + + @param obj + The object to register. wxCreatePersistentObject() overload must be + defined for the objects of this class. + */ + template + wxPersistentObject *Register(T *obj) + { + return Register(obj, wxCreatePersistentObject(obj)); + } + + /** + Register an object with the manager. + + Note that registering the object doesn't do anything except allowing to + call Restore() for it later. If you want to register the object and + restore its properties, use RegisterAndRestore(). + + The manager takes ownership of @a po and will delete it when it is + unregistered. + + @param obj + The object to register. + @param po + The wxPersistentObject to use for saving and restoring this object + properties. + */ + wxPersistentObject *Register(void *obj, wxPersistentObject *po); + + /** + Check if the object is registered and return the associated + wxPersistentObject if it is or @NULL otherwise. + */ + wxPersistentObject *Find(void *obj) const; + + /** + Unregister the object and delete the associated wxPersistentObject. + + For the persistent windows this is done automatically (via + SaveAndUnregister()) when the window is destroyed so you only need to + call this function explicitly if you are using custom persistent + objects or if you want to prevent the object properties from being + saved. + + @param obj + An object previously registered with Register(). + */ + void Unregister(void *obj); + + + /** + Save the object properties to persistent storage. + + This method does nothing if DisableSaving() had been called. + + @param obj + An object previously registered with Register(). + + @see SaveAndUnregister() + */ + void Save(void *obj); + + /** + Restore the object properties previously saved by Save(). + + This method does nothing if DisableRestoring() had been called. + + @param obj + An object previously registered with Register(). + @return + @true if the object properties were restored or @false if nothing + was found to restore or the saved settings were invalid. + + @see RegisterAndRestore() + */ + bool Restore(void *obj); + + /// Combines both Save() and Unregister() calls. + void SaveAndUnregister(void *obj); + + /// Combines both Register() and Restore() calls. + //@{ + template + bool RegisterAndRestore(T *obj); + + bool RegisterAndRestore(void *obj, wxPersistentObject *po); + //@} +}; + +/** + Base class for persistent object adapters. + + wxWidgets persistence framework is non-intrusive, i.e. can work with the + classes which have no relationship to nor knowledge of it. To allow this, + an intermediate persistence adapter is used: this is just a simple object + which provides the methods used by wxPersistenceManager to save and restore + the object properties and implements them using the concrete class methods. + + You may derive your own classes from wxPersistentObject to implement + persistence support for your common classes, see @ref persistence_defining. + + @see wxPersistentWindow<> + */ +class wxPersistentObject +{ +public: + /** + Constructor takes the object which we're associated with. + + This object must have life-time greater than ours as we keep a pointer + to it. + */ + wxPersistentObject(void *obj); + + /// Trivial but virtual destructor. + virtual ~wxPersistentObject(); + + + /** + @name Methods to be implemented in the derived classes. + + Notice that these methods are only used by wxPersistenceManager + normally and shouldn't be called directly. + */ + //@{ + + /** + Save the object properties. + + The implementation of this method should use SaveValue(). + */ + virtual void Save() const = 0; + + /** + Restore the object properties. + + The implementation of this method should use RestoreValue(). + */ + virtual bool Restore() = 0; + + + /** + Returns the string uniquely identifying the objects supported by this + adapter. + + This method is called from SaveValue() and RestoreValue() and normally + returns some short (but not too cryptic) strings, e.g. @c "Checkbox". + */ + virtual wxString GetKind() const = 0; + + /** + Returns the string uniquely identifying the object we're associated + with among all the other objects of the same type. + + This method is used together with GetKind() to construct the unique + full name of the object in e.g. a configuration file. + */ + virtual wxString GetName() const = 0; + + //@} + + + /// Return the associated object. + void *GetObject() const; + +protected: + /** + Save the specified value using the given name. + + @param name + The name of the value in the configuration file. + @param value + The value to save, currently must be a type supported by wxConfig. + @return + @true if the value was saved or @false if an error occurred. + */ + template + bool SaveValue(const wxString& name, T value) const + { + return wxPersistenceManager::Get().SaveValue(*this, name, value); + } + + /** + Restore the value saved by Save(). + + @param name + The same name as was used by Save(). + @param value + Non-@NULL pointer which will be filled with the value if it was + read successfully or not modified if it wasn't. + @return + @true if the value was successfully read or @false if it was not + found or an error occurred. + */ + template + bool RestoreValue(const wxString& name, T *value) + { + return wxPersistenceManager::Get().RestoreValue(*this, name, value); + } +}; + +/** + Function used to create the correct persistent adapter for the given type + of objects. + + To be precise, there is no such template function definition but there are + overloads of wxCreatePersistentObject() taking different object types for + all wxWidgets classes supporting persistence. And you may also define your + own overloads to integrate your custom classes with wxWidgets persistence + framework. + + @see @ref persistence_defining + */ +template +wxPersistentObject *wxCreatePersistentObject(T *obj);