wx.lib.agw.persist.persistencemanager.PersistenceManager

PersistenceManager: global aspects of persistent windows.

Provides support for automatically saving and restoring object properties to persistent storage.

This class is the central element of wxPython persistence framework, see the Persistent Object Overview in the __init__.py file for its overview.

This is a singleton class and its unique instance can be retrieved using PersistenceManager.Get() method.

Class Hierarchy

Inheritance diagram for class PersistenceManager:

Methods Summary

__init__	Default class constructor.
AddBadDefaultName	Adds a name to the BAD_DEFAULT_NAMES constant.
DisableRestoring	Globally disables restoring the persistent properties (enabled by default).
DisableSaving	Globally disables saving the persistent properties (enabled by default).
DoRestoreValue	Method used by the persistent objects to restore the data.
DoSaveValue	Method used by the persistent objects to save the data.
EnableRestoring	Globally enables restoring the persistent properties (enabled by default).
EnableSaving	Globally enables saving the persistent properties (enabled by default).
Find	Checks if the object is registered and return the associated PersistentObject
Free	Destructor for the unique persistence manager object.
Get	Accessor to the unique persistence manager object.
GetConfigurationHandler	Returns the persistent configuration handler for PersistenceManager.
GetKey	Returns a correctly formatted key name for the object obj and keyName parameters.
GetManagerStyle	Returns the PersistenceManager style.
GetPersistenceDirectory	Returns a default persistent option directory for PersistenceManager.
GetPersistenceFile	Returns the persistent configuration file for PersistenceManager.
GetPersistenceKey	Returns the persistent key name inside the configuration file for PersistenceManager.
HasRestored	This method returns True if any of the windows managed by
Register	Register an object with the manager.
RegisterAndRestore	Combines both Register and Restore calls.
RegisterAndRestoreAll	Recursively registers and restore the state of the input window and of
Restore	Restores the state of an object.
RestoreAll	Recursively restore the state of the input window and of
RestoreCtrlValue	Check if we should restore the widget value, if so pass it to DoRestoreValue,
RestoreValue	Convenience method, all the action is done in DoRestoreValue.
Save	Saves the state of an object.
SaveAndUnregister	Combines both Save and Unregister calls.
SaveCtrlValue	Check if we persist the widget value, if so pass it to DoSaveValue,
SaveValue	Convenience method, all the action is done in DoSaveValue.
SetConfigurationHandler	Sets the persistent configuration handler for PersistenceManager.
SetManagerStyle	Sets the PersistenceManager style.
SetPersistenceFile	Sets the persistent configuration file for PersistenceManager.
SetPersistenceKey	Sets the persistent key name inside the configuration file for PersistenceManager.
Unregister	Unregister the object, this is called by PersistenceManager itself so there is

Properties Summary

HasRestoredProp

This property returns True if any of the windows managed by

Class API

class PersistenceManager(object)

PersistenceManager: global aspects of persistent windows.

Provides support for automatically saving and restoring object properties to persistent storage.

This class is the central element of wxPython persistence framework, see the Persistent Object Overview in the __init__.py file for its overview.

This is a singleton class and its unique instance can be retrieved using PersistenceManager.Get() method.

Methods

__init__(self)

Default class constructor.

This method should not be called directly: you should use the object obtained by PersistenceManager.Get() and assign manager styles, custom configuration files and custom configuration handlers using the appropriate methods in this class.

Interesting attributes you can set for this class are:

• configFile: the persistent configuration file for PersistenceManager, a custom file name to which FileConfig will access to store and retrieve UI settings;

• configKey: the persistent key name inside the configuration file for PersistenceManager;

• customConfigHandler: the persistent configuration handler for PersistenceManager; this attribute is an object capable of saving/restoring UI settings. This can be a cPickle object or a ConfigObj one, for example.

• style: a combination of the following values:

  Flag name	Description
  PM_SAVE_RESTORE_AUI_PERSPECTIVES	If a toplevel window has an AUI manager associated, the manager will save and restore its AUI perspective
  PM_SAVE_RESTORE_TREE_LIST_SELECTIONS	If set, the manager will save items selections in list and tree controls
  PM_PERSIST_CONTROL_VALUE	If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
  PM_DEFAULT_STYLE	Same as PM_SAVE_RESTORE_AUI_PERSPECTIVES

Note

An individual window can also set the variable persistValue to indicate that its value should be saved/restored even so the style PM_PERSIST_CONTROL_VALUE is not set.

Note

UI settings are stored as dictionaries key <=> tuple: the tuple value contains two items. The first is the value type (i.e., float, int, bool etc…) while the second is the actual key value.

---

AddBadDefaultName(self, name)

Adds a name to the BAD_DEFAULT_NAMES constant.

Parameters:

name – a string specifying the control’s default name.

---

DisableRestoring(self)

Globally disables restoring the persistent properties (enabled by default).

Note

By default, restoring properties in Restore is enabled but this function allows to disable it. This is mostly useful for testing.

---

DisableSaving(self)

Globally disables saving the persistent properties (enabled by default).

Note

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.

---

DoRestoreValue(self, obj, keyName)

Method used by the persistent objects to restore the data.

By default this method simply use FileConfig but this behaviour may be overridden by passing a custom config handler in the PersistenceManager constructor.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name.

---

DoSaveValue(self, obj, keyName, value)

Method used by the persistent objects to save the data.

By default this method simply use FileConfig but this behaviour may be overridden by passing a custom configuration handler in the PersistenceManager constructor.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name;

• value – the value to store in the configuration file.

---

EnableRestoring(self)

Globally enables restoring the persistent properties (enabled by default).

Note

By default, restoring properties in Restore is enabled but this function allows to disable it. This is mostly useful for testing.

