// Name: wx/persist.h
// Purpose: interface of wxPersistenceManager and related classes
// Author: Vadim Zeitlin
-// RCS-ID: $Id$
// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
This is a singleton class and its unique instance can be retrieved using
Get() method.
+ @since 2.9.0
+
@library{wxcore}
*/
class wxPersistenceManager
{
public:
+ /**
+ Set the global persistence manager to use.
+
+ Call this method to specify a non-default persistence manager to use.
+ It should usually be called very early (e.g. in wxApp-derived class
+ constructor or in the beginning of overridden wxApp::OnInit()) to
+ affect creation of all persistent controls and the object passed to it
+ must have a lifetime long enough to be still alive when the persistent
+ controls are destroyed and need it to save their state so typically
+ this would be a global or a wxApp member.
+
+ @since 2.9.3
+ */
+ static void Set(wxPersistenceManager& manager);
+
/**
Returns the unique persistence manager object.
+
+ If Set() hadn't been called before, a default persistence manager
+ implementation is returned.
*/
static wxPersistenceManager& Get();
@see DisableRestoring()
*/
- bool DisableSaving();
+ void DisableSaving();
/**
Globally disable restoring the persistence object properties.
@see DisableSaving()
*/
- bool DisableRestoring();
+ void DisableRestoring();
/**
defined for the objects of this class.
*/
template <class T>
- wxPersistentObject *Register(T *obj)
- {
- return Register(obj, wxCreatePersistentObject(obj));
- }
+ wxPersistentObject *Register(T *obj);
/**
Register an object with the manager.
@see SaveAndUnregister()
*/
void Save(void *obj);
-
+
/**
Restore the object properties previously saved by Save().
bool RegisterAndRestore(void *obj, wxPersistentObject *po);
//@}
+
+protected:
+ /**
+ Protected default constructor.
+
+ This constructor is only provided for the derived classes, to use an
+ object of this class static Get() method should be called.
+ */
+ wxPersistenceManager();
+
+ /**
+ Return the config object to use.
+
+ By default the global wxConfig, returned by wxConfigBase::Get(), is
+ used but a derived class could override this function to return a
+ different one if necessary.
+
+ @since 2.9.3
+ */
+ virtual wxConfigBase *GetConfig() const;
+
+ /**
+ Return the path to use for saving the setting with the given name for
+ the specified object.
+
+ Notice that the @a name argument is the name of the setting, not the
+ name of the object itself which can be retrieved with its GetName()
+ method.
+
+ This method can be overridden by a derived class to change where in
+ wxConfig the different options are stored. By default, all settings of
+ the persistent controls are stored under "Persistent_Options" group and
+ grouped by control type (e.g. "Window" for top level windows or
+ "Splitter") and name, so that the position of a splitter called "sep"
+ could be stored under "Persistent_Options/Splitter/sep/Position" key.
+
+ @since 2.9.3
+ */
+ virtual wxString GetKey(const wxPersistentObject& who,
+ const wxString& name) const;
};
/**
@true if the value was saved or @false if an error occurred.
*/
template <typename T>
- bool SaveValue(const wxString& name, T value) const
- {
- return wxPersistenceManager::Get().SaveValue(*this, name, value);
- }
+ bool SaveValue(const wxString& name, T value) const;
/**
Restore the value saved by Save().
found or an error occurred.
*/
template <typename T>
- bool RestoreValue(const wxString& name, T *value)
- {
- return wxPersistenceManager::Get().RestoreValue(*this, name, value);
- }
+ bool RestoreValue(const wxString& name, T *value);
};
/**
framework.
@see @ref persistence_defining
+
+ @header{wx/persist.h}
*/
template <class T>
wxPersistentObject *wxCreatePersistentObject(T *obj);
+
+/**
+ A shorter synonym for wxPersistenceManager::RegisterAndRestore().
+
+ This function simply calls wxPersistenceManager::RegisterAndRestore() but
+ using it results in slightly shorter code as it calls
+ wxPersistenceManager::Get() internally. As an additional convenience, this
+ function can also set the window name.
+
+ For the implementation reasons, this function @em must be used instead of
+ the template method when using Microsoft Visual C++ 6 compiler.
+
+ @param obj wxWindow-derived object to register with persistence manager and
+ to try to restore the settings for.
+ @param name If not empty, @a obj name is changed to the provided value
+ before registering it.
+ @return true if the settings were restored or false otherwise (this will
+ always be the case when the program runs for the first time, for
+ example).
+
+ @since 2.9.0, @a name is new in 2.9.1.
+
+ @header{wx/persist.h}
+ */
+template <class T>
+bool wxPersistentRegisterAndRestore(T *obj, const wxString& name = wxString());
projects / wxWidgets.git / blobdiff