X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/96e2aec50abc9d69ecd9b37d0901cb1f021dfe8c..598e55d7143d4fca6cd7e2562cff5310671b7cd3:/docs/latex/wx/stdpaths.tex diff --git a/docs/latex/wx/stdpaths.tex b/docs/latex/wx/stdpaths.tex index 02a9d968eb..ff39c09ebf 100644 --- a/docs/latex/wx/stdpaths.tex +++ b/docs/latex/wx/stdpaths.tex @@ -6,41 +6,38 @@ %% Created: 2004-10-17 %% RCS-ID: $Id$ %% Copyright: (c) 2004 Vadim Zeitlin -%% License: wxWidgets license +%% License: wxWindows 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. - -Please note that this is not a real class because object of this type are never -created but more a namespace containing the class methods which are all static, -so to use wxStandardPaths simply call its methods directly. +used by applications to find their data files in a portable way. 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. +replaced with the value returned by \helpref{wxApp::GetAppName}{wxappgetappname} +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. + +This class is MT-safe: its methods may be called concurrently from different +threads without additional locking. \wxheading{Derived from} @@ -48,22 +45,29 @@ No base class \wxheading{Include files} - + \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardsathsgetconfigdir} +\membersection{wxStandardPaths::Get}\label{wxstandardpathsget} + +\func{static wxStandardPathsBase\&}{Get}{\void} + +Returns reference to the unique global standard paths object. + + +\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardpathsgetconfigdir} -\func{static wxString}{GetConfigDir}{\void} +\constfunc{wxString}{GetConfigDir}{\void} Return the directory containing the system config files. Example return values: \begin{itemize} \item Unix: \texttt{/etc} - \item Windows: \texttt{C:$\backslash$Windows} + \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$All Users$\backslash$Application Data} \item Mac: \texttt{/Library/Preferences} \end{itemize} @@ -72,47 +76,109 @@ Example return values: \helpref{wxFileConfig}{wxfileconfig} -\membersection{wxStandardPaths::GetDataDir}\label{wxstandardsathsgetdatadir} +\membersection{wxStandardPaths::GetDataDir}\label{wxstandardpathsgetdatadir} -\func{static wxString}{GetDataDir}{\void} +\constfunc{wxString}{GetDataDir}{\void} Return the location of the applications global, i.e. not user-specific, data files. Example return values: \begin{itemize} - \item Unix: \texttt{/usr/share/\textit{appname}} - \item Windows: \texttt{C:$\backslash$Program Files$\backslash$\textit{appname}} - \item Mac: \texttt{\textit{appname}.app/Contents} bundle subdirectory + \item Unix: \texttt{\textit{prefix}/share/\textit{appname}} + \item Windows: the directory where the executable file is located + \item Mac: \texttt{\textit{appname}.app/Contents/SharedSupport} bundle subdirectory \end{itemize} \wxheading{See also} -\helpref{GetLocalDataDir}{wxstandardsathsgetlocaldatadir} +\helpref{GetLocalDataDir}{wxstandardpathsgetlocaldatadir} + + +\membersection{wxStandardPaths::GetDocumentsDir}\label{wxstandardpathsgetdocumentsdir} + +\constfunc{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} + +\newsince{2.7.0} + + +\membersection{wxStandardPaths::GetExecutablePath}\label{wxstandardpathsgetexecutablepath} + +\constfunc{wxString}{GetExecutablePath}{\void} + +Return the directory and the filename for the current executable. + +Example return values: +\begin{itemize} + \item Unix: \texttt{/usr/local/bin/exename} + \item Windows: \texttt{C:$\backslash$Programs$\backslash$AppFolder$\backslash$exename.exe} + \item Mac: \texttt{/Programs/exename} +\end{itemize} + + + +\membersection{wxStandardPaths::GetInstallPrefix}\label{wxstandardpathsgetinstallprefix} + +\constfunc{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}. -\membersection{wxStandardPaths::GetLocalDataDir}\label{wxstandardsathsgetlocaldatadir} +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. -\func{static wxString}{GetLocalDataDir}{\void} + +\membersection{wxStandardPaths::GetLocalDataDir}\label{wxstandardpathsgetlocaldatadir} + +\constfunc{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::GetLocalizedResourcesDir}\label{wxstandardpathsgetlocalizedresourcesdir} + +\constfunc{wxString}{GetLocalizedResourcesDir}{\param{const wxChar*}{ lang}, \param{ResourceCat}{ category = ResourceCat\_None}} + +Return the localized resources directory containing the resource files of the +specified category for the given language. + +In general this is just the same as \arg{lang} subdirectory of +\helpref{GetResourcesDir()}{wxstandardpathsgetresourcesdir} (or +\texttt{\arg{lang}.lproj} under Mac OS X) but is something quite +different for message catalog category under Unix where it returns the standard +\texttt{\textit{prefix}/share/locale/\arg{lang}/LC\_MESSAGES} directory. + +\newsince{2.7.0} + + +\membersection{wxStandardPaths::GetPluginsDir}\label{wxstandardpathsgetpluginsdir} -\func{static wxString}{GetPluginsDir}{\void} +\constfunc{wxString}{GetPluginsDir}{\void} 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,43 +186,93 @@ Example return values: \helpref{wxDynamicLibrary}{wxdynamiclibrary} -\membersection{wxStandardPaths::GetUserConfigDir}\label{wxstandardsathsgetuserconfigdir} +\membersection{wxStandardPaths::GetResourcesDir}\label{wxstandardpathsgetresourcesdir} + +\constfunc{wxString}{GetResourcesDir}{\void} + +Return the directory where the application resource files are located. The +resources are the auxiliary data files needed for the application to run and +include, for example, image and sound files it might use. + +This function is the same as \helpref{GetDataDir}{wxstandardpathsgetdatadir} for +all platforms except Mac OS X. + +Example return values: +\begin{itemize} + \item Unix: \texttt{\textit{prefix}/share/\textit{appname}} + \item Windows: the directory where the executable file is located + \item Mac: \texttt{\textit{appname}.app/Contents/Resources} bundle subdirectory +\end{itemize} + +\newsince{2.7.0} + + +\wxheading{See also} + +\helpref{GetLocalizedResourcesDir}{wxstandardpathsgetlocalizedresourcesdir} + +\membersection{wxStandardPaths::GetTempDir}\label{wxstandardpathsgettempdir} + +\constfunc{wxString}{GetTempDir}{\void} + +Return the directory for storing temporary files. To create unique temporary files, +it is best to use \helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename} for correct behaviour when +multiple processes are attempting to create temporary files. -\func{static wxString}{GetUserConfigDir}{\void} +\newsince{2.7.2} + +\membersection{wxStandardPaths::GetUserConfigDir}\label{wxstandardpathsgetuserconfigdir} + +\constfunc{wxString}{GetUserConfigDir}{\void} Return the directory for the user config files: \begin{itemize} - \item Unix: \texttt{\verb|~|} (the home directory) - \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}} - \item Mac: \texttt{\verb|~|/Library/Preferences} + \item Unix: \tt{~} (the home directory) + \item Windows: \tt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Application Data} + \item Mac: \tt{~/Library/Preferences} \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} +\constfunc{wxString}{GetUserDataDir}{\void} 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 Unix: \tt{~/.\textit{appname}} + \item Windows: \tt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Application Data$\backslash$\textit{appname}} + \item Mac: \tt{~/Library/Application Support/\textit{appname}} \end{itemize} -\membersection{wxStandardPaths::GetUserLocalDataDir}\label{wxstandardsathsgetuserlocaldatadir} +\membersection{wxStandardPaths::GetUserLocalDataDir}\label{wxstandardpathsgetuserlocaldatadir} -\func{static wxString}{GetUserLocalDataDir}{\void} +\constfunc{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 -all platforms except Windows where it returns +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{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. +