Allow customization of the locations where persistent settings are stored.

Make it possible to set a non-default wxPersistenceManager to use and allow
overriding of GetConfig() and GetKey() methods by making them virtual and
documenting them.

This can be notably used to allow porting of the existing code to use
wxPersistenceManager while keeping compatibility with the old settings.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@69583 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -488,6 +488,7 @@ All (GUI):
 - Allow wxGraphicsFont creation without passing by wxFont.
 - Added wxDataViewCustomRenderer::ActivateCell().
 - Add "checked" property for toolbar tool elements in XRC.
+- Allow customization of the locations where persistent settings are stored.
 
 OSX:
 

include/wx/persist.h

@@ -44,6 +44,14 @@ wxPersistentObject *wxCreatePersistentObject(T *obj);
 class WXDLLIMPEXP_CORE wxPersistenceManager
 {
 public:
+    // Call this method to specify a non-default persistence manager to use.
+    // This function should usually be called very early to affect creation of
+    // all persistent controls and the object passed to it must have a lifetime
+    // long enough to be still alive when the persistent controls are destroyed
+    // and need it to save their state so typically this would be a global or a
+    // wxApp member.
+    static void Set(wxPersistenceManager& manager);
+
     // accessor to the unique persistence manager object
     static wxPersistenceManager& Get();
 
@@ -133,7 +141,7 @@ public:
 
 #undef wxPERSIST_DECLARE_SAVE_RESTORE_FOR
 
-private:
+protected:
     // ctor is private, use Get()
     wxPersistenceManager()
     {
@@ -142,15 +150,18 @@ private:
     }
 
 
-    // helpers of Save/Restore()
+    // Return the config object to use, by default just the global one but a
-    //
+    // different one could be used by the derived class if needed.
-    // TODO: make this customizable by allowing
+    virtual wxConfigBase *GetConfig() const { return wxConfigBase::Get(); }
-    //          (a) specifying custom wxConfig object to use
+
-    //          (b) allowing to use something else entirely
+    // Return the path to use for saving the setting with the given name for
-    wxConfigBase *GetConfig() const { return wxConfigBase::Get(); }
+    // the specified object (notice that the name is the name of the setting,
-    wxString GetKey(const wxPersistentObject& who, const wxString& name) const;
+    // not the name of the object itself which can be retrieved with GetName()).
+    virtual wxString GetKey(const wxPersistentObject& who,
+                            const wxString& name) const;
 
 
+private:
     // map with the registered objects as keys and associated
     // wxPersistentObjects as values
     wxPersistentObjectsMap m_persistentObjects;

interface/wx/persist.h

@@ -24,8 +24,26 @@
 class wxPersistenceManager
 {
 public:
+    /**
+        Set the global persistence manager to use.
+
+        Call this method to specify a non-default persistence manager to use.
+        It should usually be called very early (e.g. in wxApp-derived class
+        constructor or in the beginning of overridden wxApp::OnInit()) to
+        affect creation of all persistent controls and the object passed to it
+        must have a lifetime long enough to be still alive when the persistent
+        controls are destroyed and need it to save their state so typically
+        this would be a global or a wxApp member.
+
+        @since 2.9.3
+     */
+    static void Set(wxPersistenceManager& manager);
+
     /**
         Returns the unique persistence manager object.
+
+        If Set() hadn't been called before, a default persistence manager
+        implementation is returned.
      */
     static wxPersistenceManager& Get();
 
@@ -142,6 +160,46 @@ public:
 
     bool RegisterAndRestore(void *obj, wxPersistentObject *po);
     //@}
+
+protected:
+    /**
+        Protected default constructor.
+
+        This constructor is only provided for the derived classes, to use an
+        object of this class static Get() method should be called.
+     */
+    wxPersistenceManager();
+
+    /**
+        Return the config object to use.
+
+        By default the global wxConfig, returned by wxConfigBase::Get(), is
+        used but a derived class could override this function to return a
+        different one if necessary.
+
+        @since 2.9.3
+     */
+    virtual wxConfigBase *GetConfig() const;
+
+    /**
+        Return the path to use for saving the setting with the given name for
+        the specified object.
+
+        Notice that the @a name argument is the name of the setting, not the
+        name of the object itself which can be retrieved with its GetName()
+        method.
+
+        This method can be overridden by a derived class to change where in
+        wxConfig the different options are stored. By default, all settings of
+        the persistent controls are stored under "Persistent_Options" group and
+        grouped by control type (e.g. "Window" for top level windows or
+        "Splitter") and name, so that the position of a splitter called "sep"
+        could be stored under "Persistent_Options/Splitter/sep/Position" key.
+
+        @since 2.9.3
+     */
+    virtual wxString GetKey(const wxPersistentObject& who,
+                            const wxString& name) const;
 };
 
 /**

src/common/persist.cpp

@@ -30,16 +30,34 @@
 
 #include "wx/persist.h"
 
+namespace
+{
+
+wxPersistenceManager* gs_manager = NULL;
+
+} // anonymous namespace
+
 // ============================================================================
 // wxPersistenceManager implementation
 // ============================================================================
 
+/* static */
+void wxPersistenceManager::Set(wxPersistenceManager& manager)
+{
+    gs_manager = &manager;
+}
+
 /* static */
 wxPersistenceManager& wxPersistenceManager::Get()
 {
-    static wxPersistenceManager s_manager;
+    if ( !gs_manager )
+    {
+        static wxPersistenceManager s_manager;
 
-    return s_manager;
+        gs_manager = &s_manager;
+    }
+
+    return *gs_manager;
 }
 
 wxPersistenceManager::~wxPersistenceManager()