1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: stdpaths.tex 3%% Purpose: wxStandardPaths documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: 2004-10-17 7%% RCS-ID: $Id: stdpaths.tex 54786 2008-07-26 09:13:27Z SC $ 8%% Copyright: (c) 2004 Vadim Zeitlin <vadim@wxwindows.org> 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxStandardPaths}}\label{wxstandardpaths} 13 14wxStandardPaths returns the standard locations in the file system and should be 15used by applications to find their data files in a portable way. 16 17In the description of the methods below, the example return values are given 18for the Unix, Windows and Mac OS X systems, however please note that these are 19just the examples and the actual values may differ. For example, under Windows: 20the system administrator may change the standard directories locations, i.e. 21the Windows directory may be named \texttt{W:$\backslash$Win2003} instead of 22the default \texttt{C:$\backslash$Windows}. 23 24The strings \texttt{\textit{appname}} and \texttt{\textit{username}} should be 25replaced with the value returned by \helpref{wxApp::GetAppName}{wxappgetappname} 26and the name of the currently logged in user, respectively. The string 27\texttt{\textit{prefix}} is only used under Unix and is \texttt{/usr/local} by 28default but may be changed using \helpref{SetInstallPrefix}{wxstandardpathssetinstallprefix}. 29 30The directories returned by the methods of this class may or may not exist. If 31they don't exist, it's up to the caller to create them, wxStandardPaths doesn't 32do it. 33 34Finally note that these functions only work with standardly packaged 35applications. I.e. under Unix you should follow the standard installation 36conventions and under Mac you should create your application bundle according 37to the Apple guidelines. Again, this class doesn't help you to do it. 38 39This class is MT-safe: its methods may be called concurrently from different 40threads without additional locking. 41 42Note that you don't allocate an instance of class wxStandardPaths, but retrieve the 43global standard paths object using \texttt{wxStandardPaths::Get} on which you call the 44desired methods. 45 46\wxheading{Derived from} 47 48No base class 49 50\wxheading{Include files} 51 52<wx/stdpaths.h> 53 54 55\latexignore{\rtfignore{\wxheading{Members}}} 56 57 58\membersection{wxStandardPaths::Get}\label{wxstandardpathsget} 59 60\func{static wxStandardPathsBase\&}{Get}{\void} 61 62Returns reference to the unique global standard paths object. 63 64 65\membersection{wxStandardPaths::GetConfigDir}\label{wxstandardpathsgetconfigdir} 66 67\constfunc{wxString}{GetConfigDir}{\void} 68 69Return the directory containing the system config files. 70 71Example return values: 72\begin{itemize} 73 \item Unix: \texttt{/etc} 74 \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$All Users$\backslash$Application Data} 75 \item Mac: \texttt{/Library/Preferences} 76\end{itemize} 77 78\wxheading{See also} 79 80\helpref{wxFileConfig}{wxfileconfig} 81 82 83\membersection{wxStandardPaths::GetDataDir}\label{wxstandardpathsgetdatadir} 84 85\constfunc{wxString}{GetDataDir}{\void} 86 87Return the location of the applications global, i.e. not user-specific, 88data files. 89 90Example return values: 91\begin{itemize} 92 \item Unix: \texttt{\textit{prefix}/share/\textit{appname}} 93 \item Windows: the directory where the executable file is located 94 \item Mac: \texttt{\textit{appname}.app/Contents/SharedSupport} bundle subdirectory 95\end{itemize} 96 97\wxheading{See also} 98 99\helpref{GetLocalDataDir}{wxstandardpathsgetlocaldatadir} 100 101 102\membersection{wxStandardPaths::GetDocumentsDir}\label{wxstandardpathsgetdocumentsdir} 103 104\constfunc{wxString}{GetDocumentsDir}{\void} 105 106Return the directory containing the current user's documents. 107 108Example return values: 109\begin{itemize} 110 \item Unix: \tt{~} (the home directory) 111 \item Windows: \texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Documents} 112 \item Mac: \texttt{~/Documents} 113\end{itemize} 114 115\newsince{2.7.0} 116 117 118\membersection{wxStandardPaths::GetExecutablePath}\label{wxstandardpathsgetexecutablepath} 119 120\constfunc{wxString}{GetExecutablePath}{\void} 121 122Return the directory and the filename for the current executable. 123 124Example return values: 125\begin{itemize} 126 \item Unix: \texttt{/usr/local/bin/exename} 127 \item Windows: \texttt{C:$\backslash$Programs$\backslash$AppFolder$\backslash$exename.exe} 128 \item Mac: \texttt{/Programs/exename} 129\end{itemize} 130 131 132 133\membersection{wxStandardPaths::GetInstallPrefix}\label{wxstandardpathsgetinstallprefix} 134 135\constfunc{wxString}{GetInstallPrefix}{\void} 136 137\textbf{Note: } This function is only available under Unix. 138 139Return the program installation prefix, e.g. \texttt{/usr}, \texttt{/opt} or 140\texttt{/home/zeitlin}. 141 142If the prefix had been previously by 143\helpref{SetInstallPrefix}{wxstandardpathssetinstallprefix}, returns that 144value, otherwise tries to determine it automatically (Linux only right 145now) and finally returns the default \texttt{/usr/local} value if it failed. 146 147 148\membersection{wxStandardPaths::GetLocalDataDir}\label{wxstandardpathsgetlocaldatadir} 149 150\constfunc{wxString}{GetLocalDataDir}{\void} 151 152Return the location for application data files which are host-specific and 153can't, or shouldn't, be shared with the other machines. 154 155This is the same as \helpref{GetDataDir()}{wxstandardpathsgetdatadir} except 156under Unix where it returns \texttt{/etc/\textit{appname}}. 157 158 159\membersection{wxStandardPaths::GetLocalizedResourcesDir}\label{wxstandardpathsgetlocalizedresourcesdir} 160 161\constfunc{wxString}{GetLocalizedResourcesDir}{\param{const wxChar*}{ lang}, \param{ResourceCat}{ category = ResourceCat\_None}} 162 163Return the localized resources directory containing the resource files of the 164specified category for the given language. 165 166In general this is just the same as \arg{lang} subdirectory of 167\helpref{GetResourcesDir()}{wxstandardpathsgetresourcesdir} (or 168\texttt{\arg{lang}.lproj} under Mac OS X) but is something quite 169different for message catalog category under Unix where it returns the standard 170\texttt{\textit{prefix}/share/locale/\arg{lang}/LC\_MESSAGES} directory. 171 172\newsince{2.7.0} 173 174 175\membersection{wxStandardPaths::GetPluginsDir}\label{wxstandardpathsgetpluginsdir} 176 177\constfunc{wxString}{GetPluginsDir}{\void} 178 179Return the directory where the loadable modules (plugins) live. 180 181Example return values: 182\begin{itemize} 183 \item Unix: \texttt{\textit{prefix}/lib/\textit{appname}} 184 \item Windows: the directory of the executable file 185 \item Mac: \texttt{\textit{appname}.app/Contents/PlugIns} bundle subdirectory 186\end{itemize} 187 188\wxheading{See also} 189 190\helpref{wxDynamicLibrary}{wxdynamiclibrary} 191 192 193\membersection{wxStandardPaths::GetResourcesDir}\label{wxstandardpathsgetresourcesdir} 194 195\constfunc{wxString}{GetResourcesDir}{\void} 196 197Return the directory where the application resource files are located. The 198resources are the auxiliary data files needed for the application to run and 199include, for example, image and sound files it might use. 200 201This function is the same as \helpref{GetDataDir}{wxstandardpathsgetdatadir} for 202all platforms except Mac OS X. 203 204Example return values: 205\begin{itemize} 206 \item Unix: \texttt{\textit{prefix}/share/\textit{appname}} 207 \item Windows: the directory where the executable file is located 208 \item Mac: \texttt{\textit{appname}.app/Contents/Resources} bundle subdirectory 209\end{itemize} 210 211\newsince{2.7.0} 212 213 214\wxheading{See also} 215 216\helpref{GetLocalizedResourcesDir}{wxstandardpathsgetlocalizedresourcesdir} 217 218\membersection{wxStandardPaths::GetTempDir}\label{wxstandardpathsgettempdir} 219 220\constfunc{wxString}{GetTempDir}{\void} 221 222Return the directory for storing temporary files. To create unique temporary files, 223it is best to use \helpref{wxFileName::CreateTempFileName}{wxfilenamecreatetempfilename} for correct behaviour when 224multiple processes are attempting to create temporary files. 225 226\newsince{2.7.2} 227 228\membersection{wxStandardPaths::GetUserConfigDir}\label{wxstandardpathsgetuserconfigdir} 229 230\constfunc{wxString}{GetUserConfigDir}{\void} 231 232Return the directory for the user config files: 233\begin{itemize} 234 \item Unix: \tt{~} (the home directory) 235 \item Windows: \tt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Application Data} 236 \item Mac: \tt{~/Library/Preferences} 237\end{itemize} 238 239Only use this method if you have a single configuration file to put in this 240directory, otherwise \helpref{GetUserDataDir()}{wxstandardpathsgetuserdatadir} is 241more appropriate. 242 243 244\membersection{wxStandardPaths::GetUserDataDir}\label{wxstandardpathsgetuserdatadir} 245 246\constfunc{wxString}{GetUserDataDir}{\void} 247 248Return the directory for the user-dependent application data files: 249\begin{itemize} 250 \item Unix: \tt{~/.\textit{appname}} 251 \item Windows: \tt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Application Data$\backslash$\textit{appname}} 252 \item Mac: \tt{~/Library/Application Support/\textit{appname}} 253\end{itemize} 254 255 256\membersection{wxStandardPaths::GetUserLocalDataDir}\label{wxstandardpathsgetuserlocaldatadir} 257 258\constfunc{wxString}{GetUserLocalDataDir}{\void} 259 260Return the directory for user data files which shouldn't be shared with 261the other machines. 262 263This is the same as \helpref{GetUserDataDir()}{wxstandardpathsgetuserdatadir} for 264all platforms except Windows where it returns 265\texttt{C:$\backslash$Documents and Settings$\backslash$\textit{username}$\backslash$Local Settings$\backslash$Application Data$\backslash$\textit{appname}} 266 267 268\membersection{wxStandardPaths::SetInstallPrefix}\label{wxstandardpathssetinstallprefix} 269 270\func{void}{SetInstallPrefix}{\param{const wxString\& }{prefix}} 271 272\textbf{Note:} This function is only available under Unix. 273 274Lets wxStandardPaths know about the real program installation prefix on a Unix 275system. By default, the value returned by 276\helpref{GetInstallPrefix}{wxstandardpathsgetinstallprefix} is used. 277 278Although under Linux systems the program prefix may usually be determined 279automatically, portable programs should call this function. Usually the prefix 280is set during program configuration if using GNU autotools and so it is enough 281to pass its value defined in \texttt{config.h} to this function. 282 283