From 17af82fb4c8f830f202567259472645c27724c32 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Mon, 17 Apr 2006 01:12:04 +0000
Subject: [PATCH] added wxStandardPaths::GetDocumentsDir() (patch 1214360)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@38777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/changes.txt                         |  1 +
 docs/latex/wx/stdpaths.tex               | 14 ++++++++++++++
 include/wx/mac/carbon/private.h          |  3 +++
 include/wx/mac/classic/private.h         |  3 +++
 include/wx/mac/corefoundation/stdpaths.h |  1 +
 include/wx/msw/stdpaths.h                |  1 +
 include/wx/stdpaths.h                    |  7 +++++++
 samples/console/console.cpp              |  1 +
 src/common/stdpbase.cpp                  |  5 +++++
 src/mac/carbon/utils.cpp                 | 13 +++++++++++--
 src/mac/classic/utils.cpp                | 11 +++++++++--
 src/mac/corefoundation/stdpaths_cf.cpp   | 15 +++++++++++++++
 src/msw/stdpaths.cpp                     | 10 +++++++++-
 13 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/docs/changes.txt b/docs/changes.txt
index 01d4dbd982..b180989118 100644
--- a/docs/changes.txt
+++ b/docs/changes.txt
@@ -40,6 +40,7 @@ All:
 - Many fixes for UTF-16/32 handling in Unicode builds
 - wxLaunchDefaultBrowser() now supports wxBROWSER_NEW_WINDOW flag.
 - Added wxStandardPaths::GetResourcesDir() and GetLocalizedResourcesDir()
+- Added wxStandardPaths::GetDocumentsDir() (Ken Thomases)
 - Added wxStringTokenizer::GetLastDelimiter(); improved documentation.
 - Fixed wxTextFile in Unicode build
 - Speed improvements to wxRegEx when matching is done in a loop such as
diff --git a/docs/latex/wx/stdpaths.tex b/docs/latex/wx/stdpaths.tex
index 172c14cdc9..c765bca647 100644
--- a/docs/latex/wx/stdpaths.tex
+++ b/docs/latex/wx/stdpaths.tex
@@ -95,6 +95,20 @@ Example return values:
 \helpref{GetLocalDataDir}{wxstandardpathsgetlocaldatadir}
 
 
+\membersection{wxStandardPaths::GetDocumentsDir}\label{wxstandardpathsgetdocumentsdir}
+
+\func{wxString}{GetDocumentsDir}{\void}
+
+Return the directory containing the current user's documents.
+
+Example return values:
+\begin{itemize}
+    \item Unix: \tt{~} (the home directory)
+    \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Documents}
+    \item Mac: \texttt{~/Documents}
+\end{itemize}
+
+
 \membersection{wxStandardPaths::GetInstallPrefix}\label{wxstandardpathsgetinstallprefix}
 
 \func{wxString}{GetInstallPrefix}{\void}
diff --git a/include/wx/mac/carbon/private.h b/include/wx/mac/carbon/private.h
index 703ad07254..c8a9c67893 100644
--- a/include/wx/mac/carbon/private.h
+++ b/include/wx/mac/carbon/private.h
@@ -196,6 +196,9 @@ WXDLLEXPORT wxString wxMacFSSpec2MacFilename( const FSSpec *spec ) ;
 WXDLLEXPORT void wxMacFilename2FSSpec( const wxString &path , FSSpec *spec ) ;
 
 // utils.h
+WXDLLEXPORT wxString wxMacFindFolderNoSeparator(short vRefNum,
+                                                OSType folderType,
+                                                Boolean createFolder);
 WXDLLEXPORT wxString wxMacFindFolder(short vRefNum,
                                      OSType folderType,
                                      Boolean createFolder);
diff --git a/include/wx/mac/classic/private.h b/include/wx/mac/classic/private.h
index f16a72067e..d2c1c6986d 100644
--- a/include/wx/mac/classic/private.h
+++ b/include/wx/mac/classic/private.h
@@ -124,6 +124,9 @@ WXDLLEXPORT wxString wxUnix2MacFilename( const wxChar *s);
 #  endif
 
 // utils.h
+WXDLLEXPORT wxString wxMacFindFolderNoSeparator(short vRefNum,
+                                                OSType folderType,
+                                                Boolean createFolder);
 WXDLLEXPORT wxString wxMacFindFolder(short vRefNum,
                                      OSType folderType,
                                      Boolean createFolder);
