]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/fs.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @page fs_overview wxFileSystem
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.
19 Three classes are used in order to provide virtual file systems mechanism:
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.
35 Locations (aka filenames aka addresses) are constructed from four parts:
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.
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:
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".
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:".
92 @b wxInternetFSHandler
97 A handler for accessing documents
98 via HTTP or FTP protocols. Include file is wx/fs_inet.h.
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.
119 In addition, wxFileSystem itself can access local files.
121 @b Initializing file system handlers
122 Use wxFileSystem::AddHandler to initialize
123 a handler, for example:
132 wxFileSystem::AddHandler(new wxMemoryFSHandler);