// Name: webview.h
// Purpose: interface of wxWebView
// Author: wxWidgets team
-// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
*/
enum wxWebViewZoom
{
- wxWEB_VIEW_ZOOM_TINY,
- wxWEB_VIEW_ZOOM_SMALL,
- wxWEB_VIEW_ZOOM_MEDIUM, //!< default size
- wxWEB_VIEW_ZOOM_LARGE,
- wxWEB_VIEW_ZOOM_LARGEST
+ wxWEBVIEW_ZOOM_TINY,
+ wxWEBVIEW_ZOOM_SMALL,
+ wxWEBVIEW_ZOOM_MEDIUM, //!< default size
+ wxWEBVIEW_ZOOM_LARGE,
+ wxWEBVIEW_ZOOM_LARGEST
};
/**
/**
The entire layout scales when zooming, including images
*/
- wxWEB_VIEW_ZOOM_TYPE_LAYOUT,
+ wxWEBVIEW_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
+ wxWEBVIEW_ZOOM_TYPE_TEXT
};
/**
enum wxWebViewNavigationError
{
/** Connection error (timeout, etc.) */
- wxWEB_NAV_ERR_CONNECTION,
+ wxWEBVIEW_NAV_ERR_CONNECTION,
/** Invalid certificate */
- wxWEB_NAV_ERR_CERTIFICATE,
+ wxWEBVIEW_NAV_ERR_CERTIFICATE,
/** Authentication required */
- wxWEB_NAV_ERR_AUTH,
+ wxWEBVIEW_NAV_ERR_AUTH,
/** Other security error */
- wxWEB_NAV_ERR_SECURITY,
+ wxWEBVIEW_NAV_ERR_SECURITY,
/** Requested resource not found */
- wxWEB_NAV_ERR_NOT_FOUND,
+ wxWEBVIEW_NAV_ERR_NOT_FOUND,
/** Invalid request/parameters (e.g. bad URL, bad protocol,
unsupported resource type) */
- wxWEB_NAV_ERR_REQUEST,
+ wxWEBVIEW_NAV_ERR_REQUEST,
/** The user cancelled (e.g. in a dialog) */
- wxWEB_NAV_ERR_USER_CANCELLED,
+ wxWEBVIEW_NAV_ERR_USER_CANCELLED,
/** Another (exotic) type of error that didn't fit in other categories*/
- wxWEB_NAV_ERR_OTHER
+ wxWEBVIEW_NAV_ERR_OTHER
};
/**
enum wxWebViewReloadFlags
{
/** Default reload, will access cache */
- wxWEB_VIEW_RELOAD_DEFAULT,
+ wxWEBVIEW_RELOAD_DEFAULT,
/** Reload the current view without accessing the cache */
- wxWEB_VIEW_RELOAD_NO_CACHE
+ wxWEBVIEW_RELOAD_NO_CACHE
};
/**
enum wxWebViewFindFlags
{
/** Causes the search to restart when end or beginning reached */
- wxWEB_VIEW_FIND_WRAP = 0x0001,
+ wxWEBVIEW_FIND_WRAP = 0x0001,
/** Matches an entire word when searching */
- wxWEB_VIEW_FIND_ENTIRE_WORD = 0x0002,
+ wxWEBVIEW_FIND_ENTIRE_WORD = 0x0002,
/** Match case, i.e. case sensitive searching */
- wxWEB_VIEW_FIND_MATCH_CASE = 0x0004,
+ wxWEBVIEW_FIND_MATCH_CASE = 0x0004,
/** Highlights the search results */
- wxWEB_VIEW_FIND_HIGHLIGHT_RESULT = 0x0008,
+ wxWEBVIEW_FIND_HIGHLIGHT_RESULT = 0x0008,
/** Searches for phrase in backward direction */
- wxWEB_VIEW_FIND_BACKWARDS = 0x0010,
+ wxWEBVIEW_FIND_BACKWARDS = 0x0010,
/** The default flag, which is simple searching */
- wxWEB_VIEW_FIND_DEFAULT = 0
+ wxWEBVIEW_FIND_DEFAULT = 0
};
-/**
- * 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 WebKit web engine */
- wxWEB_VIEW_BACKEND_WEBKIT,
-
- /** Use Microsoft Internet Explorer as web engine */
- wxWEB_VIEW_BACKEND_IE
-};
/**
@class wxWebViewHistoryItem
wxString GetTitle();
};
+/**
+ @class wxWebViewFactory
+
+ An abstract factory class for creating wxWebView backends. Each
+ implementation of wxWebView should have its own factory.
+
+ @since 2.9.5
+ @library{wxwebview}
+ @category{webview}
+
+ @see wxWebView
+ */
+class wxWebViewFactory : public wxObject
+{
+public:
+ /**
+ Function to create a new wxWebView with two-step creation,
+ wxWebView::Create should be called on the returned object.
+ @return the created wxWebView
+ */
+ virtual wxWebView* Create() = 0;
+
+ /**
+ Function to create a new wxWebView with parameters.
+ @param parent Parent window for the control
+ @param id ID of this control
+ @param url Initial URL to load
+ @param pos Position of the control
+ @param size Size of the control
+ @param style
+ Window style. For generic window styles, please see wxWindow.
+ @param name Window name.
+ @return the created wxWebView
+ */
+ virtual wxWebView* Create(wxWindow* parent,
+ wxWindowID id,
+ const wxString& url = wxWebViewDefaultURLStr,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = 0,
+ const wxString& name = wxWebViewNameStr) = 0;
+};
+
/**
@class wxWebViewHandler
@section descriptions Backend Descriptions
- @par wxWEB_VIEW_BACKEND_IE (MSW)
+ @par wxWEBVIEW_BACKEND_IE (MSW)
The IE backend uses Microsoft's Trident rendering engine, specifically the
version used by the locally installed copy of Internet Explorer. As such it
this</a> article for more information. This backend has full support for
custom schemes and virtual file systems.
- @par wxWEB_VIEW_WEBKIT (GTK)
+ @par wxWEBVIEW_WEBKIT (GTK)
Under GTK the WebKit backend uses
<a href="http://webkitgtk.org/">WebKitGTK+</a>. The current minimum version
resources such as images and stylesheets are currently loaded using the
data:// scheme.
- @par wxWEB_VIEW_WEBKIT (OSX)
+ @par wxWEBVIEW_WEBKIT (OSX)
The OSX WebKit backend uses Apple's
<a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/WebKit/Classes/WebView_Class/Reference/Reference.html#//apple_ref/doc/uid/20001903">WebView</a>
Many of the methods in wxWebView are asynchronous, i.e. they return
immediately and perform their work in the background. This includes
- functions such as LoadUrl() and Reload(). To receive notification of the
+ functions such as LoadURL() and Reload(). To receive notification of the
progress and completion of these functions you need to handle the events
- that are provided. Specifically @c wxEVT_COMMAND_WEB_VIEW_LOADED notifies
+ that are provided. Specifically @c wxEVT_WEBVIEW_LOADED notifies
when the page or a sub-frame has finished loading and
- @c wxEVT_COMMAND_WEB_VIEW_ERROR notifies that an error has occurred.
+ @c wxEVT_WEBVIEW_ERROR notifies that an error has occurred.
@section vfs Virtual File Systems and Custom Schemes
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:/example/docs.zip;protocol=zip/main.htm
+ wxWebViewFSHandler is provided to access the virtual file system encapsulated by
+ wxFileSystem. The wxMemoryFSHandler documentation gives an example of how this
+ may be used.
+
+ wxWebViewArchiveHandler is provided to allow the navigation of pages inside a zip
+ archive. It supports paths of the form:
+ @c scheme:///C:/example/docs.zip;protocol=zip/main.htm
@beginEventEmissionTable{wxWebViewEvent}
- @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
+ @event{EVT_WEBVIEW_NAVIGATING(id, func)}
+ Process a @c wxEVT_WEBVIEW_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
+ @event{EVT_WEBVIEW_NAVIGATED(id, func)}
+ Process a @c wxEVT_WEBVIEW_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
+ @event{EVT_WEBVIEW_LOADED(id, func)}
+ Process a @c wxEVT_WEBVIEW_LOADED event generated when the document
is fully loaded and displayed. Note that if the displayed HTML document has
several frames, one such event will be generated per frame.
- @event{EVT_WEB_VIEW_ERROR(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
+ @event{EVT_WEBVIEW_ERROR(id, func)}
+ Process a @c wxEVT_WEBVIEW_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.
- @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
+ @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
+ Process a @c wxEVT_WEBVIEW_NEWWINDOW event, generated when a new
window is created. You must handle this event if you want anything to
happen, for example to load the page in a new window or tab.
- @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
+ @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
+ Process a @c wxEVT_WEBVIEW_TITLE_CHANGED event, generated when
the page title changes. Use GetString to get the title.
@endEventTable
const wxString& name = wxWebViewNameStr) = 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
+ Factory function to create a new wxWebView with two-step creation,
+ wxWebView::Create should be called on the returned object.
+ @param backend The backend web rendering engine to use.
+ @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
+ @c wxWebViewBackendWebKit are predefined where appropriate.
+ @return The created wxWebView
+ @since 2.9.5
*/
- static wxWebView* New(wxWebViewBackend backend = wxWEB_VIEW_BACKEND_DEFAULT);
-
+ static wxWebView* New(const wxString& backend = wxWebViewBackendDefault);
+
/**
- Factory function to create a new wxWebView
- @param parent parent window to create this view in
+ Factory function to create a new wxWebView using a wxWebViewFactory.
+ @param parent Parent window for the control
@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
+ @param url Initial URL to load
+ @param pos Position of the control
+ @param size Size of the control
+ @param backend The backend web rendering engine to use.
+ @c wxWebViewBackendDefault, @c wxWebViewBackendIE and
+ @c wxWebViewBackendWebKit are predefined where appropriate.
+ @param style
+ Window style. For generic window styles, please see wxWindow.
+ @param name Window name.
+ @return The created wxWebView, or @c NULL if the requested backend
is not available
+ @since 2.9.5
*/
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);
+ wxWindowID id,
+ const wxString& url = wxWebViewDefaultURLStr,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ const wxString& backend = wxWebViewBackendDefault,
+ long style = 0,
+ const wxString& name = wxWebViewNameStr);
+
+ /**
+ Allows the registering of new backend for wxWebView. @a backend can be
+ used as an argument to New().
+ @param backend The name for the new backend to be registered under
+ @param factory A shared pointer to the factory which creates the
+ appropriate backend.
+ @since 2.9.5
+ */
+ static void RegisterFactory(const wxString& backend,
+ wxSharedPtr<wxWebViewFactory> factory);
/**
Get the title of the current web page, or its URL/path if title is not
virtual wxString GetPageText() const = 0;
/**
- Returns whether the web control is currently busy (e.g. loading a page).
+ Returns whether the web control is currently busy (e.g.\ loading a page).
*/
virtual bool IsBusy() const = 0;
Reload the currently displayed URL.
@param flags A bit array that may optionally contain reload options.
*/
- virtual void Reload(wxWebViewReloadFlags flags = wxWEB_VIEW_RELOAD_DEFAULT) = 0;
+ virtual void Reload(wxWebViewReloadFlags flags = wxWEBVIEW_RELOAD_DEFAULT) = 0;
/**
Runs the given javascript code.
+ @note When using wxWEBVIEW_BACKEND_IE you must wait for the current
+ page to finish loading before calling RunScript().
*/
virtual void RunScript(const wxString& javascript) = 0;
@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.
+ @note When using @c wxWEBVIEW_BACKEND_IE you must wait for the current
+ page to finish loading before calling SetPage(). The baseURL
+ parameter is not used in this backend.
*/
virtual void SetPage(const wxString& html, const wxString& baseUrl) = 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.
+ May trigger an error event of type @c wxWEBVIEW_NAV_ERR_USER_CANCELLED.
+ TODO: make @c wxWEBVIEW_NAV_ERR_USER_CANCELLED errors uniform across ports.
*/
virtual void Stop() = 0;
*/
virtual void Paste() = 0;
+ /**
+ @name Context Menu
+ */
+
+ /**
+ Enable or disable the right click context menu.
+
+ By default the standard context menu is enabled, this method can be
+ used to disable it or re-enable it later.
+
+ @since 2.9.5
+ */
+ virtual void EnableContextMenu(bool enable = true);
+
+ /**
+ Returns @true if a context menu will be shown on right click.
+
+ @since 2.9.5
+ */
+ virtual bool IsContextMenuEnabled() const;
+
/**
@name History
*/
virtual void ClearSelection() = 0;
/**
- Deletes the current selection. Note that for @c wxWEB_VIEW_BACKEND_WEBKIT
+ Deletes the current selection. Note that for @c wxWEBVIEW_BACKEND_WEBKIT
the selection must be editable, either through SetEditable or the
correct HTML attribute.
*/
@param flags The flags for the search.
@return If search phrase was not found in combination with the flags
then @c wxNOT_FOUND is returned. If called for the first time
- with search phrase then the total number of results will be
+ with search phrase then the total number of results will be
returned. Then for every time its called with the same search
phrase it will return the number of the current match.
@note This function will restart the search if the flags
- @c wxWEB_VIEW_FIND_ENTIRE_WORD or @c wxWEB_VIEW_FIND_MATCH_CASE
+ @c wxWEBVIEW_FIND_ENTIRE_WORD or @c wxWEBVIEW_FIND_MATCH_CASE
are changed, since this will require a new search. To reset the
- search, for example reseting the highlights call the function
+ search, for example reseting the highlights call the function
with an empty search phrase. This always returns @c wxNOT_FOUND
on the OSX WebKit backend.
@since 2.9.5
*/
- virtual long Find(const wxString& text, wxWebViewFindFlags flags = wxWEB_VIEW_FIND_DEFAULT) = 0;
+ virtual long Find(const wxString& text, wxWebViewFindFlags flags = wxWEBVIEW_FIND_DEFAULT) = 0;
/**
@name Zoom
wxWebView objects.
@beginEventEmissionTable{wxWebViewEvent}
- @event{EVT_WEB_VIEW_NAVIGATING(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_NAVIGATING event, generated before trying
+ @event{EVT_WEBVIEW_NAVIGATING(id, func)}
+ Process a @c wxEVT_WEBVIEW_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
+ @event{EVT_WEBVIEW_NAVIGATED(id, func)}
+ Process a @c wxEVT_WEBVIEW_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
+ @event{EVT_WEBVIEW_LOADED(id, func)}
+ Process a @c wxEVT_WEBVIEW_LOADED event generated when the document
is fully loaded and displayed. Note that if the displayed HTML document has
several frames, one such event will be generated per frame.
- @event{EVT_WEB_VIEW_ERROR(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_ERROR event generated when a navigation
+ @event{EVT_WEBVIEW_ERROR(id, func)}
+ Process a @c wxEVT_WEBVIEW_ERROR event generated when a navigation
error occurs.
- The integer associated with this event will be a wxWebNavigationError item.
+ The integer associated with this event will be a #wxWebViewNavigationError item.
The string associated with this event may contain a backend-specific more
precise error message/code.
- @event{EVT_WEB_VIEW_NEWWINDOW(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_NEWWINDOW event, generated when a new
+ @event{EVT_WEBVIEW_NEWWINDOW(id, func)}
+ Process a @c wxEVT_WEBVIEW_NEWWINDOW event, generated when a new
window is created. You must handle this event if you want anything to
happen, for example to load the page in a new window or tab.
- @event{EVT_WEB_VIEW_TITLE_CHANGED(id, func)}
- Process a @c wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED event, generated when
+ @event{EVT_WEBVIEW_TITLE_CHANGED(id, func)}
+ Process a @c wxEVT_WEBVIEW_TITLE_CHANGED event, generated when
the page title changes. Use GetString to get the title.
@endEventTable
};
-wxEventType wxEVT_COMMAND_WEB_VIEW_NAVIGATING;
-wxEventType wxEVT_COMMAND_WEB_VIEW_NAVIGATED;
-wxEventType wxEVT_COMMAND_WEB_VIEW_LOADED;
-wxEventType wxEVT_COMMAND_WEB_VIEW_ERROR;
-wxEventType wxEVT_COMMAND_WEB_VIEW_NEWWINDOW;
-wxEventType wxEVT_COMMAND_WEB_VIEW_TITLE_CHANGED;
+wxEventType wxEVT_WEBVIEW_NAVIGATING;
+wxEventType wxEVT_WEBVIEW_NAVIGATED;
+wxEventType wxEVT_WEBVIEW_LOADED;
+wxEventType wxEVT_WEBVIEW_ERROR;
+wxEventType wxEVT_WEBVIEW_NEWWINDOW;
+wxEventType wxEVT_WEBVIEW_TITLE_CHANGED;
projects / wxWidgets.git / blobdiff