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());