%% Created: 2004-10-17
%% RCS-ID: $Id$
%% Copyright: (c) 2004 Vadim Zeitlin <vadim@wxwindows.org>
-%% 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}
\wxheading{Include files}
-<wx/fileloc.h>
+<wx/stdpaths.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
\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.
+
-\func{static wxString}{GetConfigDir}{\void}
+\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardpathsgetconfigdir}
+
+\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}
\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 wxString\&}{ lang}, \param{ResourceCat}{ category = ResourceCat\_None}}
+
+Return the localized resources directory containing the resource files of the
+specified category for the given language.
-\func{static wxString}{GetPluginsDir}{\void}
+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}
+
+\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}
\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}
-\func{static wxString}{GetUserConfigDir}{\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.
+
+\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.
+
+
+\membersection{wxStandardPaths::UseAppInfo}\label{wxstandardpathsuseappinfo}
+
+\func{void}{UseAppInfo}{\param{int }{info}}
+
+Controls what application information is used when constructing paths that
+should be unique to this program, such as the application data directory, the
+plugins directory on Unix, etc.
+
+Valid values for \arg{info} are \texttt{AppInfo\_None} and either one or
+combination of \texttt{AppInfo\_AppName} and \texttt{AppInfo\_VendorName}. The
+first one tells this class to not use neither application nor vendor name in
+the paths.
+
+By default, only the application name is used under Unix systems but both
+application and vendor names are used under Windows and Mac.
+
+\wxheading{See also}
+
+\helpref{wxApp::SetAppName}{wxappsetappname}, \helpref{wxApp::SetVendorName}{wxappsetvendorname}
+
projects / wxWidgets.git / blobdiff