]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/persist.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / persist.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/persist.h
3 // Purpose: interface of wxPersistenceManager and related classes
4 // Author: Vadim Zeitlin
5 // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 Provides support for automatically saving and restoring object properties
11 to persistent storage.
12
13 This class is the central element of wxWidgets persistence framework, see
14 @ref overview_persistence for its overview.
15
16 This is a singleton class and its unique instance can be retrieved using
17 Get() method.
18
19 @since 2.9.0
20
21 @library{wxcore}
22 */
23 class wxPersistenceManager
24 {
25 public:
26 /**
27 Set the global persistence manager to use.
28
29 Call this method to specify a non-default persistence manager to use.
30 It should usually be called very early (e.g. in wxApp-derived class
31 constructor or in the beginning of overridden wxApp::OnInit()) to
32 affect creation of all persistent controls and the object passed to it
33 must have a lifetime long enough to be still alive when the persistent
34 controls are destroyed and need it to save their state so typically
35 this would be a global or a wxApp member.
36
37 @since 2.9.3
38 */
39 static void Set(wxPersistenceManager& manager);
40
41 /**
42 Returns the unique persistence manager object.
43
44 If Set() hadn't been called before, a default persistence manager
45 implementation is returned.
46 */
47 static wxPersistenceManager& Get();
48
49 /**
50 Globally disable saving the persistence object properties.
51
52 By default, saving properties in Save() is enabled but the program may
53 wish to disable if, for example, it detects that it is running on a
54 system which shouldn't be modified in any way and so configuration
55 file (or Windows registry) shouldn't be written to.
56
57 @see DisableRestoring()
58 */
59 void DisableSaving();
60
61 /**
62 Globally disable restoring the persistence object properties.
63
64 By default, restoring properties in Restore() is enabled but this
65 function allows to disable it. This is mostly useful for testing.
66
67 @see DisableSaving()
68 */
69 void DisableRestoring();
70
71
72 /**
73 Register an object with the manager automatically creating a
74 persistence adapter for it.
75
76 This is equivalent to calling Register(void *, wxPersistentObject *)
77 with wxCreatePersistentObject(obj) as the second argument.
78
79 @param obj
80 The object to register. wxCreatePersistentObject() overload must be
81 defined for the objects of this class.
82 */
83 template <class T>
84 wxPersistentObject *Register(T *obj);
85
86 /**
87 Register an object with the manager.
88
89 Note that registering the object doesn't do anything except allowing to
90 call Restore() for it later. If you want to register the object and
91 restore its properties, use RegisterAndRestore().
92
93 The manager takes ownership of @a po and will delete it when it is
94 unregistered.
95
96 @param obj
97 The object to register.
98 @param po
99 The wxPersistentObject to use for saving and restoring this object
100 properties.
101 */
102 wxPersistentObject *Register(void *obj, wxPersistentObject *po);
103
104 /**
105 Check if the object is registered and return the associated
106 wxPersistentObject if it is or @NULL otherwise.
107 */
108 wxPersistentObject *Find(void *obj) const;
109
110 /**
111 Unregister the object and delete the associated wxPersistentObject.
112
113 For the persistent windows this is done automatically (via
114 SaveAndUnregister()) when the window is destroyed so you only need to
115 call this function explicitly if you are using custom persistent
116 objects or if you want to prevent the object properties from being
117 saved.
118
119 @param obj
120 An object previously registered with Register().
121 */
122 void Unregister(void *obj);
123
124
125 /**
126 Save the object properties to persistent storage.
127
128 This method does nothing if DisableSaving() had been called.
129
130 @param obj
131 An object previously registered with Register().
132
133 @see SaveAndUnregister()
134 */
135 void Save(void *obj);
136
137 /**
138 Restore the object properties previously saved by Save().
139
140 This method does nothing if DisableRestoring() had been called.
141
142 @param obj
143 An object previously registered with Register().
144 @return
145 @true if the object properties were restored or @false if nothing
146 was found to restore or the saved settings were invalid.
147
148 @see RegisterAndRestore()
149 */
150 bool Restore(void *obj);
151
152 /// Combines both Save() and Unregister() calls.
153 void SaveAndUnregister(void *obj);
154
155 /// Combines both Register() and Restore() calls.
156 //@{
157 template <class T>
158 bool RegisterAndRestore(T *obj);
159
160 bool RegisterAndRestore(void *obj, wxPersistentObject *po);
161 //@}
162
163 protected:
164 /**
165 Protected default constructor.
166
167 This constructor is only provided for the derived classes, to use an
168 object of this class static Get() method should be called.
169 */
170 wxPersistenceManager();
171
172 /**
173 Return the config object to use.
174
175 By default the global wxConfig, returned by wxConfigBase::Get(), is
176 used but a derived class could override this function to return a
177 different one if necessary.
178
179 @since 2.9.3
180 */
181 virtual wxConfigBase *GetConfig() const;
182
183 /**
184 Return the path to use for saving the setting with the given name for
185 the specified object.
186
187 Notice that the @a name argument is the name of the setting, not the
188 name of the object itself which can be retrieved with its GetName()
189 method.
190
191 This method can be overridden by a derived class to change where in
192 wxConfig the different options are stored. By default, all settings of
193 the persistent controls are stored under "Persistent_Options" group and
194 grouped by control type (e.g. "Window" for top level windows or
195 "Splitter") and name, so that the position of a splitter called "sep"
196 could be stored under "Persistent_Options/Splitter/sep/Position" key.
197
198 @since 2.9.3
199 */
200 virtual wxString GetKey(const wxPersistentObject& who,
201 const wxString& name) const;
202 };
203
204 /**
205 Base class for persistent object adapters.
206
207 wxWidgets persistence framework is non-intrusive, i.e. can work with the
208 classes which have no relationship to nor knowledge of it. To allow this,
209 an intermediate persistence adapter is used: this is just a simple object
210 which provides the methods used by wxPersistenceManager to save and restore
211 the object properties and implements them using the concrete class methods.
212
213 You may derive your own classes from wxPersistentObject to implement
214 persistence support for your common classes, see @ref persistence_defining.
215
216 @see wxPersistentWindow<>
217 */
218 class wxPersistentObject
219 {
220 public:
221 /**
222 Constructor takes the object which we're associated with.
223
224 This object must have life-time greater than ours as we keep a pointer
225 to it.
226 */
227 wxPersistentObject(void *obj);
228
229 /// Trivial but virtual destructor.
230 virtual ~wxPersistentObject();
231
232
233 /**
234 @name Methods to be implemented in the derived classes.
235
236 Notice that these methods are only used by wxPersistenceManager
237 normally and shouldn't be called directly.
238 */
239 //@{
240
241 /**
242 Save the object properties.
243
244 The implementation of this method should use SaveValue().
245 */
246 virtual void Save() const = 0;
247
248 /**
249 Restore the object properties.
250
251 The implementation of this method should use RestoreValue().
252 */
253 virtual bool Restore() = 0;
254
255
256 /**
257 Returns the string uniquely identifying the objects supported by this
258 adapter.
259
260 This method is called from SaveValue() and RestoreValue() and normally
261 returns some short (but not too cryptic) strings, e.g. @c "Checkbox".
262 */
263 virtual wxString GetKind() const = 0;
264
265 /**
266 Returns the string uniquely identifying the object we're associated
267 with among all the other objects of the same type.
268
269 This method is used together with GetKind() to construct the unique
270 full name of the object in e.g. a configuration file.
271 */
272 virtual wxString GetName() const = 0;
273
274 //@}
275
276
277 /// Return the associated object.
278 void *GetObject() const;
279
280 protected:
281 /**
282 Save the specified value using the given name.
283
284 @param name
285 The name of the value in the configuration file.
286 @param value
287 The value to save, currently must be a type supported by wxConfig.
288 @return
289 @true if the value was saved or @false if an error occurred.
290 */
291 template <typename T>
292 bool SaveValue(const wxString& name, T value) const;
293
294 /**
295 Restore the value saved by Save().
296
297 @param name
298 The same name as was used by Save().
299 @param value
300 Non-@NULL pointer which will be filled with the value if it was
301 read successfully or not modified if it wasn't.
302 @return
303 @true if the value was successfully read or @false if it was not
304 found or an error occurred.
305 */
306 template <typename T>
307 bool RestoreValue(const wxString& name, T *value);
308 };
309
310 /**
311 Function used to create the correct persistent adapter for the given type
312 of objects.
313
314 To be precise, there is no such template function definition but there are
315 overloads of wxCreatePersistentObject() taking different object types for
316 all wxWidgets classes supporting persistence. And you may also define your
317 own overloads to integrate your custom classes with wxWidgets persistence
318 framework.
319
320 @see @ref persistence_defining
321
322 @header{wx/persist.h}
323 */
324 template <class T>
325 wxPersistentObject *wxCreatePersistentObject(T *obj);
326
327 /**
328 A shorter synonym for wxPersistenceManager::RegisterAndRestore().
329
330 This function simply calls wxPersistenceManager::RegisterAndRestore() but
331 using it results in slightly shorter code as it calls
332 wxPersistenceManager::Get() internally. As an additional convenience, this
333 function can also set the window name.
334
335 For the implementation reasons, this function @em must be used instead of
336 the template method when using Microsoft Visual C++ 6 compiler.
337
338 @param obj wxWindow-derived object to register with persistence manager and
339 to try to restore the settings for.
340 @param name If not empty, @a obj name is changed to the provided value
341 before registering it.
342 @return true if the settings were restored or false otherwise (this will
343 always be the case when the program runs for the first time, for
344 example).
345
346 @since 2.9.0, @a name is new in 2.9.1.
347
348 @header{wx/persist.h}
349 */
350 template <class T>
351 bool wxPersistentRegisterAndRestore(T *obj, const wxString& name = wxString());