avoid infinite recursion for richtooltops, (hopefully) fixes #15070

[wxWidgets.git] / interface / wx / persist.h

diff --git a/interface/wx/persist.h b/interface/wx/persist.h
index bb0dc58c3197c9f42259494ee265c66b2cc240e2..6a6a1aa13ec5ae5ae1fe9ea5014cef87ecfbec81 100644 (file)
--- a/interface/wx/persist.h
+++ b/interface/wx/persist.h
@@ -4,7 +4,7 @@
 // Author:      Vadim Zeitlin
 // RCS-ID:      $Id$
 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -17,13 +17,33 @@
     This is a singleton class and its unique instance can be retrieved using
     Get() method.
 
+    @since 2.9.0
+
     @library{wxcore}
  */
 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();
 
@@ -37,7 +57,7 @@ public:
 
         @see DisableRestoring()
      */
-    bool DisableSaving();
+    void DisableSaving();
 
     /**
         Globally disable restoring the persistence object properties.
@@ -47,7 +67,7 @@ public:
 
         @see DisableSaving()
      */
-    bool DisableRestoring();
+    void DisableRestoring();
 
 
     /**
@@ -140,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;
 };
 
 /**
@@ -270,12 +330,23 @@ wxPersistentObject *wxCreatePersistentObject(T *obj);
 
     This function simply calls wxPersistenceManager::RegisterAndRestore() but
     using it results in slightly shorter code as it calls
-    wxPersistenceManager::Get() internally.
+    wxPersistenceManager::Get() internally. As an additional convenience, this
+    function can also set the window name.
 
-    For the implementation reasons, this function @em mucst be used instead of
+    For the implementation reasons, this function @em must be used instead of
     the template method when using Microsoft Visual C++ 6 compiler.
 
+    @param obj wxWindow-derived object to register with persistence manager and
+        to try to restore the settings for.
+    @param name If not empty, @a obj name is changed to the provided value
+        before registering it.
+    @return true if the settings were restored or false otherwise (this will
+        always be the case when the program runs for the first time, for
+        example).
+
+    @since 2.9.0, @a name is new in 2.9.1.
+
     @header{wx/persist.h}
  */
 template <class T>
-bool wxPersistentRegisterAndRestore(T *obj);
+bool wxPersistentRegisterAndRestore(T *obj, const wxString& name = wxString());