5
Persistent objects are simply the objects which automatically save their state
6
when they are destroyed and restore it when they are recreated, even during
7
another program invocation.
9
.. _persistent-overview:
11
Persistent Object Overview
12
==========================
14
Most often, persistent objects are, in fact, persistent windows as it is especially
15
convenient to automatically restore the UI state when the program is restarted but
16
an object of any class can be made persistent. Moreover, persistence is implemented
17
in a non-intrusive way so that the original object class doesn't need to be modified
18
at all in order to add support for saving and restoring its properties.
20
The persistence framework involves:
22
* **PersistenceManager** which all persistent objects register themselves with. This class
23
handles actual saving and restoring of persistent data as well as various global
24
aspects of persistence, e.g. it can be used to disable restoring the saved data;
25
* **PersistentObject** is the base class for all persistent objects or, rather, adaptors
26
for the persistent objects as this class main purpose is to provide the bridge between
27
the original class -- which has no special persistence support -- and PersistenceManager;
28
* **PersistentHandlers** which handle different kind of saving/restoring actions depending
32
Using Persistent Windows
33
========================
35
wxPython has built-in support for a (constantly growing) number of controls. Currently the
36
following classes are supported:
38
* wx.TopLevelWindow (and hence wx.Frame and wx.Dialog, together with their own AUI perspectives);
39
* wx.MenuBar, L{flatmenu.FlatMenuBar};
40
* L{auibar.AuiToolBar};
41
* wx.Notebook, wx.Toolbook, wx.Treebook, wx.Choicebook, wx.aui.AuiNotebook,
42
L{auibook.AuiNotebook} (together with its own AUI perspective),
43
L{flatnotebook.FlatNotebook}, L{labelbook.LabelBook},
44
L{labelbook.FlatImageBook};
46
* wx.ListBox, wx.VListBox, wx.HtmlListBox, wx.SimpleHtmlListBox, wx.gizmos.EditableListBox;
47
* wx.ListCtrl, wx.ListView;
49
* wx.Choice, wx.ComboBox, wx.combo.OwnerDrawnComboBox;
52
* wx.ScrolledWindow, wx.lib.scrolledpanel.ScrolledPanel;
53
* wx.Slider, L{knobctrl.KnobCtrl};
54
* wx.SpinButton, wx.SpinCtrl, L{floatspin.FloatSpin};
56
* wx.TextCtrl, wx.SearchCtrl, wx.lib.expando.ExpandoTextCtrl, wx.lib.masked.Ctrl;
57
* wx.ToggleButton, wx.lib.buttons.GenToggleButton, wx.lib.buttons.GenBitmapToggleButton,
58
wx.lib.buttons.GenBitmapTextToggleButton, L{shapedbutton.SToggleButton},
59
L{shapedbutton.SBitmapToggleButton}, L{shapedbutton.SBitmapTextToggleButton};
60
* wx.TreeCtrl, wx.GenericDirCtrl, L{customtreectrl.CustomTreeCtrl};
61
* wx.gizmos.TreeListCtrl, L{hypertreelist.HyperTreeList};
62
* wx.lib.calendar.CalendarCtrl;
64
* wx.DatePickerCtrl, wx.GenericDatePickerCtrl;
66
* wx.ColourPickerCtrl, wx.lib.colourselect.ColourSelect;
67
* wx.FilePickerCtrl, wx.DirPickerCtrl;
70
* wx.DirDialog, wx.FileDialog;
71
* wx.FindReplaceDialog;
73
* wx.ColourDialog, L{cubecolourdialog.CubeColourDialog};
74
* L{foldpanelbar.FoldPanelBar};
75
* wx.SingleChoiceDialog, wx.MultiChoiceDialog;
76
* wx.TextEntryDialog, wx.PasswordEntryDialog.
79
To automatically save and restore the properties of the windows of classes listed
82
* Set a unique name for the window using `SetName()`: this step is important as the
83
name is used in the configuration file and so must be unique among all windows of
85
* Call `PersistenceManager.Register(window)` at any moment after creating the window
86
and then `PersistenceManager.Restore(window)` when the settings may be restored
87
(which can't be always done immediately, e.g. often the window needs to be populated
88
first). If settings can be restored immediately after the window creation, as is often
89
the case for wx.TopLevelWindow, for example, then `PersistenceManager.RegisterAndRestore(window)`
90
can be used to do both at once.
91
* If you want the settings for the window to be saved when your main frame is destroyed (or your app closes), simply call
92
`PersistenceManager.SaveAndUnregister(window)` with no arguments.
98
Example of using a notebook control which automatically remembers the last open page::
100
book = wx.Notebook(parent, wx.ID_ANY)
101
book.SetName("MyBook") # Do not use the default name!!
106
if not PersistenceManager.RegisterAndRestore(book):
107
# Nothing was restored, so choose the default page ourselves
111
.. _persistent-windows:
113
Defining Custom Persistent Windows
114
==================================
116
User-defined classes can be easily integrated with PersistenceManager. To add support
117
for your custom class MyWidget you just need to:
119
* Define a MyWidgetHandler class inheriting from `AbstractHandler`;
120
* Implement its `GetKind()` method returning a unique string identifying all MyWidget
121
objects, typically something like "widget";
122
* Implement its `Save()` and `Restore()` methods to actually save and restore the widget
123
settings using `PersistentObject.SaveValue()` and `PersistentObject.RestoreValue()` methods.
125
If you want to add persistence support for a class not deriving from wx.Window, you need
126
to derive MyPersistentWidget directly from PersistentObject and so implement its
127
`PersistentObject.GetName()` method too. Additionally, you must ensure that
128
`PersistenceManager.SaveAndUnregister()` is called when your object is destroyed as this
129
can be only done automatically for windows.
135
* Find a way to handle `wx.ToolBar` UI settings as it has been done for L{auibar.AuiToolBar}:
136
current `wx.ToolBar` doesn't seem to have easy access to the underlying toolbar tools;
137
* Implement handler(s) for `wx.grid.Grid` for row/columns sizes (possibly adding another style
138
to `PersistenceManager` as `wx.grid.Grid` sets up arrays to store individual row and column
139
sizes when non-default sizes are used. The memory requirements for this could become prohibitive
140
if the grid is very large);
141
* Find a way to properly save and restore dialog data (`wx.ColourDialog`, `wx.FontDialog` etc...);
142
* Add handlers for the remaining widgets not yet wrapped (mostly in `wx.lib`).
148
PersistentObjects library is distributed under the wxPython license.
150
Latest revision: Andrea Gavana @ 28 Jan 2011, 15.00 GMT
155
__author__ = "Andrea Gavana <andrea.gavana@gmail.com>"
156
__date__ = "16 November 2009"
159
from persist_constants import *
160
from persistencemanager import *
161
from persist_handlers import *
added
removed
wxPython/wx/lib/agw/persist/__init__.py
