replace wxDocument::GetPrintableName(wxString&) and wxDocManager::MakeDefaultName(wxString&) with GetUserReadableName() and MakeNewDocumentName() which return wxStrings directly

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

docs/changes.txt

@@ -79,6 +79,9 @@ Deprecated methods and their replacements
   or wxStringBufferLength instead.
 - wxDIRCTRL_SHOW_FILTERS style is deprecated, filters are alwsys shown if
   specified so this style should simply be removed
+- wxDocManager::MakeDefaultName() replaced by MakeNewDocumentName() and
+  wxDocument::GetPrintableName() with GetUserReadableName() which are simpler
+  to use
 
 
 Major new features in this release

docs/latex/wx/docmanag.tex

@@ -320,16 +320,14 @@ The bottom line: if you're not deriving from Initialize, forget it and
 construct wxDocManager with no arguments.
 
 
-\membersection{wxDocManager::MakeDefaultName}\label{wxdocmanagermakedefaultname}
+\membersection{wxDocManager::MakeNewDocumentName}\label{wxdocmanagermakenewdocumentname}
 
-\func{bool}{MakeDefaultName}{\param{const wxString\& }{buf}}
+\func{wxString}{MakeNewDocumentName}{\void}
 
-Copies a suitable default name into {\it buf}. This is implemented by
-appending an integer counter to the string {\bf unnamed} and incrementing
-the counter.
-
-\perlnote{In wxPerl this function must return the modified name rather
-than just modifying the argument.}
+Return a string containing a suitable default name for a new document. By
+default this is implemented by appending an integer counter to the string
+{\bf unnamed} but can be overridden in the derived classes to do something more
+appropriate.
 
 
 \membersection{wxDocManager::OnCreateFileHistory}\label{wxdocmanageroncreatefilehistory}

docs/latex/wx/document.tex

@@ -153,16 +153,13 @@ in many cases a document will only have a single view.
 
 See also: \helpref{GetViews}{wxdocumentgetviews}
 
-\membersection{wxDocument::GetPrintableName}\label{wxdocumentgetprintablename}
+\membersection{wxDocument::GetUserReadableName}\label{wxdocumentgetuserreadablentablename}
 
-\constfunc{virtual void}{GetPrintableName}{\param{wxString\& }{name}}
+\constfunc{virtual wxString}{GetUserReadableName}{\void}
 
-Copies a suitable document name into the supplied {\it name} buffer. The default
-function uses the title, or if there is no title, uses the filename; or if no
-filename, the string {\bf unnamed}. 
-
-\perlnote{In wxPerl this function must return the modified name rather
-than just modifying the argument.}
+Return the document name suitable to be shown to the user. The default
+implementation uses the document title, if any, of the name part of the
+document filename if it was set or, otherwise, the string {\bf unnamed}.
 
 \membersection{wxDocument::GetTitle}\label{wxdocumentgettitle}
 

include/wx/docview.h

@@ -140,8 +140,17 @@ public:
     virtual wxDocTemplate *GetDocumentTemplate() const { return m_documentTemplate; }
     virtual void SetDocumentTemplate(wxDocTemplate *temp) { m_documentTemplate = temp; }
 
-    // Get title, or filename if no title, else [unnamed]
-    virtual bool GetPrintableName(wxString& buf) const;
+    // Get the document name to be shown to the user: the title if there is
+    // any, otherwise the filename if the document was saved and, finally,
+    // "unnamed" otherwise
+    virtual wxString GetUserReadableName() const;
+
+#if WXWIN_COMPATIBILITY_2_8
+    // use GetUserReadableName() instead
+    wxDEPRECATED_BUT_USED_INTERNALLY(
+        virtual bool GetPrintableName(wxString& buf) const
+    );
+#endif // WXWIN_COMPATIBILITY_2_8
 
     // Returns a window that can be used as a parent for document-related
     // dialogs. Override if necessary.
@@ -164,6 +173,9 @@ protected:
     virtual bool DoSaveDocument(const wxString& file);
     virtual bool DoOpenDocument(const wxString& file);
 
+    // the default implementation of GetUserReadableName()
+    wxString DoGetUserReadableName() const;
+
 private:
     DECLARE_ABSTRACT_CLASS(wxDocument)
     DECLARE_NO_COPY_CLASS(wxDocument)
@@ -393,8 +405,9 @@ public:
     wxList& GetDocuments() { return m_docs; }
     wxList& GetTemplates() { return m_templates; }
 
-    // Make a default document name
-    virtual bool MakeDefaultName(wxString& buf);
+    // Return the default name for a new document (by default returns strings
+    // in the form "unnamed <counter>" but can be overridden)
+    virtual wxString MakeNewDocumentName();
 
     // Make a frame title (override this to do something different)
     virtual wxString MakeFrameTitle(wxDocument* doc);
@@ -423,6 +436,13 @@ public:
     // Get the current document manager
     static wxDocManager* GetDocumentManager() { return sm_docManager; }
 
