X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/22d6efa851642c6a69174278fc50f712f41e2271..11ef729d54ee338a1d569b5a238c2feb84d488ff:/docs/latex/wx/fs.tex diff --git a/docs/latex/wx/fs.tex b/docs/latex/wx/fs.tex index 5488d876f6..c8f80148b8 100644 --- a/docs/latex/wx/fs.tex +++ b/docs/latex/wx/fs.tex @@ -1,37 +1,38 @@ -\section{File Systems}\label{fs} +\section{wxFileSystem}\label{fs} 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. (Do you remember? You can -press enter on ZIP file and its contents is displayed as if it -were a local directory...) +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}\itemsep=0pt \item The \helpref{wxFSFile}{wxfsfile} class provides information -on opened file (name, input stream, mime type and anchor). +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 The \helpref{wxFileSystemHandler}{wxfilesystemhandler} is the core -if VFS mechanism. You can derive your own handler and pass it to +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: +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 "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. @@ -40,31 +41,51 @@ See Combined Protocols paragraph for details. \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. +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 .} +\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 . 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 + +... -\begin{enumerate}\itemsep=0pt -\item Local files -\item HTTP protocol -\item FTP protocol -\item .ZIP archives -\end{enumerate} +bool MyApp::OnInit() +{ + wxFileSystem::AddHandler(new wxMemoryFSHandler); +... +} +\end{verbatim}