From 48713afd53264562b36b3ce574872555a1898b66 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Mon, 18 Oct 2004 23:27:37 +0000 Subject: [PATCH] - added and documented Get/SetInstallPath() under Unix - corrected returns values of several functions for Mac OS X git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@29979 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/stdpaths.tex | 89 +++++++++++++++++++++++++------------- include/wx/stdpaths.h | 25 +++++++++-- 2 files changed, 80 insertions(+), 34 deletions(-) diff --git a/docs/latex/wx/stdpaths.tex b/docs/latex/wx/stdpaths.tex index 02a9d968eb..f4f7ce4cf2 100644 --- a/docs/latex/wx/stdpaths.tex +++ b/docs/latex/wx/stdpaths.tex @@ -9,7 +9,7 @@ %% License: wxWidgets license %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{\class{wxStandardPaths}}\label{wxstandardsaths} +\section{\class{wxStandardPaths}}\label{wxstandardpaths} wxStandardPaths returns the standard locations in the file system and should be used by the programs to find their data files in a portable way. @@ -20,27 +20,25 @@ so to use wxStandardPaths simply call its methods directly. In the description of the methods below, the example return values are given for the Unix, Windows and Mac OS X systems, however please note that these are -just the examples and the actual values may differ. Most importantly: -\begin{itemize} - \item Unix: \texttt{/usr} should in general be replaced by the - program installation prefix which is by default \texttt{/usr/local} but - may be any other path as well. - \item Windows: the system administrator may change the standard - directories locations, i.e. the Windows directory may be named - \texttt{W:$\backslash$Win2003} instead of default - \texttt{C:$\backslash$Windows} -\end{itemize} +just the examples and the actual values may differ. For example, under Windows: +the system administrator may change the standard directories locations, i.e. +the Windows directory may be named \texttt{W:$\backslash$Win2003} instead of +the default \texttt{C:$\backslash$Windows}. The strings \texttt{\textit{appname}} and \texttt{\textit{username}} should be replaced with the value returned by \helpref{wxApp::GetAppName}{wxappgetappname} -and the name of the currently logged in user, respectively. +and the name of the currently logged in user, respectively. The string +\texttt{\textit{prefix}} is only used under Unix and is \texttt{/usr/local} by +default but may be changed using \helpref{SetInstallPrefix}{wxstandardpathssetinstallprefix}. The directories returned by the methods of this class may or may not exist. If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't do it. -Finally note that under Mac, these functions only work for the bundled -applications. +Finally note that these functions only work with standardly packaged +applications. I.e. under Unix you should follow the standard installation +conventions and under Mac you should create your application bundle according +to the Apple guidelines. Again, this class doesn't help you to do it. \wxheading{Derived from} @@ -54,7 +52,7 @@ No base class \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardsathsgetconfigdir} +\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardpathsgetconfigdir} \func{static wxString}{GetConfigDir}{\void} @@ -72,7 +70,7 @@ Example return values: \helpref{wxFileConfig}{wxfileconfig} -\membersection{wxStandardPaths::GetDataDir}\label{wxstandardsathsgetdatadir} +\membersection{wxStandardPaths::GetDataDir}\label{wxstandardpathsgetdatadir} \func{static wxString}{GetDataDir}{\void} @@ -81,28 +79,43 @@ data files. Example return values: \begin{itemize} - \item Unix: \texttt{/usr/share/\textit{appname}} + \item Unix: \texttt{\textit{prefix}/share/\textit{appname}} \item Windows: \texttt{C:$\backslash$Program Files$\backslash$\textit{appname}} - \item Mac: \texttt{\textit{appname}.app/Contents} bundle subdirectory + \item Mac: \texttt{\textit{appname}.app/Contents/SharedSupport} bundle subdirectory \end{itemize} \wxheading{See also} -\helpref{GetLocalDataDir}{wxstandardsathsgetlocaldatadir} +\helpref{GetLocalDataDir}{wxstandardpathsgetlocaldatadir} + + +\membersection{wxStandardPaths::GetInstallPrefix}\label{wxstandardpathsgetinstallprefix} + +\func{static wxString}{GetInstallPrefix}{\void} + +\textbf{Note: } This function is only available under Unix. + +Return the program installation prefix, e.g. \texttt{/usr}, \texttt{/opt} or +\texttt{/home/zeitlin}. +If the prefix had been previously by +\helpref{SetInstallPrefix}{wxstandardpathssetinstallprefix}, returns that +value, otherwise tries to determine it automatically (Linux only right +now) and finally returns the default \texttt{/usr/local} value if it failed. -\membersection{wxStandardPaths::GetLocalDataDir}\label{wxstandardsathsgetlocaldatadir} + +\membersection{wxStandardPaths::GetLocalDataDir}\label{wxstandardpathsgetlocaldatadir} \func{static wxString}{GetLocalDataDir}{\void} Return the location for application data files which are host-specific and can't, or shouldn't, be shared with the other machines. -This is the same as \helpref{GetDataDir()}{wxstandardsathsgetdatadir} except +This is the same as \helpref{GetDataDir()}{wxstandardpathsgetdatadir} except under Unix where it returns \texttt{/etc/\textit{appname}}. -\membersection{wxStandardPaths::GetPluginsDir}\label{wxstandardsathsgetpluginsdir} +\membersection{wxStandardPaths::GetPluginsDir}\label{wxstandardpathsgetpluginsdir} \func{static wxString}{GetPluginsDir}{\void} @@ -110,9 +123,9 @@ Return the directory where the loadable modules (plugins) live. Example return values: \begin{itemize} - \item Unix: \texttt{/usr/lib/\textit{appname}} + \item Unix: \texttt{\textit{prefix}/lib/\textit{appname}} \item Windows: the directory of the executable file - \item Mac: \texttt{\textit{appname}.app/Contents/Plugins} bundle subdirectory + \item Mac: \texttt{\textit{appname}.app/Contents/PlugIns} bundle subdirectory \end{itemize} \wxheading{See also} @@ -120,7 +133,7 @@ Example return values: \helpref{wxDynamicLibrary}{wxdynamiclibrary} -\membersection{wxStandardPaths::GetUserConfigDir}\label{wxstandardsathsgetuserconfigdir} +\membersection{wxStandardPaths::GetUserConfigDir}\label{wxstandardpathsgetuserconfigdir} \func{static wxString}{GetUserConfigDir}{\void} @@ -132,11 +145,11 @@ Return the directory for the user config files: \end{itemize} Only use this method if you have a single configuration file to put in this -directory, otherwise \helpref{GetUserDataDir()}{wxstandardsathsgetuserdatadir} is +directory, otherwise \helpref{GetUserDataDir()}{wxstandardpathsgetuserdatadir} is more appropriate. -\membersection{wxStandardPaths::GetUserDataDir}\label{wxstandardsathsgetuserdatadir} +\membersection{wxStandardPaths::GetUserDataDir}\label{wxstandardpathsgetuserdatadir} \func{static wxString}{GetUserDataDir}{\void} @@ -144,19 +157,35 @@ Return the directory for the user-dependent application data files: \begin{itemize} \item Unix: \texttt{\verb|~|/.\textit{appname}} \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Application Data$\backslash$\textit{appname}} - \item Mac: \texttt{\verb|~|/Library/\textit{appname}} + \item Mac: \texttt{\verb|~|/Library/Application Support/\textit{appname}} \end{itemize} -\membersection{wxStandardPaths::GetUserLocalDataDir}\label{wxstandardsathsgetuserlocaldatadir} +\membersection{wxStandardPaths::GetUserLocalDataDir}\label{wxstandardpathsgetuserlocaldatadir} \func{static wxString}{GetUserLocalDataDir}{\void} Return the directory for user data files which shouldn't be shared with the other machines. -This is the same as \helpref{GetUserDataDir()}{wxstandardsathsgetuserdatadir} for +This is the same as \helpref{GetUserDataDir()}{wxstandardpathsgetuserdatadir} for all platforms except Windows where it returns \texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Local Settings$\backslash$Application Data$\backslash$\textit{appname}} +\membersection{wxStandardPaths::SetInstallPrefix}\label{wxstandardpathssetinstallprefix} + +\func{static void}{SetInstallPrefix}{\param{const wxString\& }{prefix}} + +\textbf{Note: } This function is only available under Unix. + +Lets wxStandardPaths know about the real program installation prefix on a Unix +system. By default, the value returned by +\helpref{GetInstallPrefix}{wxstandardpathsgetinstallprefix} is used. + +Although under Linux systems the program prefix may usually be determined +automatically, portable programs should call this function. Usually the prefix +is set during program configuration if using GNU autotools and so it is enough +to pass its value defined in \texttt{config.h} to this function. + + diff --git a/include/wx/stdpaths.h b/include/wx/stdpaths.h index 938f0f48b2..5940fab64f 100644 --- a/include/wx/stdpaths.h +++ b/include/wx/stdpaths.h @@ -19,6 +19,23 @@ class WXDLLIMPEXP_BASE wxStandardPaths { public: +#ifdef __UNIX_LIKE__ + // set the program installation directory which is /usr/local by default + // + // under some systems (currently only Linux) the program directory can be + // determined automatically but for portable programs you should always set + // it explicitely + static void SetInstallPrefix(const wxString& prefix); + + // get the program installation prefix + // + // if the prefix had been previously by SetInstallPrefix, returns that + // value, otherwise tries to determine it automatically (Linux only right + // now) and returns /usr/local if it failed + static wxString GetInstallPrefix(); +#endif // __UNIX_LIKE__ + + // return the directory with system config files: // /etc under Unix, c:\Windows under Windows, /Library/Preferences for Mac static wxString GetConfigDir(); @@ -34,8 +51,8 @@ public: // return the location of the applications global, i.e. not user-specific, // data files // - // /usr/share/appname under Unix, c:\Program Files\appname under Windows, - // Contents app bundle directory under Mac + // prefix/share/appname under Unix, c:\Program Files\appname under Windows, + // appname.app/Contents/SharedSupport app bundle directory under Mac static wxString GetDataDir(); // return the location for application data files which are host-specific @@ -47,7 +64,7 @@ public: // // $HOME/.appname under Unix, // c:\Documents and Settings\username\Application Data\appname under Windows - // and ~/Library/appname under Mac + // and ~/Library/Application Support/appname under Mac static wxString GetUserDataDir(); // return the directory for user data files which shouldn't be shared with @@ -59,7 +76,7 @@ public: // return the directory where the loadable modules (plugins) live // - // /usr/lib/appname under Unix, program directory under Windows and + // prefix/lib/appname under Unix, program directory under Windows and // Contents/Plugins app bundle subdirectory under Mac static wxString GetPluginsDir(); }; -- 2.45.2