From: Steve Lamerton <steve.lamerton@gmail.com>
Date: Thu, 4 Aug 2011 18:46:49 +0000 (+0000)
Subject: Add documentation for virtual file system support in wxWebView.
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/42be0c562b1dff1a58a913277f86c217ebc9cc0c

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
---

diff --git a/interface/wx/webfilehandler.h b/interface/wx/webfilehandler.h
new file mode 100644
index 0000000000..74dd8510b8
--- /dev/null
+++ b/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);
+};
\ No newline at end of file
diff --git a/interface/wx/webview.h b/interface/wx/webview.h
index cf5b9bd75a..2414f41e38 100644
--- a/interface/wx/webview.h
+++ b/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
   
@@ -131,6 +156,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)}
@@ -164,6 +203,7 @@ public:
    
     @library{wxweb}
     @category{ctrl,web}
+    @see wxWebHandler, wxWebNavigationEvent
  */
 class wxWebView : public wxControl
 {
@@ -258,6 +298,12 @@ public:
         displayed page.
     */
     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.