X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/704a4b7524e05d7bf4d208eb1b30be9989abef4c..bf7945cef10c0844a32e95695c544d829da9293a:/docs/latex/wx/fs.tex diff --git a/docs/latex/wx/fs.tex b/docs/latex/wx/fs.tex index a183aa63a4..671a65c52c 100644 --- a/docs/latex/wx/fs.tex +++ b/docs/latex/wx/fs.tex @@ -1,75 +1,91 @@ -\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 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", 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. -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 wxWindows 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 .} +\twocolitem{{\bf wxZipFSHandler}}{A handler for ZIP archives. +Include file is . 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 . 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 + +... -\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}