diff --git a/include/wx/mac/corefoundation/stdpaths.h b/include/wx/mac/corefoundation/stdpaths.h
index 00b1ffbdf7..a73ca4b514 100644
--- a/include/wx/mac/corefoundation/stdpaths.h
+++ b/include/wx/mac/corefoundation/stdpaths.h
@@ -42,6 +42,7 @@ public:
     virtual wxString GetResourcesDir() const;
     virtual wxString GetLocalizedResourcesDir(const wxChar *lang,
                                               ResourceCat category) const;
+    virtual wxString GetDocumentsDir() const;
 
 protected:
     // this function can be called with any of CFBundleCopyXXXURL function
diff --git a/include/wx/msw/stdpaths.h b/include/wx/msw/stdpaths.h
index 5273872dce..56bae840f5 100644
--- a/include/wx/msw/stdpaths.h
+++ b/include/wx/msw/stdpaths.h
@@ -26,6 +26,7 @@ public:
     virtual wxString GetUserDataDir() const;
     virtual wxString GetUserLocalDataDir() const;
     virtual wxString GetPluginsDir() const;
+    virtual wxString GetDocumentsDir() const;
 
 protected:
     // get the path corresponding to the given standard CSIDL_XXX constant
diff --git a/include/wx/stdpaths.h b/include/wx/stdpaths.h
index b3b54d4106..1be4077d65 100644
--- a/include/wx/stdpaths.h
+++ b/include/wx/stdpaths.h
@@ -111,6 +111,12 @@ public:
         return GetResourcesDir() + wxFILE_SEP_PATH + lang;
     }
 
+    // return the "Documents" directory for the current user
+    //
+    // C:\Documents and Settings\username\Documents under Windows,
+    // $HOME under Unix and ~/Documents under Mac
+    virtual wxString GetDocumentsDir() const;
+
 
     // virtual dtor for the base class
     virtual ~wxStandardPathsBase();
@@ -149,6 +155,7 @@ public:
     virtual wxString GetLocalDataDir() const { return m_prefix; }
     virtual wxString GetUserDataDir() const { return m_prefix; }
     virtual wxString GetPluginsDir() const { return m_prefix; }
+    virtual wxString GetDocumentsDir() const { return m_prefix; }
 
 private:
     wxString m_prefix;
diff --git a/samples/console/console.cpp b/samples/console/console.cpp
index 06662dde58..14e781d047 100644
--- a/samples/console/console.cpp
+++ b/samples/console/console.cpp
@@ -2684,6 +2684,7 @@ static void TestStandardPaths()
     wxPrintf(_T("Data dir (sys local):\t%s\n"), stdp.GetLocalDataDir().c_str());
     wxPrintf(_T("Data dir (user):\t%s\n"), stdp.GetUserDataDir().c_str());
     wxPrintf(_T("Data dir (user local):\t%s\n"), stdp.GetUserLocalDataDir().c_str());
+    wxPrintf(_T("Documents dir:\t\t%s\n"), stdp.GetDocumentsDir().c_str());
     wxPrintf(_T("Plugins dir:\t\t%s\n"), stdp.GetPluginsDir().c_str());
     wxPrintf(_T("Resources dir:\t\t%s\n"), stdp.GetResourcesDir().c_str());
     wxPrintf(_T("Localized res. dir:\t%s\n"),
diff --git a/src/common/stdpbase.cpp b/src/common/stdpbase.cpp
index 6f9bba7c97..18ad257b92 100644
--- a/src/common/stdpbase.cpp
+++ b/src/common/stdpbase.cpp
@@ -73,6 +73,11 @@ wxString wxStandardPathsBase::GetUserLocalDataDir() const
     return GetUserDataDir();
 }
 
