git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/persistence.h

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: docs/doxygen/overviews/persistence.h
	3	// Purpose: overview of persistent objects
	4	// Author: Vadim Zeitlin
	5	// Created: 2009-01-23
	6	// RCS-ID: $Id$
	7	// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
	8	// Licence: wxWindows license
	9	/////////////////////////////////////////////////////////////////////////////
	10
	11	/**
	12
	13	@page overview_persistence Persistent Objects Overview
	14
	15	Persistent objects are simply the objects which automatically save their state
	16	when they are destroyed and restore it when they are recreated, even during
	17	another program invocation.
	18
	19	Most often, persistent objects are, in fact, persistent windows as it is
	20	especially convenient to automatically restore the UI state when the program is
	21	restarted but an object of any class can be made persistent. Moreover,
	22	persistence is implemented in a non-intrusive way so that the original object
	23	class doesn't need to be modified at all in order to add support for saving and
	24	restoring its properties.
	25
	26	The persistence framework involves
	27	- wxPersistenceManager which all persistent objects register themselves with.
	28	This class handles actual saving and restoring of persistent data as well as
	29	various global aspects of persistence, e.g. it can be used to disable
	30	restoring the saved data.
	31	- wxPersistentObject is the base class for all persistent objects or, rather,
	32	adaptors for the persistent objects as this class main purpose is to provide
	33	the bridge between the original class -- which has no special persistence
	34	support -- and wxPersistenceManager,
	35	- wxPersistentWindow<> which derives from wxPersistentObject and implements some
	36	of its methods using wxWindow-specific functionality. Notably,
	37	wxPersistenceManager handles the destruction of persistent windows
	38	automatically implicitly while it has to be done explicitly for the
	39	arbitrary persistent objects.
	40	- wxCreatePersistentObject() function which is used to create the
	41	appropriate persistence adapter for the object.
	42
	43
	44	@section persistence_using Using Persistent Windows
	45
	46	wxWidgets has built-in support for a (constantly growing) number of controls.
	47	Currently the following classes are supported:
	48	- wxTopLevelWindow (and hence wxFrame and wxDialog)
	49	- wxBookCtrlBase, i.e. wxNotebook, wxListbook, wxToolbook and wxChoicebook
	50	- wxTreebook
	51
	52	To automatically save and restore the properties of the windows of classes
	53	listed above you need to
	54
	55	-# Set a unique name for the window using wxWindow::SetName(): this step is
	56	important as the name is used in the configuration file and so must be
	57	unique among all windows of the same class.
	58	-# Call wxPersistenceManager::Register() at any moment after creating the
	59	window and then wxPersistenceManager::Restore() when the settings may be
	60	restored (which can't be always done immediately, e.g. often the window
	61	needs to be populated first). If settings can be restored immediately after
	62	the window creation, as is often the case for wxTopLevelWindow, for
	63	example, then wxPersistenceManager::RegisterAndRestore() can be used to do
	64	both at once.
	65	-# If you do not want the settings for the window to be saved (for example
	66	the changes to the dialog size are usually not saved if the dialog was
	67	cancelled), you need to call wxPersistenceManager::Unregister() manually.
	68	Otherwise the settings will be automatically saved when the control itself
	69	is destroyed.
	70
	71	Example of using a notebook control which automatically remembers the last open
	72	page:
	73	@code
	74	wxNotebook *book = new wxNotebook(parent, wxID_ANY);
	75	book->SetName("MyBook"); // do not use the default name
	76	book->AddPage(...);
	77	book->AddPage(...);
	78	book->AddPage(...);
	79	if ( !wxPersistenceManager::RegisterAndRestore(book) )
	80	{
	81	// nothing was restored, so choose the default page ourselves
	82	book->SetSelection(0);
	83	}
	84	@endcode
	85
	86
	87	@section persistence_defining Defining Custom Persistent Windows
	88
	89	User-defined classes can be easily integrated with wxPersistenceManager. To add
	90	support for your custom class @c MyWidget you just need to:
	91
	92	-# Define a new @c MyPersistentWidget class inheriting from
	93	wxPersistentWindow<MyWidget>.
	94	-# Implement its pure virtual GetKind() method returning a unique string
	95	identifying all @c MyWidget objects, typically something like @c "widget"
	96	-# Implement its pure virtual Save() and Restore() methods to actually save
	97	and restore the widget settings using wxPersistentObject::SaveValue() and
	98	wxPersistentObject::RestoreValue() methods.
	99	-# Define wxCreatePersistentObject() overload taking @c MyWidget * and
	100	returning a new @c MyPersistentWidget object.
	101
	102	If you want to add persistence support for a class not deriving from wxWindow,
	103	you need to derive @c MyPersistentWidget directly from wxPersistentObject and
	104	so implement its pure virtual wxPersistentObject::GetName() method too.
	105	Additionally, you must ensure that wxPersistenceManager::SaveAndUnregister() is
	106	called when your object is destroyed as this can be only done automatically for
	107	windows.
	108
	109	*/
	110