escape more underscores (we need a pre-commit check for those...)

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

diff --git a/docs/latex/wx/filesys.tex b/docs/latex/wx/filesys.tex
index 10a5c6e082e7534bfca628a0a8459f4deebd14c6..2d38e300a553a24c45a2c9d8d33ce1f3a8b1613f 100644 (file)
--- a/docs/latex/wx/filesys.tex
+++ b/docs/latex/wx/filesys.tex
@@ -26,18 +26,22 @@ provide access to user-defined virtual file systems.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxFileSystem::wxFileSystem}\label{wxfilesystemwxfilesystem}
 
 \func{}{wxFileSystem}{\void}
 
 Constructor. 
 
+
 \membersection{wxFileSystem::AddHandler}\label{wxfilesystemaddhandler}
 
 \func{static void}{AddHandler}{\param{wxFileSystemHandler }{*handler}}
 
-This static function adds new handler into the list of handlers.
-The \helpref{handlers}{wxfilesystemhandler} provide access to virtual FS.
+This static function adds new handler into the list of 
+\helpref{handlers}{wxfilesystemhandler} which provide access to virtual FS.
+Note that if two handlers for the same protocol are added, the last one added
+takes precedence.
 
 \wxheading{Note}
 
@@ -51,44 +55,55 @@ This is because (a) AddHandler is a static method, and (b) the handlers
 are deleted in wxFileSystem's destructor so that you don't have to
 care about it.
 
+
+\membersection{wxFileSystem::HasHandlerForPath}\label{wxfilesystemhashandlerforpath}
+
+\func{static bool}{HasHandlerForPath}{\param{const wxString \&}{ location}}
+
+This static function returns \true if there is a registered handler which can open the given
+location.
+
+
 \membersection{wxFileSystem::ChangePathTo}\label{wxfilesystemchangepathto}
 
-\func{void}{ChangePathTo}{\param{const wxString\& }{location}, \param{bool }{is\_dir = FALSE}}
+\func{void}{ChangePathTo}{\param{const wxString\& }{location}, \param{bool }{is\_dir = false}}
 
 Sets the current location. {\it location} parameter passed to 
 \helpref{OpenFile}{wxfilesystemopenfile} is relative to this path.
 
-{\bf Caution! } Unless {\it is\_dir} is TRUE the {\it location} parameter
+{\bf Caution! } Unless {\it is\_dir} is true the {\it location} parameter
 is not the directory name but the name of the file in this directory. All these
 commands change the path to "dir/subdir/":
 
 \begin{verbatim}
   ChangePathTo("dir/subdir/xh.htm");
-  ChangePathTo("dir/subdir", TRUE);
-C  hangePathTo("dir/subdir/", TRUE);
+  ChangePathTo("dir/subdir", true);
+  ChangePathTo("dir/subdir/", true);
 \end{verbatim}
 
 \wxheading{Parameters}
 
 \docparam{location}{the new location. Its meaning depends on the value of {\it is\_dir}}
 
-\docparam{is\_dir}{if TRUE {\it location} is new directory. If FALSE (default) 
+\docparam{is\_dir}{if true {\it location} is new directory. If false (default) 
 {\it location} is {\bf file in} the new directory.}
 
 \wxheading{Example}
 
 \begin{verbatim}
   f = fs -> OpenFile("hello.htm"); // opens file 'hello.htm'
-  fs -> ChangePathTo("subdir/folder", TRUE);
+  fs -> ChangePathTo("subdir/folder", true);
   f = fs -> OpenFile("hello.htm"); // opens file 'subdir/folder/hello.htm' !!
 \end{verbatim}
 
+
 \membersection{wxFileSystem::GetPath}\label{wxfilesystemgetpath}
 
 \func{wxString}{GetPath}{\void}
 
 Returns actual path (set by \helpref{ChangePathTo}{wxfilesystemchangepathto}).
 
+
 \membersection{wxFileSystem::FileNameToURL}\label{wxfilesystemfilenametourl}
 
 \func{static wxString}{FileNameToURL}{\param{wxFileName }{filename}}
@@ -100,6 +115,26 @@ Converts filename into URL.
 \helpref{wxFileSystem::URLToFileName}{wxfilesystemurltofilename},
 \helpref{wxFileName}{wxfilename}
 
+
+\membersection{wxFileSystem::FindFileInPath}\label{wxfilesystemfindfileinpath}
+
+\func{bool}{FindFileInPath}{\param{wxString }{*str}, \param{const wxChar }{*path}, \param{const wxChar }{*file}}
+
+Looks for the file with the given name \arg{file} in a colon or semi-colon
+(depending on the current platform) separated list of directories in
+\arg{path}. If the file is found in any directory, returns \true and the full
+path of the file in \arg{str}, otherwise returns \false and doesn't modify 
+\arg{str}.
+
+\wxheading{Parameters}
+
+\docparam{str}{Receives the full path of the file, must not be \NULL}
+
+\docparam{path}{\texttt{wxPATH\_SEP}-separated list of directories}
+
+\docparam{file}{the name of the file to look for}
+
+
 \membersection{wxFileSystem::FindFirst}\label{wxfilesystemfindfirst}
 
 \func{wxString}{FindFirst}{\param{const wxString\& }{wildcard}, \param{int }{flags = 0}}
@@ -108,12 +143,14 @@ Works like \helpref{wxFindFirstFile}{wxfindfirstfile}. Returns name of the first
 filename (within filesystem's current path) that matches {\it wildcard}. {\it flags} may be one of
 wxFILE (only files), wxDIR (only directories) or 0 (both).
 
+
 \membersection{wxFileSystem::FindNext}\label{wxfilesystemfindnext}
 
 \func{wxString}{FindNext}{\void}
 
 Returns the next filename that matches parameters passed to \helpref{FindFirst}{wxfilesystemfindfirst}.
 
+
 \membersection{wxFileSystem::OpenFile}\label{wxfilesystemopenfile}
 
 \func{wxFSFile*}{OpenFile}{\param{const wxString\& }{location}}
@@ -121,11 +158,13 @@ Returns the next filename that matches parameters passed to \helpref{FindFirst}{
 Opens the file and returns a pointer to a \helpref{wxFSFile}{wxfsfile} object
 or NULL if failed. It first tries to open the file in relative scope
 (based on value passed to ChangePathTo() method) and then as an
-absolute path.
+absolute path.  Note that the user is responsible for deleting the returned
+wxFSFile.  
+
 
 \membersection{wxFileSystem::URLToFileName}\label{wxfilesystemurltofilename}
 
-\func{static wxFileName}{URLToFileName}{\param{const wxString& }{url}}
+\func{static wxFileName}{URLToFileName}{\param{const wxString\& }{url}}
 
 Converts URL into a well-formed filename. The URL must use the {\tt file} 
 protocol.