+wxString wxStandardPathsBase::GetDocumentsDir() const
+{
+    return wxFileName::GetHomeDir();
+}
+
 /* static */
 wxString wxStandardPathsBase::AppendAppName(const wxString& dir)
 {
diff --git a/src/mac/carbon/utils.cpp b/src/mac/carbon/utils.cpp
index 5cb7a352f9..9c22b95818 100644
--- a/src/mac/carbon/utils.cpp
+++ b/src/mac/carbon/utils.cpp
@@ -521,7 +521,7 @@ bool wxIsBusy()
 
 #if wxUSE_BASE
 
-wxString wxMacFindFolder( short        vol,
+wxString wxMacFindFolderNoSeparator( short        vol,
               OSType       folderType,
               Boolean      createFolder)
 {
@@ -529,11 +529,20 @@ wxString wxMacFindFolder( short        vol,
     wxString strDir ;
 
     if ( FSFindFolder( vol, folderType, createFolder, &fsRef) == noErr)
-        strDir = wxMacFSRefToPath( &fsRef ) + wxFILE_SEP_PATH ;
+    {
+        strDir = wxMacFSRefToPath( &fsRef );
+    }
 
     return strDir ;
 }
 
+wxString wxMacFindFolder( short        vol,
+              OSType       folderType,
+              Boolean      createFolder)
+{
+    return wxMacFindFolderNoSeparator(vol, folderType, createFolder) + wxFILE_SEP_PATH;
+}
+
 #endif // wxUSE_BASE
 
 #if wxUSE_GUI
diff --git a/src/mac/classic/utils.cpp b/src/mac/classic/utils.cpp
index 78cbfd0da7..f5a8ff1bd5 100644
--- a/src/mac/classic/utils.cpp
+++ b/src/mac/classic/utils.cpp
@@ -372,7 +372,7 @@ bool wxIsBusy()
 
 #if wxUSE_BASE
 
-wxString wxMacFindFolder( short        vol,
+wxString wxMacFindFolderNoSeparator( short        vol,
               OSType       folderType,
               Boolean      createFolder)
 {
@@ -385,12 +385,19 @@ wxString wxMacFindFolder( short        vol,
         FSSpec file ;
         if ( FSMakeFSSpec( vRefNum , dirID , "\p" , &file ) == noErr )
         {
-            strDir = wxMacFSSpec2MacFilename( &file ) + wxFILE_SEP_PATH ;
+            strDir = wxMacFSSpec2MacFilename( &file );
         }
     }
     return strDir ;
 }
 
+wxString wxMacFindFolder( short        vol,
+              OSType       folderType,
+              Boolean      createFolder)
+{
+    return wxMacFindFolderNoSeparator(vol, folderType, createFolder) + wxFILE_SEP_PATH;
+}
+
 #endif // wxUSE_BASE
 
 #if wxUSE_GUI
diff --git a/src/mac/corefoundation/stdpaths_cf.cpp b/src/mac/corefoundation/stdpaths_cf.cpp
index eb6e0367bf..2b2cf9cba0 100644
--- a/src/mac/corefoundation/stdpaths_cf.cpp
+++ b/src/mac/corefoundation/stdpaths_cf.cpp
@@ -31,6 +31,7 @@
 #include "wx/mac/private.h"
 #endif
 #include "wx/mac/corefoundation/cfstring.h"
+#include "wx/mac/private.h"
 
 #if defined(__DARWIN__)
 #include <CoreFoundation/CFBundle.h>
@@ -106,6 +107,20 @@ wxString wxStandardPathsCF::GetFromFunc(wxCFURLRef (*func)(wxCFBundleRef)) const
     return ret;
 }
 
+wxString wxStandardPathsCF::GetDocumentsDir() const
+{
+    return wxMacFindFolderNoSeparator
+        (
+#if TARGET_API_MAC_OSX
+        kUserDomain,
+#else
+        kOnSystemDisk,
+#endif
+        kDocumentsFolderType,
+        kCreateFolder
+        );
+}
+
 // ----------------------------------------------------------------------------
 // wxStandardPathsCF public API
 // ----------------------------------------------------------------------------
diff --git a/src/msw/stdpaths.cpp b/src/msw/stdpaths.cpp
index 5e9de59ee3..7eef3af3a0 100644
--- a/src/msw/stdpaths.cpp
+++ b/src/msw/stdpaths.cpp
@@ -68,6 +68,10 @@ static const wxChar *TRACE_MASK = _T("stdpaths");
     #define CSIDL_PROGRAM_FILES   0x0026
 #endif
 
+#ifndef CSIDL_PERSONAL
+    #define CSIDL_PERSONAL        0x0005
+#endif
+
 #ifndef SHGFP_TYPE_CURRENT
     #define SHGFP_TYPE_CURRENT 0
 #endif
@@ -75,7 +79,6 @@ static const wxChar *TRACE_MASK = _T("stdpaths");
 #ifndef SHGFP_TYPE_DEFAULT
     #define SHGFP_TYPE_DEFAULT 1
 #endif
-
 // ----------------------------------------------------------------------------
 // module globals
 // ----------------------------------------------------------------------------
@@ -262,6 +265,11 @@ wxString wxStandardPaths::GetAppDir()
     return fn.GetPath();
 }
 
+wxString wxStandardPaths::GetDocumentsDir() const
+{
+    return DoGetDirectory(CSIDL_PERSONAL);
+}
+
 // ----------------------------------------------------------------------------
 // public functions
 // ----------------------------------------------------------------------------
-- 
2.50.0

