docs/doxygen/overviews/filesystem.h

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