Optionally set the window name in wxPersistentRegisterAndRestore().

In practice names are not often used so typically whenever you want to make a
window settings persistent you also need to set its name and the it's
convenient to let a single function do both tasks, so add an overload taking
the name string (this is a separate function instead of optional parameter to
avoid compilation errors if this is ever used with non-wxWindow-derived
objects which don't have SetName() method).

Also expand the documentation slightly and add @since tags.

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

include/wx/persist.h

@@ -239,5 +239,15 @@ inline bool wxPersistentRegisterAndRestore(T *obj)
 
 }
 
+// A helper function which also sets the name for the (wxWindow-derived) object
+// before registering and restoring it.
+template <typename T>
+inline bool wxPersistentRegisterAndRestore(T *obj, const wxString& name)
+{
+    obj->SetName(name);
+
+    return wxPersistentRegisterAndRestore(obj);
+}
+
 #endif // _WX_PERSIST_H_
 

interface/wx/persist.h

@@ -17,6 +17,8 @@
     This is a singleton class and its unique instance can be retrieved using
     Get() method.
 
+    @since 2.9.0
+
     @library{wxcore}
  */
 class wxPersistenceManager
@@ -270,12 +272,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());

samples/widgets/widgets.cpp

@@ -361,8 +361,7 @@ bool WidgetsApp::OnInit()
 WidgetsFrame::WidgetsFrame(const wxString& title)
             : wxFrame(NULL, wxID_ANY, title)
 {
-    SetName("Main");
-    const bool sizeSet = wxPersistentRegisterAndRestore(this);
+    const bool sizeSet = wxPersistentRegisterAndRestore(this, "Main");
 
     // set the frame icon
     SetIcon(wxICON(sample));