a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
283 lines
9.9 KiB
TeX
283 lines
9.9 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: stdpaths.tex
|
|
%% Purpose: wxStandardPaths documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 2004-10-17
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 2004 Vadim Zeitlin <vadim@wxwindows.org>
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxStandardPaths}}\label{wxstandardpaths}
|
|
|
|
wxStandardPaths returns the standard locations in the file system and should be
|
|
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. 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. 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 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}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/stdpaths.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxBase}{librarieslist}
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
\membersection{wxStandardPaths::Get}\label{wxstandardpathsget}
|
|
|
|
\func{static wxStandardPathsBase\&}{Get}{\void}
|
|
|
|
Returns reference to the unique global standard paths object.
|
|
|
|
|
|
\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$Documents and Settings$\backslash$All Users$\backslash$Application Data}
|
|
\item Mac: \texttt{/Library/Preferences}
|
|
\end{itemize}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxFileConfig}{wxfileconfig}
|
|
|
|
|
|
\membersection{wxStandardPaths::GetDataDir}\label{wxstandardpathsgetdatadir}
|
|
|
|
\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{\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}{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}.
|
|
|
|
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{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()}{wxstandardpathsgetdatadir} except
|
|
under Unix where it returns \texttt{/etc/\textit{appname}}.
|
|
|
|
|
|
\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.
|
|
|
|
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{\textit{prefix}/lib/\textit{appname}}
|
|
\item Windows: the directory of the executable file
|
|
\item Mac: \texttt{\textit{appname}.app/Contents/PlugIns} bundle subdirectory
|
|
\end{itemize}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxDynamicLibrary}{wxdynamiclibrary}
|
|
|
|
|
|
\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.
|
|
|
|
\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: \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()}{wxstandardpathsgetuserdatadir} is
|
|
more appropriate.
|
|
|
|
|
|
\membersection{wxStandardPaths::GetUserDataDir}\label{wxstandardpathsgetuserdatadir}
|
|
|
|
\constfunc{wxString}{GetUserDataDir}{\void}
|
|
|
|
Return the directory for the user-dependent application data files:
|
|
\begin{itemize}
|
|
\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{wxstandardpathsgetuserlocaldatadir}
|
|
|
|
\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()}{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.
|
|
|