Moved desktop margin options to a more sensible place

[wxWidgets.git] / docs / latex / wx / pathlist.tex

diff --git a/docs/latex/wx/pathlist.tex b/docs/latex/wx/pathlist.tex
index b74547fea16b9608aa761c082ae72bd70e455c93..a904788f2686197c547e045ebad7481ad8f759cf 100644 (file)
--- a/docs/latex/wx/pathlist.tex
+++ b/docs/latex/wx/pathlist.tex
@@ -2,24 +2,27 @@
 
 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
 
 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 \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} 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}
 
 
 \wxheading{Derived from}
 

-\helpref{wxArrayString}{wxarraystring}
+\helpref{wxArrayString}{wxarraystring}\\
+\helpref{wxArray}{wxarray}

 
 \wxheading{Include files}
 
 <wx/filefn.h>
 
 
 \wxheading{Include files}
 
 <wx/filefn.h>
 

+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{See also}
 
 \wxheading{See also}
 

-\helpref{wxArrayString}{wxarraystring}
+\helpref{wxArrayString}{wxarraystring}, \helpref{wxStandardPaths}{wxstandardpaths}, \helpref{wxFileName}{wxfilename}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 


@@ -40,45 +43,65 @@ Constructs the object calling the \helpref{Add}{wxpathlistadd} function.
 \func{void}{AddEnvList}{\param{const wxString\& }{env\_variable}}
 
 Finds the value of the given environment variable, and adds all paths
 \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}\label{wxpathlistadd}
 
 example.
 
 
 \membersection{wxPathList::Add}\label{wxpathlistadd}
 

-\func{void}{Add}{\param{const wxString\& }{path}}
+\func{bool}{Add}{\param{const wxString\& }{path}}

 
 \func{void}{Add}{\param{const wxArrayString\& }{arr}}
 
 
 \func{void}{Add}{\param{const wxArrayString\& }{arr}}
 

-The first form adds the given directory (the filename if present is removed)
-to the path list, if the path is not already in the list.
+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.

 
 The second form just calls the first form on all elements of the given array.
 
 
 The second form just calls the first form on all elements of the given array.
 

+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}\label{wxpathlistensurefileaccessible}
 
 
 \membersection{wxPathList::EnsureFileAccessible}\label{wxpathlistensurefileaccessible}
 

-\func{void}{EnsureFileAccessible}{\param{const wxString\& }{filename}}
+\func{bool}{EnsureFileAccessible}{\param{const wxString\& }{filename}}

 
 

-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.
+Given a full filename (with path), calls \helpref{Add}{wxpathlistadd} with the path
+of the file.

 
 
 \membersection{wxPathList::FindAbsoluteValidPath}\label{wxpathlistfindabsolutepath}
 
 \constfunc{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}}
 
 
 
 \membersection{wxPathList::FindAbsoluteValidPath}\label{wxpathlistfindabsolutepath}
 
 \constfunc{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}}
 

-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.
+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}\label{wxpathlistfindvalidpath}
 
 \constfunc{wxString}{FindValidPath}{\param{const wxString\& }{file}}
 
 
 
 \membersection{wxPathList::FindValidPath}\label{wxpathlistfindvalidpath}
 
 \constfunc{wxString}{FindValidPath}{\param{const wxString\& }{file}}
 

-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.
+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.
+
+If the file wasn't found in any of the stored paths, an empty string is returned.
+
+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.
+
+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!