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

@@ -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

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}

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);

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);

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

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

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;

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"),

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)
 {

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

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

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
 // ----------------------------------------------------------------------------

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
 // ----------------------------------------------------------------------------