Add documentation for virtual file system support in wxWebView.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/SOC2011_WEBVIEW@68523 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/webfilehandler.h

@@ -0,0 +1,31 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        webfilehandler.h
+// Purpose:     interface of wxWebFileHandler
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxWebFileHandler
+  
+    A custom handler for the file scheme which also supports loading from 
+    archives. The syntax for wxWebFileHandler differs from virtual file 
+    systems in the rest of wxWidgets by using a syntax such as
+    @c file:///C:/exmaple/docs.zip;protocol=zip/main.htm Currently the only
+    supported protocol is @c zip. 
+   
+    @library{wxweb}
+    @category{web}
+    
+    @see wxWebView, wxWebHandler
+ */
+class wxWebFileHandler : public wxWebHandler
+{
+public:
+    /**
+        @return The string @c "file"
+    */
+    virtual wxString GetName() const;
+    virtual wxFSFile* GetFile(const wxString &uri);
+};

interface/wx/webview.h

@@ -116,6 +116,31 @@ public:
     wxString GetTitle();
 };
 
+/**
+    @class wxWebHandler
+  
+    The base class for handling custom schemes in wxWebView, for example to 
+    allow virtual file system support.
+   
+    @library{wxweb}
+    @category{web}
+    
+    @see wxWebView
+ */
+class wxWebHandler
+{
+public:
+    /**
+        @return A pointer to the file represented by @c uri.
+    */  
+    virtual wxFSFile* GetFile(const wxString &uri) = 0;
+
+    /**
+        @return The name of the scheme, for example @c file or @c http.
+    */
+    virtual wxString GetName() const = 0;
+};
+
 /**
     @class wxWebView
   
@@ -132,6 +157,20 @@ public:
     Note that errors are generally reported asynchronously though the
     @c wxEVT_COMMAND_WEB_VIEW_ERROR event described below.
     
+    @section vfs Virtual File Systems and Custom Schemes
+    
+    wxWebView supports the registering of custom scheme handlers, for example
+    @c file or @c http. To do this create a new class which inherits from 
+    wxWebHandler, where the wxWebHandler::GetName() method returns the scheme
+    you wish to handle and wxWebHandler::GetFile() returns a pointer to a 
+    wxFSFile which represents the given url. You can then register your handler
+    with RegisterHandler() it will be called for all pages and resources.
+    
+    wxWebFileHandler is provided to allow the navigation of pages inside a zip
+    archive. It overrides the @c file scheme and provides support for the 
+    standard @c file syntax as well as paths to archives of the form 
+    @c file:///C:/exmaple/docs.zip;protocol=zip/main.htm 
+  
     @beginEventEmissionTable{wxWebNavigationEvent}
     @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
        Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
@@ -164,6 +203,7 @@ public:
    
     @library{wxweb}
     @category{ctrl,web}
+    @see wxWebHandler, wxWebNavigationEvent
  */
 class wxWebView : public wxControl
 {
@@ -259,6 +299,12 @@ public:
     */
     virtual void Print() = 0;
     
+    /**
+        Registers a custom scheme handler.
+        @param handler A pointer to a heap allocated wxWebHandler.
+    */
+    virtual void RegisterHandler(wxWebHandler* handler) = 0;
+
     /**
         Reload the currently displayed URL.
         @param flags A bit array that may optionally contain reload options.