1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: Persistent Objects Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Persistent Objects Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#persistence_using">Using Persistent Windows</a></li>
<li class="level1"><a href="#persistence_defining">Defining Custom Persistent Windows</a></li>
</ul>
</div>
<div class="textblock"><p>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.</p>
<p>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.</p>
<p>The persistence framework includes the following components:</p>
<ul>
<li><a class="el" href="classwx_persistence_manager.html" title="Provides support for automatically saving and restoring object properties to persistent storage...">wxPersistenceManager</a> 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.</li>
<li><a class="el" href="classwx_persistent_object.html" title="Base class for persistent object adapters.">wxPersistentObject</a> 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 <a class="el" href="classwx_persistence_manager.html" title="Provides support for automatically saving and restoring object properties to persistent storage...">wxPersistenceManager</a>,</li>
<li>wxPersistentWindow<> which derives from <a class="el" href="classwx_persistent_object.html" title="Base class for persistent object adapters.">wxPersistentObject</a> and implements some of its methods using wxWindow-specific functionality. Notably, <a class="el" href="classwx_persistence_manager.html" title="Provides support for automatically saving and restoring object properties to persistent storage...">wxPersistenceManager</a> handles the destruction of persistent windows automatically implicitly while it has to be done explicitly for the arbitrary persistent objects.</li>
<li><a class="el" href="interface_2wx_2persist_2bookctrl_8h.html#a8b21681a5cb6009c8acb05f474ca1899" title="Overload allowing persistence adapter creation for wxBookCtrlBase-derived objects.">wxCreatePersistentObject()</a> function which is used to create the appropriate persistence adapter for the object.</li>
</ul>
<h1><a class="anchor" id="persistence_using"></a>
Using Persistent Windows</h1>
<p>wxWidgets has built-in support for a (constantly growing) number of controls. Currently the following classes are supported:</p>
<ul>
<li><a class="el" href="classwx_top_level_window.html" title="wxTopLevelWindow is a common base class for wxDialog and wxFrame.">wxTopLevelWindow</a> (and hence <a class="el" href="classwx_frame.html" title="A frame is a window whose size and position can (usually) be changed by the user.">wxFrame</a> and <a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a>)</li>
<li><a class="el" href="classwx_book_ctrl_base.html" title="A book control is a convenient way of displaying multiple pages of information, displayed one page at...">wxBookCtrlBase</a> (i.e. <a class="el" href="classwx_notebook.html" title="This class represents a notebook control, which manages multiple windows with associated tabs...">wxNotebook</a>, <a class="el" href="classwx_listbook.html" title="wxListbook is a class similar to wxNotebook but which uses a wxListCtrl to show the labels instead of...">wxListbook</a>, <a class="el" href="classwx_toolbook.html" title="wxToolbook is a class similar to wxNotebook but which uses a wxToolBar to show the labels instead of ...">wxToolbook</a> and <a class="el" href="classwx_choicebook.html" title="wxChoicebook is a class similar to wxNotebook, but uses a wxChoice control to show the labels instead...">wxChoicebook</a>)</li>
<li><a class="el" href="classwx_treebook.html" title="This class is an extension of the wxNotebook class that allows a tree structured set of pages to be s...">wxTreebook</a></li>
</ul>
<p>To automatically save and restore the properties of the windows of classes listed above you need to:</p>
<ol type="1">
<li>Set a unique name for the window using <a class="el" href="classwx_window.html#af80875cda5e1af98dcd7c8e712e3c800" title="Sets the window's name.">wxWindow::SetName()</a>: 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.</li>
<li>Call <a class="el" href="classwx_persistence_manager.html#a0163b3f81fd0187dc35774de09679777" title="Register an object with the manager automatically creating a persistence adapter for it...">wxPersistenceManager::Register()</a> at any moment after creating the window and then <a class="el" href="classwx_persistence_manager.html#a932d8f5cf981aed723f79d1923f67aed" title="Restore the object properties previously saved by Save().">wxPersistenceManager::Restore()</a> 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 <a class="el" href="classwx_top_level_window.html" title="wxTopLevelWindow is a common base class for wxDialog and wxFrame.">wxTopLevelWindow</a>, for example, then <a class="el" href="classwx_persistence_manager.html#a2d90794f76e46b357bcffc01be657f94" title="Combines both Register() and Restore() calls.">wxPersistenceManager::RegisterAndRestore()</a> can be used to do both at once.</li>
<li>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 <a class="el" href="classwx_persistence_manager.html#a453383431eb8f8127f0ac0d8a2cee1c5" title="Unregister the object and delete the associated wxPersistentObject.">wxPersistenceManager::Unregister()</a> manually. Otherwise the settings will be automatically saved when the control itself is destroyed.</li>
</ol>
<p>Example of using a notebook control which automatically remembers the last open page:</p>
<div class="fragment"><div class="line"><a class="code" href="classwx_notebook.html" title="This class represents a notebook control, which manages multiple windows with associated tabs...">wxNotebook</a> *book = <span class="keyword">new</span> <a class="code" href="classwx_notebook.html" title="This class represents a notebook control, which manages multiple windows with associated tabs...">wxNotebook</a>(parent, <a class="code" href="defs_8h.html#ac66d0a09761e7d86b2ac0b2e0c6a8cbba1f375b01ea03a713bbb7e32a36a2589c" title="Any id: means that we don't care about the id, whether when installing an event handler or when creat...">wxID_ANY</a>);</div>
<div class="line">book-><a class="code" href="classwx_window.html#af80875cda5e1af98dcd7c8e712e3c800" title="Sets the window's name.">SetName</a>(<span class="stringliteral">"MyBook"</span>); <span class="comment">// do not use the default name</span></div>
<div class="line">book-><a class="code" href="classwx_book_ctrl_base.html#ab47f8935c3705a452fce7d292d8181dd" title="Adds a new page.">AddPage</a>(...);</div>
<div class="line">book-><a class="code" href="classwx_book_ctrl_base.html#ab47f8935c3705a452fce7d292d8181dd" title="Adds a new page.">AddPage</a>(...);</div>
<div class="line">book-><a class="code" href="classwx_book_ctrl_base.html#ab47f8935c3705a452fce7d292d8181dd" title="Adds a new page.">AddPage</a>(...);</div>
<div class="line"><span class="keywordflow">if</span> ( !<a class="code" href="classwx_persistence_manager.html#a2d90794f76e46b357bcffc01be657f94" title="Combines both Register() and Restore() calls.">wxPersistenceManager::RegisterAndRestore</a>(book) )</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// nothing was restored, so choose the default page ourselves</span></div>
<div class="line"> book-><a class="code" href="classwx_notebook.html#a140d1743bc93c3aff36fe2c9f1cb2bc8" title="Sets the selection to the given page, returning the previous selection.">SetSelection</a>(0);</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="persistence_defining"></a>
Defining Custom Persistent Windows</h1>
<p>User-defined classes can be easily integrated with <a class="el" href="classwx_persistence_manager.html" title="Provides support for automatically saving and restoring object properties to persistent storage...">wxPersistenceManager</a>. To add support for your custom class <code>MyWidget</code> you just need to:</p>
<ol type="1">
<li>Define a new <code>MyPersistentWidget</code> class inheriting from wxPersistentWindow<MyWidget>.</li>
<li>Implement its pure virtual GetKind() method returning a unique string identifying all <code>MyWidget</code> objects, typically something like <code>"widget"</code> </li>
<li>Implement its pure virtual Save() and Restore() methods to actually save and restore the widget settings using <a class="el" href="classwx_persistent_object.html#a0e45b20be1a6b77fe48f49c7232ed212" title="Save the specified value using the given name.">wxPersistentObject::SaveValue()</a> and <a class="el" href="classwx_persistent_object.html#a7dd10ed5914be1d60f9104f0a80bafe5" title="Restore the value saved by Save().">wxPersistentObject::RestoreValue()</a> methods.</li>
<li>Define <a class="el" href="interface_2wx_2persist_2bookctrl_8h.html#a8b21681a5cb6009c8acb05f474ca1899" title="Overload allowing persistence adapter creation for wxBookCtrlBase-derived objects.">wxCreatePersistentObject()</a> overload taking <code>MyWidget</code> * and returning a new <code>MyPersistentWidget</code> object.</li>
</ol>
<p>If you want to add persistence support for a class not deriving from <a class="el" href="classwx_window.html" title="wxWindow is the base class for all windows and represents any visible object on screen.">wxWindow</a>, you need to derive <code>MyPersistentWidget</code> directly from <a class="el" href="classwx_persistent_object.html" title="Base class for persistent object adapters.">wxPersistentObject</a> and so implement its pure virtual <a class="el" href="classwx_persistent_object.html#ae175687a86da6a3d0d6edac12840d7e0" title="Returns the string uniquely identifying the object we're associated with among all the other objects ...">wxPersistentObject::GetName()</a> method too. Additionally, you must ensure that <a class="el" href="classwx_persistence_manager.html#ab8a9b090b5f84df7b6a765fed78d4820" title="Combines both Save() and Unregister() calls.">wxPersistenceManager::SaveAndUnregister()</a> is called when your object is destroyed as this can be only done automatically for windows. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
