-\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
+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.wxwidgets.org/index.html" the right location is "//www.wxwidgets.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 a ZIP archive:
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", right location is
+"reference/fopen.htm", anchor is "syntax" and left location
+is "file:archives/cpp\_doc.zip".
-In fact there are two protocols used in this example : zip and file.
-You can construct even more complicated addresses like this one:
+There are {\bf two} protocols used in this example: "zip" and "file".
-http://www.archives.org/myarchive.zip\#zip:local/docs/cpp/stdio.zip\#zip:index.htm
+\wxheading{File Systems Included in wxHTML}
-In this example you access zip VFS stdio.zip stored in another zip (myarchive.zip)
-which is at WWW. Enjoy it :-)
+The following virtual file system handlers are part of wxWidgets so far:
-\wxheading{File Systems Included in wxHTML}
+\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>. URL 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>
+
+...
-\begin{enumerate}
-\item Local files
-\item HTTP protocol
-\item FTP protocol
-\item .ZIP archives
-\end{enumerate}
+bool MyApp::OnInit()
+{
+ wxFileSystem::AddHandler(new wxMemoryFSHandler);
+...
+}
+\end{verbatim}
projects / wxWidgets.git / blobdiff