X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/704a4b7524e05d7bf4d208eb1b30be9989abef4c..80d2803f703d1b238f42725504f08266ef02defe:/docs/latex/wx/fs.tex

diff --git a/docs/latex/wx/fs.tex b/docs/latex/wx/fs.tex
index a183aa63a4..21821955f6 100644
--- a/docs/latex/wx/fs.tex
+++ b/docs/latex/wx/fs.tex
@@ -1,75 +1,102 @@
-\section{File Systems}\label{fs}
+\section{wxFileSystem}\label{fs}
 
-The wxHTML library uses {\bf virtual file systems} mechanism
-similar to the one used in Midnight Commander or Dos Navigator or
-FAR or almost any modern file manager. (Do you remember? You can
-press enter on ZIP file and it's content is displayed like it's
-a directory...)
+The wxHTML library uses a {\bf virtual file systems} mechanism
+similar to the one used in Midnight Commander, Dos Navigator,
+FAR or almost any modern file manager. It allows the user to access
+data stored in archives as if they were ordinary files. On-the-fly
+generated files that exist only in memory are also supported.
 
 \wxheading{Classes}
 
-Three classes are used in order to provide full VFS:
+Three classes are used in order to provide virtual file systems mechanism:
 
-\begin{itemize}
-\item \helpref{wxFSFile}{wxfsfile} class provides information
-on opened file (name, input stream, mime type and anchor).
-
-\item \helpref{wxFileSystem}{wxfilesystem} class is interface.
-It's main methods are ChangePathTo() and OpenFile(). This class
+\begin{itemize}\itemsep=0pt
+\item The \helpref{wxFSFile}{wxfsfile} class provides information
+about opened file (name, input stream, mime type and anchor).
+\item The \helpref{wxFileSystem}{wxfilesystem} class is the interface.
+Its main methods are ChangePathTo() and OpenFile(). This class
 is most often used by the end user.
-
-\item \helpref{wxFileSystemHandler}{wxfilesystemhandler} is the core
-if VFS mechanism. You can derive your own handler and pass it to
+\item The \helpref{wxFileSystemHandler}{wxfilesystemhandler} is the core
+of virtual file systems mechanism. You can derive your own handler and pass it to
+of the VFS mechanism. You can derive your own handler and pass it to
 wxFileSystem's AddHandler() method. In the new handler you only need to
-overwrite OpenFile() and CanOpen() methods.
+override the OpenFile() and CanOpen() methods.
 \end{itemize}
 
 \wxheading{Locations}
 
-Locations (aka filenames aka addresses) are constructed from 4 parts:
-
-\begin{itemize}
-\item {\bf protocol} - handler can regonize if it is able to open some
-file by checking it's protocol. Examples are "http", "file" or "ftp"
+Locations (aka filenames aka addresses) are constructed from four parts:
 
+\begin{itemize}\itemsep=0pt
+\item {\bf protocol} - handler can recognize if it is able to open a
+file by checking its protocol. Examples are "http", "file" or "ftp".
 \item {\bf right location} - is the name of file within the protocol.
-In "http://www.wxwindows.org/index.html" the right location is "//www.wxwindows.org/index.html"
-
-\item {\bf anchor} - anchor is optional and is usually not present.
-In "index.htm\#chapter2" the anchor is "chapter2"
-
-\item {\bf left location} - this is usually empty string. 
+In "http://www.wxwindows.org/index.html" the right location is "//www.wxwindows.org/index.html".
+\item {\bf anchor} - an anchor is optional and is usually not present.
+In "index.htm\#chapter2" the anchor is "chapter2".
+\item {\bf left location} - this is usually an empty string. 
 It is used by 'local' protocols such as ZIP.
 See Combined Protocols paragraph for details.
 \end{itemize}
 
 \wxheading{Combined Protocols}
 
-Left location pretends protocol in URL string. 
-It's not used by global protocols like HTTP but it's used
-by local ones - for example you can see this address:
+The left location precedes the protocol in the URL string. 
+It is not used by global protocols like HTTP but it becomes handy when nesting
+protocols - for example you may want to access files in ZIP archive that is
+located on some FTP server:
+
+ftp:ftp.archives.org/pub/cpp\_doc.zip\#zip:reference/fopen.htm\#syntax
+
+In fact, you have to use 'left location' even when accessing local ZIPs:
 
 file:archives/cpp\_doc.zip\#zip:reference/fopen.htm\#syntax
 
-In this example, protocol is "zip", left location is
-"reference/fopen.htm", anchor is "syntax" and right location
-is "file:archives/cpp_doc.zip". It is used by zip handler
-to determine in what file this particular zip VFS is stored.
+In this example, the protocol is "zip", the left location is
+"reference/fopen.htm", the anchor is "syntax" and the right location
+is "file:archives/cpp\_doc.zip". 
 
-In fact there are two protocols used in this example : zip and file.
+There are {\bf two} protocols used in this example: "zip" and "file".
 You can construct even more complicated addresses like this one:
 
 http://www.archives.org/myarchive.zip\#zip:local/docs/cpp/stdio.zip\#zip:index.htm
 
-In this example you access zip VFS stdio.zip stored in another zip (myarchive.zip)
-which is at WWW. Enjoy it :-)
+In this example you access zip virtual file system stdio.zip stored in another zip (myarchive.zip)
+which can be found at WWW.
 
 \wxheading{File Systems Included in wxHTML}
 
-\begin{enumerate}
-\item Local files
-\item HTTP protocol
-\item FTP protocol
-\item .ZIP archives
-\end{enumerate}
+The following virtual file system handlers are part of wxWindows so far:
+
+\begin{twocollist}
+\twocolitem{{\bf wxInternetFSHandler}}{A handler for accessing documents
+via HTTP or FTP protocols. Include file is <wx/fs_inet.h>.}
+\twocolitem{{\bf wxZipFSHandler}}{A handler for ZIP archives. 
+Include file is <wx/fs_zip.h>. URL is in form "archive.zip\#zip:filename".}
+\twocolitem{{\bf wxMemoryFSHandler}}{This handler allows you to access 
+data stored in memory (such as bitmaps) as if they were regular files.
+See \helpref{wxMemoryFSHandler documentation}{wxmemoryfshandler} for details.
+Include file is <wx/fs_mem.h>. UURL is prefixed with memory:, e.g. 
+"memory:myfile.htm"}
+\end{twocollist}
+
+In addition, wxFileSystem itself can access local files.
+
+
+\wxheading{Initializing file system handlers}
+
+Use \helpref{wxFileSystem::AddHandler}{wxfilesystemaddhandler} to initialize
+a handler, for example:
+
+\begin{verbatim}
+#include <wx/fs_mem.h>
+
+...
+
+bool MyApp::OnInit()
+{
+    wxFileSystem::AddHandler(new wxMemoryFSHandler);
+...
+}
+\end{verbatim}