PersistenceManager and PersistentObject

This page contains the reference documentation for PersistenceManager and PersistentObject.

This module contains the definitions of PersistentObject and PersistenceManager objects.

Classes

PersistentObject

class persistencemanager.PersistentObject(object)

PersistentObject: ABC for anything persistent.

This is the base class for persistent object adapters. wxPython 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 PersistenceManager to save and restore the object properties and implements them using the concrete class methods.

You may derive your own classes from PersistentObject to implement persistence support for your common classes, see Defining Custom Persistent Windows in the __init__.py file.

__init__(window, persistenceHandler=None)

Default class constructor.

Parameters:
  • window – an instance of wx.Window;
  • persistenceHandler – if not None, this should a custom handler derived from AbstractHandler.
GetKind()

Returns the string uniquely identifying the objects supported by this adapter.

Note

This method is called from SaveValue and RestoreValue and normally returns some short (but not too cryptic) strings, e.g. Checkbox.

GetName()

Returns the string uniquely identifying the window we’re associated with among all the other objects of the same type.

Note

This method is used together with GetKind to construct the unique full name of the object in e.g. a configuration file.

GetWindow()
Returns the actual associated window.
Restore()

Restores the corresponding window settings.

Note

This method shouldn’t be used directly as it doesn’t respect the global PersistenceManager.DisableRestoring settings, use PersistenceManager methods with the same name instead.

RestoreValue(name)

Restore the value saved by Save.

Parameter:name

the same name as was used by Save.

Returns:True if the value was successfully read or False if it was not found or an error occurred.
Save()

Saves the corresponding window settings.

Note

This method shouldn’t be used directly as it doesn’t respect the global PersistenceManager.DisableSaving settings, use PersistenceManager methods with the same name instead.

SaveValue(name, value)

Save the specified value using the given name.

Parameters:
  • name – the name of the value in the configuration file.
  • value – the value to save.
Returns:

True if the value was saved or False if an error occurred.

PersistenceManager

class persistencemanager.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 Objects Overview in the __init__.py file for its overview.

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

__init__()

Default class constructor.

This method should not be called directly: you should use the object obtained by 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 PersistenceManager, a custom file name to which wx.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 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_DEFAULT_STYLE

    Same as PM_SAVE_RESTORE_AUI_PERSPECTIVES

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.

DisableRestoring()

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.

See also

DisableSaving.

DisableSaving()

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.

See also

DisableRestoring.

EnableRestoring()

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.

See also

DisableRestoring.

EnableSaving()

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.

See also

DisableSaving.

Find(window)

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

Parameter:window – an instance of wx.Window.
classmethod Free()
Destructor for the unique persistence manager object.
classmethod Get()
Accessor to the unique persistence manager object.
GetConfigurationHandler()
Returns the persistent configuration handler for PersistenceManager.
GetKey(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()

Returns the PersistenceManager style.

See also

SetManagerStyle for a list of possible styles.

GetPersistenceDirectory()

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 wx.FileConfig.

GetPersistenceFile()

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()

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...).

Register(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 PersistenceManager 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(window)

Combines both Register and Restore calls.

Parameter:window – an instance of wx.Window.

See also

Restore, Register.

Restore(window)

Restores the state of an object.

Parameter: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.

See also

RegisterAndRestore.

RestoreValue(obj, keyName)

Method used by the persistent objects to restore the data.

By default this method simply use wx.FileConfig but this behaviour may be overridden by setting a custom config handler in the SetConfigurationHandler method.

Parameters:
  • obj

    an instance of PersistentObject;

  • keyName – a string specifying the key name.
Save(window)

Saves the state of an object.

Parameter:window – an instance of wx.Window.

Note

This methods does nothing if DisableSaving was called.

See also

SaveAndUnregister.

SaveAndUnregister(window=None)

Combines both Save and Unregister calls.

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

See also

Save, Unregister.

SaveValue(obj, keyName, value)

Method used by the persistent objects to save the data.

By default this method simply use wx.FileConfig but this behaviour may be overridden by setting a custom config handler in the SetConfigurationHandler method.

Parameters:
  • obj

    an instance of PersistentObject;

  • keyName – a string specifying the key name;
  • value – the value to store in the configuration file.
SetConfigurationHandler(handler)

Sets the persistent configuration handler for PersistenceManager.

Parameter: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(style)

Sets the PersistenceManager style.

Parameter: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_DEFAULT_STYLE Same as PM_SAVE_RESTORE_AUI_PERSPECTIVES.

See also

GetManagerStyle.

SetPersistenceFile(fileName)

Sets the persistent configuration file for PersistenceManager.

Parameter: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(key)

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

Parameter: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(window)

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

Parameter: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.

Table Of Contents

Previous topic

Introduction

Next topic

Persistent Handlers

This Page