| Version: 3.3.1

Persistent Objects Overview

Persistent objects are simply the objects which automatically save their state when they are destroyed and restore it when they are recreated, even during another program invocation.

Most often, persistent objects are, in fact, persistent windows as it is especially convenient to automatically restore the UI state when the program is restarted but an object of any class can be made persistent. Moreover, persistence is implemented in a non-intrusive way so that the original object class doesn't need to be modified at all in order to add support for saving and restoring its properties.

The persistence framework includes the following components:

- wxPersistenceManager which all persistent objects register themselves with. This class handles actual saving and restoring of persistent data as well as various global aspects of persistence, e.g. it can be used to disable restoring the saved data.
- wxPersistentObject is the base class for all persistent objects or, rather, adaptors for the persistent objects as this class main purpose is to provide the bridge between the original class – which has no special persistence support – and wxPersistenceManager,
- wxPersistentWindow<> which derives from wxPersistentObject and implements some of its methods using wxWindow-specific functionality. Notably, wxPersistenceManager handles the destruction of persistent windows automatically implicitly while it has to be done explicitly for the arbitrary persistent objects.
- wxCreatePersistentObject() function which is used to create the appropriate persistence adapter for the object.

# Using Persistent Windows

wxWidgets has built-in support for a (constantly growing) number of controls. Currently the following classes are supported:

- wxTopLevelWindow (and hence wxFrame and wxDialog), see wxPersistentTLW.
- wxBookCtrlBase (i.e. wxNotebook, wxListbook, wxToolbook and wxChoicebook), see wxPersistentBookCtrl and wxPersistentTreeBookCtrl.
- wxDataViewCtrl (and derivatives such as wxDataViewListCtrl), see wxPersistentDataViewCtrl.
- wxCheckBox, see wxPersistentCheckBox.
- wxComboBox, see wxPersistentComboBox.
- wxRadioButton, see wxPersistentRadioButton.

To automatically save and restore the properties of the windows of classes listed above you need to:

1. Set a unique name for the window by either using this name in its constructor or calling wxWindow::SetName(): this step is important as the name is used in the configuration file and so must be unique among all windows of the same class.
2. Call wxPersistenceManager::Register() at any moment after creating the window and then wxPersistenceManager::Restore() when the settings may be restored (which can't be always done immediately, e.g. often the window needs to be populated first). If settings can be restored immediately after the window creation, as is often the case for wxTopLevelWindow, for example, then wxPersistenceManager::RegisterAndRestore() can be used to do both at once.
3. If you do not want the settings for the window to be saved (for example the changes to the dialog size are usually not saved if the dialog was cancelled), you need to call wxPersistenceManager::Unregister() manually. Otherwise the settings will be automatically saved when the control itself is destroyed.

A convenient wxPersistentRegisterAndRestore() helper function can be used to perform the first steps at once, e.g. to automatically save and restore the position of a `MyFrame` window in your application, you need to only do the following:

#include <wx/persist/toplevel.h>
...
MyFrame::MyFrame(wxWindow* parent, ...)
: wxFrame(parent, ...)
{
... all the other initialization ...
// Restore the previously saved geometry, if any, and register this frame
// for its geometry to be saved when it is closed using the given wxConfig
// key name.
if ( !wxPersistentRegisterAndRestore(this, "my_frame_name") )
{
// Choose some custom default size for the first run -- or don't do
// anything at all and let the system use the default initial size.
SetClientSize(FromDIP(wxSize(800, 600)));
}
Show(true);
}
wxFrame
A frame is a window whose size and position can (usually) be changed by the user.
Definition: frame.h:166
wxSize
A wxSize is a useful data structure for graphics operations.
Definition: gdicmn.h:1039
wxWindow
wxWindow is the base class for all windows and represents any visible object on screen.
Definition: window.h:353
toplevel.h
wxPersistentRegisterAndRestore
bool wxPersistentRegisterAndRestore(T *obj, const wxString &name=wxString())
A shorter synonym for wxPersistenceManager::RegisterAndRestore().

And here is an example of using a notebook control which automatically remembers the last open page without using the helper function:

wxNotebook *book = new wxNotebook(parent, wxID_ANY);
book->SetName("MyBook"); // do not use the default name
book->AddPage(...);
book->AddPage(...);
book->AddPage(...);
// We don't check for the return value here as the first page is selected
// by default anyhow and we just keep this selection in this case.
wxPersistenceManager::Get().RegisterAndRestore(book);
wxBookCtrlBase::AddPage
virtual bool AddPage(wxWindow *page, const wxString &text, bool select=false, int imageId=NO_IMAGE)
Adds a new page.
wxNotebook
This class represents a notebook control, which manages multiple windows with associated tabs.
Definition: notebook.h:114
wxPersistenceManager::Get
static wxPersistenceManager & Get()
Returns the unique persistence manager object.
wxPersistenceManager::RegisterAndRestore
bool RegisterAndRestore(T *obj)
Combines both Register() and Restore() calls.
wxWindow::SetName
virtual void SetName(const wxString &name)
Sets the window's name.
wxID_ANY
@ wxID_ANY
Any id: means that we don't care about the id, whether when installing an event handler or when creat...
Definition: defs.h:591

# Defining Custom Persistent Windows

User-defined classes can be easily integrated with wxPersistenceManager. To add support for your custom class `MyWidget` you just need to:

1. Define a new `MyPersistentWidget` class inheriting from `wxPersistentWindow<MyWidget>`.
2. Implement its pure virtual GetKind() method returning a unique string identifying all `MyWidget` objects, typically something like `"widget"`
3. Implement its pure virtual Save() and Restore() methods to actually save and restore the widget settings using wxPersistentObject::SaveValue() and wxPersistentObject::RestoreValue() methods.
4. Define wxCreatePersistentObject() overload taking `MyWidget*` and returning a new `MyPersistentWidget` object.

If you want to add persistence support for a class not deriving from wxWindow, you need to derive `MyPersistentWidget` directly from wxPersistentObject and so implement its pure virtual wxPersistentObject::GetName() method too. Additionally, you must ensure that wxPersistenceManager::SaveAndUnregister() is called when your object is destroyed as this can be only done automatically for windows.