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