From dec53e5a560eeaffd5927f000101dd473fd83c13 Mon Sep 17 00:00:00 2001 From: Steve Lamerton Date: Thu, 19 May 2011 18:28:01 +0000 Subject: [PATCH] Move wxWebView documentation into a separate interface file and add the wxWeb library to the libraries page git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/SOC2011_WEBVIEW@67764 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/libs.h | 8 + include/wx/webview.h | 38 ---- interface/wx/webview.h | 380 ++++++++++++++++++++++++++++++++++ 3 files changed, 388 insertions(+), 38 deletions(-) create mode 100644 interface/wx/webview.h diff --git a/docs/doxygen/mainpages/libs.h b/docs/doxygen/mainpages/libs.h index 88c682f776..27e1c24191 100644 --- a/docs/doxygen/mainpages/libs.h +++ b/docs/doxygen/mainpages/libs.h @@ -39,6 +39,7 @@ digraph Dependancies wxRichText [fillcolor = green, URL = "\ref page_libs_wxrichtext"]; wxSTC [fillcolor = green, URL = "\ref page_libs_wxstc"]; wxXRC [fillcolor = green, URL = "\ref page_libs_wxxrc"]; + wxWeb [fillcolor = green, URL = "\ref page_libs_wxweb"]; wxCore -> wxBase; wxNet -> wxBase; @@ -55,6 +56,7 @@ digraph Dependancies wxRichText -> wxAdvanced; wxRichText -> wxHTML; wxRichText -> wxXML; wxSTC -> wxCore; wxXRC -> wxAdvanced; wxXRC -> wxHTML; wxXRC -> wxXML; + wxWeb -> wxCore; } @enddot @@ -202,5 +204,11 @@ text editor. See for more info about Scintilla. Requires @ref page_libs_wxcore, @ref page_libs_wxbase. +@section page_libs_wxweb wxWeb + +The wxWeb library contains the wxWebView control. + +Requires @ref page_libs_wxcore, @ref page_libs_wxbase. + */ diff --git a/include/wx/webview.h b/include/wx/webview.h index 4cd6c89b2e..0382d5050f 100644 --- a/include/wx/webview.h +++ b/include/wx/webview.h @@ -96,44 +96,6 @@ enum wxWebViewBackend extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewNameStr[]; extern WXDLLIMPEXP_DATA_WEB(const char) wxWebViewDefaultURLStr[]; -/** - * @class wxWebView - * - * This control may be used to render web (HTML / CSS / javascript) documents. - * Capabilities of the HTML renderer will depend upon the backed. - * TODO: describe each backend and its capabilities here - * - * Note that errors are generally reported asynchronously though the - * wxEVT_COMMAND_WEB_VIEW_ERROR event described below. - * - * @beginEventEmissionTable{wxWebNavigationEvent} - * @event{EVT_BUTTON(id, func)} - * - * @event{EVT_WEB_VIEW_NAVIGATING(id, func)} - * Process a wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying - * to get a resource. This event may be vetoed to prevent navigating to this - * resource. Note that if the displayed HTML document has several frames, one - * such event will be generated per frame. - * - * @event{EVT_WEB_VIEW_NAVIGATED(id, func)} - * Process a wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was - * confirmed that a resource would be requested. This event may not be vetoed. - * Note that if the displayed HTML document has several frames, one such event - * will be generated per frame. - * - * @event{EVT_WEB_VIEW_LOADED(id, func)} - * Process a wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document - * is fully loaded and displayed. - * - * @event{EVT_WEB_VIEW_ERRROR(id, func)} - * Process a wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation - * error occurs. - * The integer associated with this event will be a wxWebNavigationError item. - * The string associated with this event may contain a backend-specific more - * precise error message/code. - * - * @endEventTable - */ class WXDLLIMPEXP_WEB wxWebView : public wxControl { public: diff --git a/interface/wx/webview.h b/interface/wx/webview.h new file mode 100644 index 0000000000..b3f47cc133 --- /dev/null +++ b/interface/wx/webview.h @@ -0,0 +1,380 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: webview.h +// Purpose: interface of wxWebView +// Author: wxWidgets team +// RCS-ID: $Id:$ +// Licence: wxWindows licence +///////////////////////////////////////////////////////////////////////////// + +/** + Zoom levels availiable in wxWebView +*/ +enum wxWebViewZoom +{ + wxWEB_VIEW_ZOOM_TINY, + wxWEB_VIEW_ZOOM_SMALL, + wxWEB_VIEW_ZOOM_MEDIUM, //!< default size + wxWEB_VIEW_ZOOM_LARGE, + wxWEB_VIEW_ZOOM_LARGEST +}; + +/** + The type of zooming that the web view control can perform +*/ +enum wxWebViewZoomType +{ + /** + The entire layout scales when zooming, including images + */ + wxWEB_VIEW_ZOOM_TYPE_LAYOUT, + /** + Only the text changes in size when zooming, images and other layout + elements retain their initial size + */ + wxWEB_VIEW_ZOOM_TYPE_TEXT +}; + +/** + Types of errors that can cause navigation to fail +*/ +enum wxWebNavigationError +{ + /** Connection error (timeout, etc.) */ + wxWEB_NAV_ERR_CONNECTION = 1, + /** Invalid certificate */ + wxWEB_NAV_ERR_CERTIFICATE = 2, + /** Authentication required */ + wxWEB_NAV_ERR_AUTH = 3, + /** Other security error */ + wxWEB_NAV_ERR_SECURITY = 4, + /** Requested resource not found */ + wxWEB_NAV_ERR_NOT_FOUND = 5, + /** Invalid request/parameters (e.g. bad URL, bad protocol, + unsupported resource type) */ + wxWEB_NAV_ERR_REQUEST = 6, + /** The user cancelled (e.g. in a dialog) */ + wxWEB_NAV_ERR_USER_CANCELLED = 7, + /** Another (exotic) type of error that didn't fit in other categories*/ + wxWEB_NAV_ERR_OTHER = 8 +}; + +/** + Type of refresh +*/ +enum wxWebViewReloadFlags +{ + /** Default reload, will access cache */ + wxWEB_VIEW_RELOAD_DEFAULT = 0, + /** Reload the current view without accessing the cache */ + wxWEB_VIEW_RELOAD_NO_CACHE +}; + + +/** + * List of available backends for wxWebView + */ +enum wxWebViewBackend +{ + /** Value that may be passed to wxWebView to let it pick an appropriate + * engine for the current platform*/ + wxWEB_VIEW_BACKEND_DEFAULT, + + /** The OSX-native WebKit web engine */ + wxWEB_VIEW_BACKEND_OSX_WEBKIT, + + /** The GTK port of the WebKit engine */ + wxWEB_VIEW_BACKEND_GTK_WEBKIT, + + /** Use Microsoft Internet Explorer as web engine */ + wxWEB_VIEW_BACKEND_IE +}; + +/** + @class wxWebView + + This control may be used to render web (HTML / CSS / javascript) documents. + Capabilities of the HTML renderer will depend upon the backed. + TODO: describe each backend and its capabilities here + + Note that errors are generally reported asynchronously though the + @c wxEVT_COMMAND_WEB_VIEW_ERROR event described below. + + @beginEventEmissionTable{wxWebNavigationEvent} + @event{EVT_WEB_VIEW_NAVIGATING(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying + to get a resource. This event may be vetoed to prevent navigating to this + resource. Note that if the displayed HTML document has several frames, one + such event will be generated per frame. + @event{EVT_WEB_VIEW_NAVIGATED(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was + confirmed that a resource would be requested. This event may not be vetoed. + Note that if the displayed HTML document has several frames, one such event + will be generated per frame. + @event{EVT_WEB_VIEW_LOADED(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document + is fully loaded and displayed. + @event{EVT_WEB_VIEW_ERRROR(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation + error occurs. + The integer associated with this event will be a wxWebNavigationError item. + The string associated with this event may contain a backend-specific more + precise error message/code. + @endEventTable + + @library{wxweb} + @category{ctrl} + */ +class wxWebView : public wxControl +{ +public: + + /** + Creation function for two-step creation. + */ + virtual bool Create(wxWindow* parent, + wxWindowID id, + const wxString& url, + const wxPoint& pos, + const wxSize& size, + long style, + const wxString& name) = 0; + + /** + Factory function to create a new wxWebView for two-step creation + (you need to call wxWebView::Create on the returned object) + @param backend which web engine to use as backend for wxWebView + @return the created wxWebView, or NULL if the requested backend is + not available + */ + static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT); + + /** + Factory function to create a new wxWebView + @param parent parent window to create this view in + @param id ID of this control + @param url URL to load by default in the web view + @param pos position to create this control at + (you may use wxDefaultPosition if you use sizers) + @param size size to create this control with + (you may use wxDefaultSize if you use sizers) + @param backend which web engine to use as backend for wxWebView + @return the created wxWebView, or NULL if the requested backend + is not available + */ + static wxWebView* New(wxWindow* parent, + wxWindowID id, + const wxString& url = wxWebViewDefaultURLStr, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT, + long style = 0, + const wxString& name = wxWebViewNameStr); + + + /** + Get whether it is possible to navigate back in the history of + visited pages + */ + virtual bool CanGoBack() = 0; + + /** + Get whether it is possible to navigate forward in the history of + visited pages + */ + virtual bool CanGoForward() = 0; + + /** + Navigate back in the history of visited pages. + Only valid if CanGoBack() returned true. + */ + virtual void GoBack() = 0; + + /** + Navigate forwardin the history of visited pages. + Only valid if CanGoForward() returned true. + */ + virtual void GoForward() = 0; + + /** + Load a HTMl document (web page) from a URL + @param url the URL where the HTML document to display can be found + @note web engines generally report errors asynchronously, so if you wish + to know whether loading the URL was successful, register to receive + navigation error events + */ + virtual void LoadUrl(const wxString& url) = 0; + + /** + Stop the current page loading process, if any. + May trigger an error event of type @c wxWEB_NAV_ERR_USER_CANCELLED. + TODO: make @c wxWEB_NAV_ERR_USER_CANCELLED errors uniform across ports. + */ + virtual void Stop() = 0; + + /** + Reload the currently displayed URL. + @param flags A bit array that may optionnally contain reload options + */ + virtual void Reload(wxWebViewReloadFlags flags = wxWEB_VIEW_RELOAD_DEFAULT) = 0; + + + /** + Get the URL of the currently displayed document + */ + virtual wxString GetCurrentURL() = 0; + + /** + Get the title of the current web page, or its URL/path if title is not + available + */ + virtual wxString GetCurrentTitle() = 0; + + /** + Get the HTML source code of the currently displayed document + @return the HTML source code, or an empty string if no page is currently + shown + */ + virtual wxString GetPageSource() = 0; + + /** + Get the zoom factor of the page + @return How much the HTML document is zoomed (scaleed) + */ + virtual wxWebViewZoom GetZoom() = 0; + + /** + Set the zoom factor of the page + @param zoom How much to zoom (scale) the HTML document + */ + virtual void SetZoom(wxWebViewZoom zoom) = 0; + + /** + Set how to interpret the zoom factor + @param zoomType how the zoom factor should be interpreted by the + HTML engine + @note invoke canSetZoomType() first, some HTML renderers may not + support all zoom types + */ + virtual void SetZoomType(wxWebViewZoomType zoomType) = 0; + + /** + Get how the zoom factor is currently interpreted + @return how the zoom factor is currently interpreted by the HTML engine + */ + virtual wxWebViewZoomType GetZoomType() const = 0; + + /** + Retrieve whether the current HTML engine supports a type of zoom + @param type the type of zoom to test + @return whether this type of zoom is supported by this HTML engine + (and thus can be set through setZoomType()) + */ + virtual bool CanSetZoomType(wxWebViewZoomType type) const = 0; + + /** + Set the displayed page source to the contents of the given string + @param html the string that contains the HTML data to display + @param baseUrl URL assigned to the HTML data, to be used to resolve + relative paths, for instance + */ + virtual void SetPage(const wxString& html, const wxString& baseUrl) = 0; + + /** + Set the displayed page source to the contents of the given stream + @param html the stream to read HTML data from + @param baseUrl URL assigned to the HTML data, to be used to resolve + relative paths, for instance + */ + virtual void SetPage(wxInputStream& html, wxString baseUrl) + { + wxStringOutputStream stream; + stream.Write(html); + SetPage(stream.GetString(), baseUrl); + } + + /** + Opens a print dialog so that the user may print the currently + displayed page. + */ + virtual void Print() = 0; + + /** + Returns whether the web control is currently busy (e.g. loading a page) + */ + virtual bool IsBusy() = 0; +}; + + + + +/** + @class wxWebNavigationEvent + + A navigation event holds information about events associated with + wxWebView objects. + + @beginEventEmissionTable{wxWebNavigationEvent} + @event{EVT_WEB_VIEW_NAVIGATING(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying + to get a resource. This event may be vetoed to prevent navigating to this + resource. Note that if the displayed HTML document has several frames, one + such event will be generated per frame. + @event{EVT_WEB_VIEW_NAVIGATED(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATED event generated after it was + confirmed that a resource would be requested. This event may not be vetoed. + Note that if the displayed HTML document has several frames, one such event + will be generated per frame. + @event{EVT_WEB_VIEW_LOADED(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_LOADED event generated when the document + is fully loaded and displayed. + @event{EVT_WEB_VIEW_ERRROR(id, func)} + Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation + error occurs. + The integer associated with this event will be a wxWebNavigationError item. + The string associated with this event may contain a backend-specific more + precise error message/code. + @endEventTable + + @library{wxweb} + @category{events} + + @see wxWebView +*/ +class wxWebNavigationEvent : public wxCommandEvent +{ +public: + wxWebNavigationEvent(); + wxWebNavigationEvent(wxEventType type, int id, const wxString href, + const wxString target, bool canVeto); + /** + Get the URL being visited + */ + const wxString& GetHref() const { return m_href; } + + /** + Get the target (frame or window) in which the URL that caused this event + is viewed, or an empty string if not available. + */ + const wxString& GetTarget() const; + + // default copy ctor, assignment operator and dtor are ok + virtual wxEvent* Clone() const; + + /** + Get whether this event may be vetoed (stopped/prevented). Only + meaningful for events fired before navigation takes place. + */ + bool CanVeto() const; + + /** + Whether this event was vetoed (stopped/prevented). Only meaningful for + events fired before navigation takes place. + */ + bool IsVetoed() const; + + /** + Veto (prevent/stop) this event. Only meaningful for events fired + before navigation takes place. Only valid if CanVeto() returned true. + */ + void Veto(); +}; \ No newline at end of file