another patch bring the docs more up to date (patch 1717776)

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

diff --git a/docs/latex/wx/pathlist.tex b/docs/latex/wx/pathlist.tex
index e1e90aa3fd067f4269ebcca42848792afd6d6409..aa241be22276a404366ab0073326975a08c0bccd 100644 (file)
--- a/docs/latex/wx/pathlist.tex
+++ b/docs/latex/wx/pathlist.tex
@@ -2,12 +2,10 @@
 
 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}
 


@@ -40,17 +38,19 @@ 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}}
 
 The first form adds the given directory to the path list, if the path is not already in the list.
 
 \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.
+

 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
 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


@@ -63,34 +63,40 @@ The {\it path} is always considered a directory but no existence checks will be
 
 \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 (i.e. absolute) 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 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.
+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.

 
 

-The returned path may be relative to the current working directory.
+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 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!
+