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. (Do you remember? You can
   6 press enter on ZIP file and its contents is displayed as if it
   7 were a local directory...)
   8
   9 \wxheading{Classes}
  10
  11 Three classes are used in order to provide full VFS:
  12
  13 \begin{itemize}\itemsep=0pt
  14 \item The \helpref{wxFSFile}{wxfsfile} class provides information
  15 on 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 if VFS mechanism. You can derive your own handler and pass it to
  21 wxFileSystem's AddHandler() method. In the new handler you only need to
  22 overwrite OpenFile() and CanOpen() methods.
  23 \end{itemize}
  24
  25 \wxheading{Locations}
  26
  27 Locations (aka filenames aka addresses) are constructed from 4 parts:
  28
  29 \begin{itemize}\itemsep=0pt
  30 \item {\bf protocol} - handler can recognize if it is able to open a
  31 file by checking its protocol. Examples are "http", "file" or "ftp".
  32 \item {\bf right location} - is the name of file within the protocol.
  33 In "http://www.wxwindows.org/index.html" the right location is "//www.wxwindows.org/index.html".
  34 \item {\bf anchor} - anchor is optional and is usually not present.
  35 In "index.htm\#chapter2" the anchor is "chapter2".
  36 \item {\bf left location} - this is usually an empty string.
  37 It is used by 'local' protocols such as ZIP.
  38 See Combined Protocols paragraph for details.
  39 \end{itemize}
  40
  41 \wxheading{Combined Protocols}
  42
  43 Left location pretends protocol in URL string.
  44 It's not used by global protocols like HTTP but it's used
  45 by local ones - for example you can see this address:
  46
  47 file:archives/cpp\_doc.zip\#zip:reference/fopen.htm\#syntax
  48
  49 In this example, protocol is "zip", left location is
  50 "reference/fopen.htm", anchor is "syntax" and right location
  51 is "file:archives/cpp\_doc.zip". It is used by zip handler
  52 to determine in what file this particular zip VFS is stored.
  53
  54 In fact there are two protocols used in this example: zip and file.
  55 You can construct even more complicated addresses like this one:
  56
  57 http://www.archives.org/myarchive.zip\#zip:local/docs/cpp/stdio.zip\#zip:index.htm
  58
  59 In this example you access zip VFS stdio.zip stored in another zip (myarchive.zip)
  60 which is at WWW.
  61
  62 \wxheading{File Systems Included in wxHTML}
  63
  64 Following VFS handlers are part of wxWindows so far:
  65
  66 \begin{twocollist}
  67 \twocolitem{{\bf wxInternetFSHandler}}{Handler for accessing documents
  68 via HTTP or FTP protocols. Include file is <wx/fs_inet.h>.}
  69 \twocolitem{{\bf wxZipFSHandler}}{Handler for ZIP archives.
  70 Include file is <wx/fs_zip.h>. URL is in form "archive.zip\#zip:filename".}
  71 \twocolitem{{\bf wxMemoryFSHandler}}{This handler allows you to access
  72 data stored in memory (such as bitmaps) as if they were regular files.
  73 See \helpref{wxMemoryFSHandler documentation}{wxmemoryfshandler} for details.
  74 Include file is <wx/fs_mem.h>. UURL is prefixed with memory:, e.g.
  75 "memory:myfile.htm"}
  76 \end{twocollist}
  77
  78 In addition, wxFileSystem can access local files.
  79
  80
  81 Use \helpref{wxFileSystem::AddHandler}{wxfilesystemaddhandler} to initialize
  82 a handler, for example:
  83
  84 \begin{verbatim}
  85 #include <wx/fs_mem.h>
  86
  87 ...
  88
  89 bool MyApp::OnInit()
  90 {
  91     wxFileSystem::AddHandler(new wxMemoryFSHandler);
  92 ...
  93 \end{verbatim}
  94
  95
  96