docs/doxygen/overviews/fs.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        fs
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page fs_overview wxFileSystem
  12
  13  The wxHTML library uses a @b virtual file systems mechanism
  14  similar to the one used in Midnight Commander, Dos Navigator,
  15  FAR or almost any modern file manager. It allows the user to access
  16  data stored in archives as if they were ordinary files. On-the-fly
  17  generated files that exist only in memory are also supported.
  18  @b Classes
  19  Three classes are used in order to provide virtual file systems mechanism:
  20
  21
  22   The #wxFSFile class provides information
  23  about opened file (name, input stream, mime type and anchor).
  24   The #wxFileSystem class is the interface.
  25  Its main methods are ChangePathTo() and OpenFile(). This class
  26  is most often used by the end user.
  27   The #wxFileSystemHandler is the core
  28  of virtual file systems mechanism. You can derive your own handler and pass it to
  29  the VFS mechanism. You can derive your own handler and pass it to
  30  wxFileSystem's AddHandler() method. In the new handler you only need to
  31  override the OpenFile() and CanOpen() methods.
  32
  33
  34  @b Locations
  35  Locations (aka filenames aka addresses) are constructed from four parts:
  36
  37
  38   @b protocol - handler can recognize if it is able to open a
  39  file by checking its protocol. Examples are "http", "file" or "ftp".
  40   @b right location - is the name of file within the protocol.
  41  In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
  42   @b anchor - an anchor is optional and is usually not present.
  43  In "index.htm#chapter2" the anchor is "chapter2".
  44   @b left location - this is usually an empty string.
  45  It is used by 'local' protocols such as ZIP.
  46  See Combined Protocols paragraph for details.
  47
  48
  49  @b Combined Protocols
  50  The left location precedes the protocol in the URL string.
  51  It is not used by global protocols like HTTP but it becomes handy when nesting
  52  protocols - for example you may want to access files in a ZIP archive:
  53  file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax
  54  In this example, the protocol is "zip", right location is
  55  "reference/fopen.htm", anchor is "syntax" and left location
  56  is "file:archives/cpp_doc.zip".
  57  There are @b two protocols used in this example: "zip" and "file".
  58  @b File Systems Included in wxHTML
  59  The following virtual file system handlers are part of wxWidgets so far:
  60
  61
  62
  63
  64
  65
  66  @b wxArchiveFSHandler
  67
  68
  69
  70
  71  A handler for archives such as zip
  72  and tar. Include file is wx/fs_arc.h. URLs examples:
  73  "archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
  74
  75
  76
  77
  78
  79  @b wxFilterFSHandler
  80
  81
  82
  83
  84  A handler for compression schemes such
  85  as gzip. Header is wx/fs_filter.h. URLs are in the form, e.g.:
  86  "document.ps.gz#gzip:".
  87
  88
  89
  90
  91
  92  @b wxInternetFSHandler
  93
  94
  95
  96
  97  A handler for accessing documents
  98  via HTTP or FTP protocols. Include file is wx/fs_inet.h.
  99
 100
 101
 102
 103
 104  @b wxMemoryFSHandler
 105
 106
 107
 108
 109  This handler allows you to access
 110  data stored in memory (such as bitmaps) as if they were regular files.
 111  See @ref memoryfshandler_overview for details.
 112  Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g.
 113  "memory:myfile.htm"
 114
 115
 116
 117
 118
 119  In addition, wxFileSystem itself can access local files.
 120
 121  @b Initializing file system handlers
 122  Use wxFileSystem::AddHandler to initialize
 123  a handler, for example:
 124
 125  @code
 126  #include wx/fs_mem.h
 127
 128  ...
 129
 130  bool MyApp::OnInit()
 131  {
 132      wxFileSystem::AddHandler(new wxMemoryFSHandler);
 133  ...
 134  }
 135  @endcode
 136
 137  */
 138
 139