git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/filesystem.h

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: filesystem.h
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	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