← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to docs/doxygen/overviews/filesystem.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

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