+#if WXWIN_COMPATIBILITY_2_8
+    // deprecated, override GetDefaultName() instead
+    wxDEPRECATED_BUT_USED_INTERNALLY(
+        virtual bool MakeDefaultName(wxString& buf)
+    );
+#endif
+
 #if WXWIN_COMPATIBILITY_2_6
     // deprecated, use GetHistoryFilesCount() instead
     wxDEPRECATED( size_t GetNoHistoryFiles() const );

src/common/docview.cpp

@@ -241,8 +241,7 @@ bool wxDocument::OnNewDocument()
     Modify(false);
     SetDocumentSaved(false);
 
-    wxString name;
-    GetDocumentManager()->MakeDefaultName(name);
+    const wxString name = GetDocumentManager()->MakeNewDocumentName();
     SetTitle(name);
     SetFilename(name, true);
 
@@ -408,23 +407,41 @@ bool wxDocument::Revert()
 
 
 // Get title, or filename if no title, else unnamed
+#if WXWIN_COMPATIBILITY_2_8
 bool wxDocument::GetPrintableName(wxString& buf) const
 {
-    if (!m_documentTitle.empty())
-    {
-        buf = m_documentTitle;
-        return true;
-    }
-    else if (!m_documentFile.empty())
-    {
-        buf = wxFileNameFromPath(m_documentFile);
-        return true;
-    }
-    else
-    {
-        buf = _("unnamed");
-        return true;
-    }
+    // this function can not only be overridden by the user code but also
+    // called by it so we need to ensure that we return the same thing as
+    // GetUserReadableName() but we can't call it because this would result in
+    // an infinite recursion, hence we use the helper DoGetUserReadableName()
+    buf = DoGetUserReadableName();
+
+    return true;
+}
+#endif // WXWIN_COMPATIBILITY_2_8
+
+wxString wxDocument::GetUserReadableName() const
+{
+#if WXWIN_COMPATIBILITY_2_8
+    // we need to call the old virtual function to ensure that the overridden
+    // version of it is still called
+    wxString name;
+    if ( GetPrintableName(name) )
+        return name;
+#endif // WXWIN_COMPATIBILITY_2_8
+
+    return DoGetUserReadableName();
+}
+
+wxString wxDocument::DoGetUserReadableName() const
+{
+    if ( !m_documentTitle.empty() )
+        return m_documentTitle;
+
+    if ( !m_documentFile.empty() )
+        return wxFileNameFromPath(m_documentFile);
+
+    return _("unnamed");
 }
 
 wxWindow *wxDocument::GetDocumentWindow() const
@@ -446,8 +463,7 @@ bool wxDocument::OnSaveModified()
 {
     if (IsModified())
     {
-        wxString title;
-        GetPrintableName(title);
+        wxString title = GetUserReadableName();
 
         wxString msgTitle;
         if (!wxTheApp->GetAppName().empty())
@@ -663,9 +679,7 @@ void wxView::OnChangeFilename()
     wxDocument *doc = GetDocument();
     if (!doc) return;
 
-    wxString name;
-    doc->GetPrintableName(name);
-    win->SetLabel(name);
+    win->SetLabel(doc->GetUserReadableName());
 }
 
 void wxView::SetDocument(wxDocument *doc)
@@ -1404,13 +1418,30 @@ wxDocument *wxDocManager::GetCurrentDocument() const
         return (wxDocument *) NULL;
 }
 
-// Make a default document name
-bool wxDocManager::MakeDefaultName(wxString& name)
+// Make a default name for a new document
+#if WXWIN_COMPATIBILITY_2_8
+bool wxDocManager::MakeDefaultName(wxString& WXUNUSED(name))
 {
-    name.Printf(_("unnamed%d"), m_defaultDocumentNameCounter);
-    m_defaultDocumentNameCounter++;
+    // we consider that this function can only be overridden by the user code,
+    // not called by it as it only makes sense to call it internally, so we
+    // don't bother to return anything from here
+    return false;
+}
+#endif // WXWIN_COMPATIBILITY_2_8
 
-    return true;
+wxString wxDocManager::MakeNewDocumentName()
+{
+    wxString name;
+
+#if WXWIN_COMPATIBILITY_2_8
+    if ( !MakeDefaultName(name) )
+#endif // WXWIN_COMPATIBILITY_2_8
+    {
+        name.Printf(_("unnamed%d"), m_defaultDocumentNameCounter);
+        m_defaultDocumentNameCounter++;
+    }
+
+    return name;
 }
 
 // Make a frame title (override this to do something different)
@@ -1423,8 +1454,7 @@ wxString wxDocManager::MakeFrameTitle(wxDocument* doc)
         title = appName;
     else
     {
-        wxString docName;
-        doc->GetPrintableName(docName);
+        wxString docName = doc->GetUserReadableName();
         title = docName + wxString(_(" - ")) + appName;
     }
     return title;