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