---

EnableSaving(self)

Globally enables saving the persistent properties (enabled by default).

Note

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.

---

Find(self, window)

Checks if the object is registered and return the associated PersistentObject if it is or None otherwise.

Parameters:

window – an instance of wx.Window.

---

classmethod Free(self)

Destructor for the unique persistence manager object.

---

classmethod Get(self)

Accessor to the unique persistence manager object.

---

GetConfigurationHandler(self)

Returns the persistent configuration handler for PersistenceManager.

---

GetKey(self, obj, keyName)

Returns a correctly formatted key name for the object obj and keyName parameters.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name.

---

GetManagerStyle(self)

Returns the PersistenceManager style.

See also

SetManagerStyle for a list of possible styles.

---

GetPersistenceDirectory(self)

Returns a default persistent option directory for PersistenceManager.

Note

The return value of this method is not used if you are using your own custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc…) or if you have specified a custom configuration file to use with FileConfig.

---

GetPersistenceFile(self)

Returns the persistent configuration file for PersistenceManager.

Note

The return value of this method is not used if you are using your own custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc…).

---

GetPersistenceKey(self)

Returns the persistent key name inside the configuration file for PersistenceManager.

Note

The return value of this method is not used if you are using your own custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc…).

---

HasRestored(self)

This method returns True if any of the windows managed by PersistenceManager has had its settings restored.

Returns:

True if any window was restored, False otherwise.

Added in version 0.9.7.

---

Register(self, window, persistenceHandler=None)

Register an object with the manager.

Parameters:

• window – an instance of wx.Window;

• persistenceHandler – if not None, this should a custom handler derived from AbstractHandler.

Note

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.

Note

The manager takes ownership of the PersistentObject and will delete it when it is unregistered.

---

RegisterAndRestore(self, window)

Combines both Register and Restore calls.

Parameters:

window – an instance of wx.Window.

---

RegisterAndRestoreAll(self, window, children=None)

Recursively registers and restore the state of the input window and of all of its children.

Parameters:

• window – an instance of wx.Window;

• children – list of children of the input window, on first call it is equal to None.

---

Restore(self, window)

Restores the state of an object.

Parameters:

window – an instance of wx.Window.

Returns:

True if the object properties were restored or False if nothing was found to restore or the saved settings were invalid.

Note

This methods does nothing if DisableRestoring was called.

---

RestoreAll(self, window, children=None)

Recursively restore the state of the input window and of all of its children.

Parameters:

• window – an instance of wx.Window;

• children – list of children of the input window, on first call it is equal to None.

---

RestoreCtrlValue(self, obj, keyName)

Check if we should restore the widget value, if so pass it to DoRestoreValue, this method checks the style PM_PERSIST_CONTROL_VALUE and if if it is not set it will also check the variable persistValue of the individual window.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name.

---

RestoreValue(self, obj, keyName)

Convenience method, all the action is done in DoRestoreValue.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name.

---

Save(self, window)

Saves the state of an object.

Parameters:

window – an instance of wx.Window.

Note

This methods does nothing if DisableSaving was called.

---

SaveAndUnregister(self, window=None)

Combines both Save and Unregister calls.

Parameters:

window – an instance of wx.Window. If it is None, all the windows previously registered are saved and then unregistered.

---

SaveCtrlValue(self, obj, keyName, value)

Check if we persist the widget value, if so pass it to DoSaveValue, this method checks the style PM_PERSIST_CONTROL_VALUE and if it is not set it will also check the variable persistValue of the individual window.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name;

• value – the value to store in the configuration file.

---

SaveValue(self, obj, keyName, value)

Convenience method, all the action is done in DoSaveValue.

Parameters:

• obj – an instance of PersistentObject;

• keyName – a string specifying the key name;

• value – the value to store in the configuration file.

---

SetConfigurationHandler(self, handler)

Sets the persistent configuration handler for PersistenceManager.

Parameters:

handler – an object capable of saving/restoring UI settings. This can be a cPickle object or a ConfigObj one, for example.

Note

UI settings are stored as dictionaries key <=> tuple: the tuple value contains two items. The first is the value type (i.e., float, int, bool etc…) while the second is the actual key value.

---

SetManagerStyle(self, style)

Sets the PersistenceManager style.

Parameters:

style – a combination of the following values:

Flag name	Description
PM_SAVE_RESTORE_AUI_PERSPECTIVES	If a toplevel window has an AUI manager associated, the manager will save and restore its AUI perspective
PM_SAVE_RESTORE_TREE_LIST_SELECTIONS	If set, the manager will save items selections in list and tree controls
PM_PERSIST_CONTROL_VALUE	If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
PM_DEFAULT_STYLE	Same as PM_SAVE_RESTORE_AUI_PERSPECTIVES.

---

SetPersistenceFile(self, fileName)

Sets the persistent configuration file for PersistenceManager.

Parameters:

fileName – the file name where to store the persistent options.

Note

Calling this method has no influence if you are using your own custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc…).

---

SetPersistenceKey(self, key)

Sets the persistent key name inside the configuration file for PersistenceManager.

Parameters:

key – a short meaningful name for your unique preferences key.

Note

Calling this method has no influence if you are using your own custom configuration handler (i.e., by using ConfigObj/ConfigParser/cPickle etc…).

---

Unregister(self, window)

Unregister the object, this is called by PersistenceManager itself so there is usually no need to do it explicitly.

Parameters:

window – an instance of wx.Window, which must have been previously registered with Register.

Note

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.

Note

This deletes the associated PersistentObject.

Properties

HasRestoredProp

This property returns True if any of the windows managed by PersistenceManager has had its settings restored.

Returns:

True if any window was restored, False otherwise.

Added in version 0.9.7.