interface/wx/persist.h

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