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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
|
.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. currentmodule:: wx.lib.agw.persist.persistencemanager
.. highlight:: python
.. _wx.lib.agw.persist.persistencemanager.PersistenceManager:
==========================================================================================================================================
|phoenix_title| **wx.lib.agw.persist.persistencemanager.PersistenceManager**
==========================================================================================================================================
:class:`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 :ref:`persistent-overview` in the `__init__.py` file for its overview.
This is a singleton class and its unique instance can be retrieved using
:meth:`PersistenceManager.Get() <PersistenceManager.Get>` method.
|
|class_hierarchy| Class Hierarchy
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>PersistenceManager</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.lib.agw.persist.persistencemanager.PersistenceManager_inheritance.png" alt="Inheritance diagram of PersistenceManager" usemap="#dummy" class="inheritance"/></center>
</div>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.persist.persistencemanager.PersistenceManager.html" title="wx.lib.agw.persist.persistencemanager.PersistenceManager" alt="" coords="4,5,403,35"/> </map>
</p>
|
|method_summary| Methods Summary
================================
========================================================================================= ================================================================================
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.__init__` Default class constructor.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.AddBadDefaultName` Adds a name to the ``BAD_DEFAULT_NAMES`` constant.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.DisableRestoring` Globally disables restoring the persistent properties (enabled by default).
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.DisableSaving` Globally disables saving the persistent properties (enabled by default).
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.DoRestoreValue` Method used by the persistent objects to restore the data.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.DoSaveValue` Method used by the persistent objects to save the data.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.EnableRestoring` Globally enables restoring the persistent properties (enabled by default).
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.EnableSaving` Globally enables saving the persistent properties (enabled by default).
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Find` Checks if the object is registered and return the associated :class:`PersistentObject`
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Free` Destructor for the unique persistence manager object.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Get` Accessor to the unique persistence manager object.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetConfigurationHandler` Returns the persistent configuration handler for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetKey` Returns a correctly formatted key name for the object `obj` and `keyName` parameters.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetManagerStyle` Returns the :class:`PersistenceManager` style.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetPersistenceDirectory` Returns a default persistent option directory for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetPersistenceFile` Returns the persistent configuration file for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.GetPersistenceKey` Returns the persistent key name inside the configuration file for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.HasRestored` This method returns ``True`` if any of the windows managed by
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Register` Register an object with the manager.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.RegisterAndRestore` Combines both :meth:`~PersistenceManager.Register` and :meth:`~PersistenceManager.Restore` calls.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.RegisterAndRestoreAll` Recursively registers and restore the state of the input `window` and of
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Restore` Restores the state of an object.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.RestoreAll` Recursively restore the state of the input `window` and of
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.RestoreCtrlValue` Check if we should restore the widget value, if so pass it to :meth:`~PersistenceManager.DoRestoreValue`,
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.RestoreValue` Convenience method, all the action is done in :meth:`~PersistenceManager.DoRestoreValue`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Save` Saves the state of an object.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SaveAndUnregister` Combines both :meth:`~PersistenceManager.Save` and :meth:`~PersistenceManager.Unregister` calls.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SaveCtrlValue` Check if we persist the widget value, if so pass it to :meth:`~PersistenceManager.DoSaveValue`,
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SaveValue` Convenience method, all the action is done in :meth:`~PersistenceManager.DoSaveValue`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SetConfigurationHandler` Sets the persistent configuration handler for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SetManagerStyle` Sets the :class:`PersistenceManager` style.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SetPersistenceFile` Sets the persistent configuration file for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.SetPersistenceKey` Sets the persistent key name inside the configuration file for :class:`PersistenceManager`.
:meth:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.Unregister` Unregister the object, this is called by :class:`PersistenceManager` itself so there is
========================================================================================= ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================= ================================================================================
:attr:`~wx.lib.agw.persist.persistencemanager.PersistenceManager.HasRestoredProp` This property returns ``True`` if any of the windows managed by
================================================================================= ================================================================================
|
|api| Class API
===============
.. class:: PersistenceManager(object)
:class:`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 :ref:`persistent-overview` in the `__init__.py` file for its overview.
This is a singleton class and its unique instance can be retrieved using
:meth:`PersistenceManager.Get() <PersistenceManager.Get>` method.
.. method:: __init__(self)
Default class constructor.
This method should **not** be called directly: you should use the object
obtained by :meth:`PersistenceManager.Get() <PersistenceManager.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 :class:`PersistenceManager`,
a custom file name to which :class:`FileConfig` will access to store and
retrieve UI settings;
- `configKey`: the persistent key name inside the configuration file for
:class:`PersistenceManager`;
- `customConfigHandler`: the persistent configuration handler for :class:`PersistenceManager`;
this attribute is an 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_PERSIST_CONTROL_VALUE`` If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
``PM_DEFAULT_STYLE`` Same as ``PM_SAVE_RESTORE_AUI_PERSPECTIVES``
======================================== ==================================
:note: An individual window can also set the variable `persistValue` to
indicate that its value should be saved/restored even so the style
`PM_PERSIST_CONTROL_VALUE` is not set.
: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.
.. method:: AddBadDefaultName(self, name)
Adds a name to the ``BAD_DEFAULT_NAMES`` constant.
:param `name`: a string specifying the control's default name.
.. method:: DisableRestoring(self)
Globally disables restoring the persistent properties (enabled by default).
:note: By default, restoring properties in :meth:`~PersistenceManager.Restore` is enabled but this
function allows to disable it. This is mostly useful for testing.
.. method:: DisableSaving(self)
Globally disables saving the persistent properties (enabled by default).
:note: By default, saving properties in :meth:`~PersistenceManager.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.
.. method:: DoRestoreValue(self, obj, keyName)
Method used by the persistent objects to restore the data.
By default this method simply use :class:`FileConfig` but this behaviour may be
overridden by passing a custom config handler in the PersistenceManager
constructor.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name.
.. method:: DoSaveValue(self, obj, keyName, value)
Method used by the persistent objects to save the data.
By default this method simply use :class:`FileConfig` but this behaviour may be
overridden by passing a custom configuration handler in the :class:`PersistenceManager`
constructor.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name;
:param `value`: the value to store in the configuration file.
.. method:: EnableRestoring(self)
Globally enables restoring the persistent properties (enabled by default).
:note: By default, restoring properties in :meth:`~PersistenceManager.Restore` is enabled but this
function allows to disable it. This is mostly useful for testing.
.. method:: EnableSaving(self)
Globally enables saving the persistent properties (enabled by default).
:note: By default, saving properties in :meth:`~PersistenceManager.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.
.. method:: Find(self, window)
Checks if the object is registered and return the associated :class:`PersistentObject`
if it is or ``None`` otherwise.
:param `window`: an instance of :class:`wx.Window`.
.. classmethod:: Free(self)
Destructor for the unique persistence manager object.
.. classmethod:: Get(self)
Accessor to the unique persistence manager object.
.. method:: GetConfigurationHandler(self)
Returns the persistent configuration handler for :class:`PersistenceManager`.
.. method:: GetKey(self, obj, keyName)
Returns a correctly formatted key name for the object `obj` and `keyName` parameters.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name.
.. method:: GetManagerStyle(self)
Returns the :class:`PersistenceManager` style.
:see: :meth:`~PersistenceManager.SetManagerStyle` for a list of possible styles.
.. method:: GetPersistenceDirectory(self)
Returns a default persistent option directory for :class:`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 :class:`FileConfig`.
.. method:: GetPersistenceFile(self)
Returns the persistent configuration file for :class:`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...).
.. method:: GetPersistenceKey(self)
Returns the persistent key name inside the configuration file for :class:`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...).
.. method:: HasRestored(self)
This method returns ``True`` if any of the windows managed by
:class:`PersistenceManager` has had its settings restored.
:returns: ``True`` if any window was restored, ``False`` otherwise.
.. versionadded:: 0.9.7
.. method:: Register(self, window, persistenceHandler=None)
Register an object with the manager.
:param `window`: an instance of :class:`wx.Window`;
:param `persistenceHandler`: if not ``None``, this should a custom handler derived
from :class:`~wx.lib.agw.persist.persist_handlers.AbstractHandler`.
.. note::
Note that registering the object doesn't do anything except allowing to call
:meth:`~PersistenceManager.Restore` for it later. If you want to register the object and restore its
properties, use :meth:`~PersistenceManager.RegisterAndRestore`.
.. note::
The manager takes ownership of the :class:`PersistentObject` and will delete it when
it is unregistered.
.. method:: RegisterAndRestore(self, window)
Combines both :meth:`~PersistenceManager.Register` and :meth:`~PersistenceManager.Restore` calls.
:param `window`: an instance of :class:`wx.Window`.
.. method:: RegisterAndRestoreAll(self, window, children=None)
Recursively registers and restore the state of the input `window` and of
all of its children.
:param `window`: an instance of :class:`wx.Window`;
:param `children`: list of children of the input `window`, on first call it is equal to ``None``.
.. method:: Restore(self, window)
Restores the state of an object.
:param `window`: an instance of :class:`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 :meth:`~PersistenceManager.DisableRestoring` was called.
.. method:: RestoreAll(self, window, children=None)
Recursively restore the state of the input `window` and of
all of its children.
:param `window`: an instance of :class:`wx.Window`;
:param `children`: list of children of the input `window`, on first call it is equal to ``None``.
.. method:: RestoreCtrlValue(self, obj, keyName)
Check if we should restore the widget value, if so pass it to :meth:`~PersistenceManager.DoRestoreValue`,
this method checks the style `PM_PERSIST_CONTROL_VALUE` and if if it is
not set it will also check the variable `persistValue` of the individual
window.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name.
.. method:: RestoreValue(self, obj, keyName)
Convenience method, all the action is done in :meth:`~PersistenceManager.DoRestoreValue`.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name.
.. method:: Save(self, window)
Saves the state of an object.
:param `window`: an instance of :class:`wx.Window`.
:note: This methods does nothing if :meth:`~PersistenceManager.DisableSaving` was called.
.. method:: SaveAndUnregister(self, window=None)
Combines both :meth:`~PersistenceManager.Save` and :meth:`~PersistenceManager.Unregister` calls.
:param `window`: an instance of :class:`wx.Window`. If it is ``None``, all the
windows previously registered are saved and then unregistered.
.. method:: SaveCtrlValue(self, obj, keyName, value)
Check if we persist the widget value, if so pass it to :meth:`~PersistenceManager.DoSaveValue`,
this method checks the style `PM_PERSIST_CONTROL_VALUE` and if it is not
set it will also check the variable `persistValue` of the individual
window.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name;
:param `value`: the value to store in the configuration file.
.. method:: SaveValue(self, obj, keyName, value)
Convenience method, all the action is done in :meth:`~PersistenceManager.DoSaveValue`.
:param `obj`: an instance of :class:`PersistentObject`;
:param `keyName`: a string specifying the key name;
:param `value`: the value to store in the configuration file.
.. method:: SetConfigurationHandler(self, handler)
Sets the persistent configuration handler for :class:`PersistenceManager`.
:param `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.
.. method:: SetManagerStyle(self, style)
Sets the :class:`PersistenceManager` style.
:param `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_PERSIST_CONTROL_VALUE`` If set, control values will be persisted. This is handy for e.g. applications using a database, where the data (control value) is persisted in the database and persisting it with PM again would only cause confusion.
``PM_DEFAULT_STYLE`` Same as ``PM_SAVE_RESTORE_AUI_PERSPECTIVES``.
======================================== ==================================
.. method:: SetPersistenceFile(self, fileName)
Sets the persistent configuration file for :class:`PersistenceManager`.
:param `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...).
.. method:: SetPersistenceKey(self, key)
Sets the persistent key name inside the configuration file for :class:`PersistenceManager`.
:param `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...).
.. method:: Unregister(self, window)
Unregister the object, this is called by :class:`PersistenceManager` itself so there is
usually no need to do it explicitly.
:param `window`: an instance of :class:`wx.Window`, which must have been previously
registered with :meth:`~PersistenceManager.Register`.
:note: For the persistent windows this is done automatically (via :meth:`~PersistenceManager.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 :class:`PersistentObject`.
.. attribute:: HasRestoredProp
This property returns ``True`` if any of the windows managed by
:class:`PersistenceManager` has had its settings restored.
:returns: ``True`` if any window was restored, ``False`` otherwise.
.. versionadded:: 0.9.7
|
