f4b80e5337
Don't support this compiler any more, this allows to get rid of tons of MSVC6-specific workarounds, in particular we can now use Bind() and natural template functions calls in the library code. Also remove MSVC6 project and solution files and don't generate them when bakefile_gen is ran any more (removing the remaining occurrences of msvc6prj from the bakefiles results in weird bake-time errors, so it's simpler to just leave them there). git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@76532 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
349 lines
11 KiB
C++
349 lines
11 KiB
C++
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: wx/persist.h
|
|
// Purpose: interface of wxPersistenceManager and related classes
|
|
// Author: Vadim Zeitlin
|
|
// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
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.
|
|
|
|
@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();
|
|
|
|
/**
|
|
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()
|
|
*/
|
|
void 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()
|
|
*/
|
|
void 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 <class T>
|
|
wxPersistentObject *Register(T *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 <class T>
|
|
bool RegisterAndRestore(T *obj);
|
|
|
|
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;
|
|
};
|
|
|
|
/**
|
|
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 <typename T>
|
|
bool SaveValue(const wxString& name, T value) const;
|
|
|
|
/**
|
|
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 <typename T>
|
|
bool RestoreValue(const wxString& name, T *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
|
|
|
|
@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.
|
|
|
|
@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());
|