X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4d01e350fe2d8cb15c068d579c4022345f3ff0c0..9e967d5417d49764276cf121a32c35d5770b1332:/docs/latex/wx/pathlist.tex diff --git a/docs/latex/wx/pathlist.tex b/docs/latex/wx/pathlist.tex index 6f04950e11..a904788f26 100644 --- a/docs/latex/wx/pathlist.tex +++ b/docs/latex/wx/pathlist.tex @@ -2,84 +2,106 @@ The path list is a convenient way of storing a number of directories, and when presented with a filename without a directory, searching for an existing file -in those directories. Storing the filename only in an application's files and -using a locally-defined list of directories makes the application and its files more -portable. +in those directories. -Use the {\it wxFileNameFromPath} global function to extract the filename -from the path. +Be sure to look also at \helpref{wxStandardPaths}{wxstandardpaths} if you only +want to search files in some standard paths. \wxheading{Derived from} -\helpref{wxList}{wxlist}\\ -\helpref{wxObject}{wxobject} +\helpref{wxArrayString}{wxarraystring}\\ +\helpref{wxArray}{wxarray} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} -\helpref{wxList}{wxlist} +\helpref{wxArrayString}{wxarraystring}, \helpref{wxStandardPaths}{wxstandardpaths}, \helpref{wxFileName}{wxfilename} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxPathList::wxPathList} +\membersection{wxPathList::wxPathList}\label{wxpathlistctor} \func{}{wxPathList}{\void} -Constructor. +Empty constructor. + +\func{}{wxPathList}{\param{const wxArrayString\& }{arr}} + +Constructs the object calling the \helpref{Add}{wxpathlistadd} function. -\membersection{wxPathList::AddEnvList} +\membersection{wxPathList::AddEnvList}\label{wxpathlistaddenvlist} \func{void}{AddEnvList}{\param{const wxString\& }{env\_variable}} Finds the value of the given environment variable, and adds all paths -to the path list. Useful for finding files in the PATH variable, for +to the path list. Useful for finding files in the {\tt PATH} variable, for example. -\membersection{wxPathList::Add} +\membersection{wxPathList::Add}\label{wxpathlistadd} + +\func{bool}{Add}{\param{const wxString\& }{path}} + +\func{void}{Add}{\param{const wxArrayString\& }{arr}} + +The first form adds the given directory to the path list, if the path is not already in the list. +If the path cannot be normalized for some reason, it returns \false. -\func{void}{Add}{\param{const wxString\& }{path}} +The second form just calls the first form on all elements of the given array. -Adds the given directory to the path list, but does not -check if the path was already on the list (use -\helpref{wxPathList::Member()}{wxpathlistmember} for this). +The {\it path} is always considered a directory but no existence checks will be done on it +(because if it doesn't exist, it could be created later and thus result a valid path when +\helpref{FindValidPath}{wxpathlistfindvalidpath} is called). +{\bf Note:} if the given path is relative, it won't be made absolute before adding it +(this is why \helpref{FindValidPath}{wxpathlistfindvalidpath} may return relative paths). -\membersection{wxPathList::EnsureFileAccessible} -\func{void}{EnsureFileAccessible}{\param{const wxString\& }{filename}} +\membersection{wxPathList::EnsureFileAccessible}\label{wxpathlistensurefileaccessible} -Given a full filename (with path), ensures that files in the same path -can be accessed using the pathlist. It does this by stripping the -filename and adding the path to the list if not already there. +\func{bool}{EnsureFileAccessible}{\param{const wxString\& }{filename}} +Given a full filename (with path), calls \helpref{Add}{wxpathlistadd} with the path +of the file. -\membersection{wxPathList::FindAbsoluteValidPath} -\func{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}} +\membersection{wxPathList::FindAbsoluteValidPath}\label{wxpathlistfindabsolutepath} -Searches for a full path for an existing file by appending {\it file} to -successive members of the path list. If the file wasn't found, an empty -string is returned. +\constfunc{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}} +Like \helpref{FindValidPath}{wxpathlistfindvalidpath} but this function always +returns an absolute path (eventually prepending the current working directory +to the value returned \helpref{FindValidPath}{wxpathlistfindvalidpath}) or an +empty string. -\membersection{wxPathList::FindValidPath} -\func{wxString}{FindValidPath}{\param{const wxString\& }{file}} +\membersection{wxPathList::FindValidPath}\label{wxpathlistfindvalidpath} -Searches for a full path for an existing file by appending {\it file} to -successive members of the path list. If the file wasn't found, an empty string -is returned. This path may be relative to the current working directory. +\constfunc{wxString}{FindValidPath}{\param{const wxString\& }{file}} +Searches the given file in all paths stored in this class. +The first path which concatenated to the given string points to an existing +file (see \helpref{wxFileExists}{wxfileexists}) is returned. -\membersection{wxPathList::Member}\label{wxpathlistmember} +If the file wasn't found in any of the stored paths, an empty string is returned. -\func{bool}{Member}{\param{const wxString\& }{file}} +The given string must be a file name, eventually with a path prefix (if the path +prefix is absolute, only its name will be searched); i.e. it must not end with +a directory separator (see \helpref{wxFileName::GetPathSeparator}{wxfilenamegetpathseparator}) +otherwise an assertion will fail. -true if the path is in the path list (ignoring case). +The returned path may be relative to the current working directory. +Note in fact that wxPathList can be used to store both relative and absolute paths so that +if you \helpref{Add()}{wxpathlistadd}ed relative paths, then the current working directory +(see \helpref{wxGetCwd}{wxgetcwd} and \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory}) +may affect the value returned by this function!