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