docs/latex/wx/fs.tex

   1 \section{wxFileSystem}\label{fs}
   2
   3 The wxHTML library uses a {\bf virtual file systems} mechanism
   4 similar to the one used in Midnight Commander, Dos Navigator,
   5 FAR or almost any modern file manager. It allows the user to access
   6 data stored in archives as if they were ordinary files. On-the-fly
   7 generated files that exist only in memory are also supported.
   8
   9 \wxheading{Classes}
  10
  11 Three classes are used in order to provide virtual file systems mechanism:
  12
  13 \begin{itemize}\itemsep=0pt
  14 \item The \helpref{wxFSFile}{wxfsfile} class provides information
  15 about opened file (name, input stream, mime type and anchor).
  16 \item The \helpref{wxFileSystem}{wxfilesystem} class is the interface.
  17 Its main methods are ChangePathTo() and OpenFile(). This class
  18 is most often used by the end user.
  19 \item The \helpref{wxFileSystemHandler}{wxfilesystemhandler} is the core
  20 of virtual file systems mechanism. You can derive your own handler and pass it to
  21 the VFS mechanism. You can derive your own handler and pass it to
  22 wxFileSystem's AddHandler() method. In the new handler you only need to
  23 override the OpenFile() and CanOpen() methods.
  24 \end{itemize}
  25
  26 \wxheading{Locations}
  27
  28 Locations (aka filenames aka addresses) are constructed from four parts:
  29
  30 \begin{itemize}\itemsep=0pt
  31 \item {\bf protocol} - handler can recognize if it is able to open a
  32 file by checking its protocol. Examples are "http", "file" or "ftp".
  33 \item {\bf right location} - is the name of file within the protocol.
  34 In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
  35 \item {\bf anchor} - an anchor is optional and is usually not present.
  36 In "index.htm\#chapter2" the anchor is "chapter2".
  37 \item {\bf left location} - this is usually an empty string.
  38 It is used by 'local' protocols such as ZIP.
  39 See Combined Protocols paragraph for details.
  40 \end{itemize}
  41
  42 \wxheading{Combined Protocols}
  43
  44 The left location precedes the protocol in the URL string.
  45 It is not used by global protocols like HTTP but it becomes handy when nesting
  46 protocols - for example you may want to access files in a ZIP archive:
  47
  48 file:archives/cpp\_doc.zip\#zip:reference/fopen.htm\#syntax
  49
  50 In this example, the protocol is "zip", right location is
  51 "reference/fopen.htm", anchor is "syntax" and left location
  52 is "file:archives/cpp\_doc.zip".
  53
  54 There are {\bf two} protocols used in this example: "zip" and "file".
  55
  56 \wxheading{File Systems Included in wxHTML}
  57
  58 The following virtual file system handlers are part of wxWidgets so far:
  59
  60 \begin{twocollist}
  61 \twocolitem{{\bf wxInternetFSHandler}}{A handler for accessing documents
  62 via HTTP or FTP protocols. Include file is <wx/fs\_inet.h>.}
  63 \twocolitem{{\bf wxZipFSHandler}}{A handler for ZIP archives.
  64 Include file is <wx/fs\_zip.h>. URL is in form "archive.zip\#zip:filename".}
  65 \twocolitem{{\bf wxMemoryFSHandler}}{This handler allows you to access
  66 data stored in memory (such as bitmaps) as if they were regular files.
  67 See \helpref{wxMemoryFSHandler documentation}{wxmemoryfshandler} for details.
  68 Include file is <wx/fs\_mem.h>. URL is prefixed with memory:, e.g.
  69 "memory:myfile.htm"}
  70 \end{twocollist}
  71
  72 In addition, wxFileSystem itself can access local files.
  73
  74
  75 \wxheading{Initializing file system handlers}
  76
  77 Use \helpref{wxFileSystem::AddHandler}{wxfilesystemaddhandler} to initialize
  78 a handler, for example:
  79
  80 \begin{verbatim}
  81 #include <wx/fs_mem.h>
  82
  83 ...
  84
  85 bool MyApp::OnInit()
  86 {
  87     wxFileSystem::AddHandler(new wxMemoryFSHandler);
  88 ...
  89 }
  90 \end{verbatim}
  91