.TH wxWebView 3erl "wx 2.2.2.1" "wxWidgets team." "Erlang Module Definition"
.SH NAME
wxWebView \- Functions for wxWebView class
.SH DESCRIPTION
.LP
This control may be used to render web (HTML / CSS / javascript) documents\&. It is designed to allow the creation of multiple backends for each port, although currently just one is available\&. It differs from \fIwxHtmlWindow\fR\& in that each backend is actually a full rendering engine, Trident on MSW and Webkit on macOS and GTK\&. This allows the correct viewing of complex pages with javascript and css\&.
.LP
Backend Descriptions
.LP
Par: The IE backend uses Microsoft\&'s Trident rendering engine, specifically the version used by the locally installed copy of Internet Explorer\&. As such it is only available for the MSW port\&. By default recent versions of the WebBrowser control, which this backend uses, emulate Internet Explorer 7\&. This can be changed with a registry setting by wxWebView::MSWSetEmulationLevel() see this article for more information\&. This backend has full support for custom schemes and virtual file systems\&.
.LP
Par: The Edge (Chromium) backend uses Microsoft\&'s Edge WebView2\&. It is available for Windows 7 and newer\&. The following features are currently unsupported with this backend: virtual filesystems, custom urls, find\&.
.LP
This backend is not enabled by default, to build it follow these steps:
.LP
Par: Under GTK the WebKit backend uses WebKitGTK+\&. The current minimum version required is 1\&.3\&.1 which ships by default with Ubuntu Natty and Debian Wheezy and has the package name libwebkitgtk-dev\&. Custom schemes and virtual files systems are supported under this backend, however embedded resources such as images and stylesheets are currently loaded using the data:// scheme\&.
.LP
Par: Under GTK3 the WebKit2 version of WebKitGTK+ is used\&. In Ubuntu the required package name is libwebkit2gtk-4\&.0-dev and under Fedora it is webkitgtk4-devel\&. All wxWEBVIEW_WEBKIT features are supported except for clearing and enabling / disabling the history\&.
.LP
Par: The macOS WebKit backend uses Apple\&'s WebView class\&. This backend has full support for custom schemes and virtual file systems\&.
.LP
Asynchronous Notifications
.LP
Many of the methods in \fIwxWebView\fR\& are asynchronous, i\&.e\&. they return immediately and perform their work in the background\&. This includes functions such as \fIloadURL/2\fR\& and \fIreload/2\fR\&\&. To receive notification of the progress and completion of these functions you need to handle the events that are provided\&. Specifically \fIwxEVT_WEBVIEW_LOADED\fR\& notifies when the page or a sub-frame has finished loading and \fIwxEVT_WEBVIEW_ERROR\fR\& notifies that an error has occurred\&.
.LP
Virtual File Systems and Custom Schemes
.LP
\fIwxWebView\fR\& supports the registering of custom scheme handlers, for example \fIfile\fR\& or \fIhttp\fR\&\&. To do this create a new class which inherits from \fIwxWebViewHandler\fR\& (not implemented in wx), where wxWebHandler::GetFile() returns a pointer to a \fIwxFSFile\fR\& (not implemented in wx) which represents the given url\&. You can then register your handler with \fIRegisterHandler()\fR\& (not implemented in wx) it will be called for all pages and resources\&.
.LP
\fIwxWebViewFSHandler\fR\& (not implemented in wx) is provided to access the virtual file system encapsulated by \fIwxFileSystem\fR\& (not implemented in wx)\&. The \fIwxMemoryFSHandler\fR\& (not implemented in wx) documentation gives an example of how this may be used\&.
.LP
\fIwxWebViewArchiveHandler\fR\& (not implemented in wx) is provided to allow the navigation of pages inside a zip archive\&. It supports paths of the form: \fIscheme:///C\fR\&:/example/docs\&.zip;protocol=zip/main\&.htm
.LP
Since: 2\&.9\&.3
.LP
See: \fIwxWebViewHandler\fR\& (not implemented in wx), \fIwxWebViewEvent\fR\& 
.LP
This class is derived (and can use functions) from: \fIwxControl\fR\& \fIwxWindow\fR\& \fIwxEvtHandler\fR\&
.LP
wxWidgets docs: wxWebView
.SH "EVENTS"

.LP
Event types emitted from this class: \fIwebview_navigating\fR\&, \fIwebview_navigated\fR\&, \fIwebview_loaded\fR\&, \fIwebview_error\fR\&, \fIwebview_newwindow\fR\&, \fIwebview_title_changed\fR\&
.SH DATA TYPES
.nf

\fBwxWebView()\fR\& = wx:wx_object()
.br
.fi
.SH EXPORTS
.LP
.nf

.B
new(Parent, Id) -> wxWebView()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Parent = wxWindow:wxWindow()
.br
Id = integer()
.br
.RE
.RE
.LP
.nf

.B
new(Parent, Id, Options :: [Option]) -> wxWebView()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Parent = wxWindow:wxWindow()
.br
Id = integer()
.br
Option = 
.br
    {url, unicode:chardata()} |
.br
    {pos, {X :: integer(), Y :: integer()}} |
.br
    {size, {W :: integer(), H :: integer()}} |
.br
    {backend, unicode:chardata()} |
.br
    {style, integer()}
.br
.RE
.RE
.RS
.LP
Factory function to create a new \fIwxWebView\fR\& using a \fIwxWebViewFactory\fR\& (not implemented in wx)\&.
.LP
Return: The created \fIwxWebView\fR\&, or \fINULL\fR\& if the requested backend is not available
.LP
Since: 2\&.9\&.5
.RE

.LP
.nf

.B
getCurrentTitle(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the title of the current web page, or its URL/path if title is not available\&.
.RE

.LP
.nf

.B
getCurrentURL(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the URL of the currently displayed document\&.
.RE

.LP
.nf

.B
getPageSource(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the HTML source code of the currently displayed document\&.
.LP
Return: The HTML source code, or an empty string if no page is currently shown\&.
.RE

.LP
.nf

.B
getPageText(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the text of the current page\&.
.RE

.LP
.nf

.B
isBusy(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns whether the web control is currently busy (e\&.g\&. loading a page)\&.
.RE

.LP
.nf

.B
isEditable(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns whether the web control is currently editable\&.
.RE

.LP
.nf

.B
loadURL(This, Url) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Url = unicode:chardata()
.br
.RE
.RE
.RS
.LP
Load a web page from a URL\&.
.LP
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\&.
.RE

.LP
.nf

.B
print(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Opens a print dialog so that the user may print the currently displayed page\&.
.RE

.LP
.nf

.B
reload(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.LP
.nf

.B
reload(This, Options :: [Option]) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Option = {flags, wx:wx_enum()}
.br
.RE
.RE
.RS
.LP
Reload the currently displayed URL\&.
.LP
Note: The flags are ignored by the edge backend\&.
.RE

.LP
.nf

.B
runScript(This, Javascript) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Result = {Res :: boolean(), Output :: unicode:charlist()}
.br
This = wxWebView()
.br
Javascript = unicode:chardata()
.br
.RE
.RE
.RS
.LP
Runs the given JavaScript code\&.
.LP
JavaScript code is executed inside the browser control and has full access to DOM and other browser-provided functionality\&. For example, this code will replace the current page contents with the provided string\&.
.LP
If \fIoutput\fR\& is non-null, it is filled with the result of executing this code on success, e\&.g\&. a JavaScript value such as a string, a number (integer or floating point), a boolean or JSON representation for non-primitive types such as arrays and objects\&. For example:
.LP
This function has a few platform-specific limitations:
.LP
Also notice that under MSW converting JavaScript objects to JSON is not supported in the default emulation mode\&. \fIwxWebView\fR\& implements its own object-to-JSON conversion as a fallback for this case, however it is not as full-featured, well-tested or performing as the implementation of this functionality in the browser control itself, so it is recommended to use MSWSetEmulationLevel() to change emulation level to a more modern one in which JSON conversion is done by the control itself\&.
.LP
Return: true if there is a result, false if there is an error\&.
.RE

.LP
.nf

.B
setEditable(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.LP
.nf

.B
setEditable(This, Options :: [Option]) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Option = {enable, boolean()}
.br
.RE
.RE
.RS
.LP
Set the editable property of the web control\&.
.LP
Enabling allows the user to edit the page even if the \fIcontenteditable\fR\& attribute is not set\&. The exact capabilities vary with the backend being used\&.
.RE

.LP
.nf

.B
setPage(This, Html, BaseUrl) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Html = BaseUrl = unicode:chardata()
.br
.RE
.RE
.RS
.LP
Set the displayed page source to the contents of the given string\&.
.LP
Note: When using \fIwxWEBVIEW_BACKEND_IE\fR\& you must wait for the current page to finish loading before calling \fIsetPage/3\fR\&\&. The baseURL parameter is not used in this backend and the edge backend\&.
.RE

.LP
.nf

.B
stop(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Stop the current page loading process, if any\&.
.LP
May trigger an error event of type \fIwxWEBVIEW_NAV_ERR_USER_CANCELLED\fR\&\&. TODO: make \fIwxWEBVIEW_NAV_ERR_USER_CANCELLED\fR\& errors uniform across ports\&.
.RE

.LP
.nf

.B
canCopy(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if the current selection can be copied\&.
.LP
Note: This always returns \fItrue\fR\& on the macOS WebKit backend\&.
.RE

.LP
.nf

.B
canCut(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if the current selection can be cut\&.
.LP
Note: This always returns \fItrue\fR\& on the macOS WebKit backend\&.
.RE

.LP
.nf

.B
canPaste(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if data can be pasted\&.
.LP
Note: This always returns \fItrue\fR\& on the macOS WebKit backend\&.
.RE

.LP
.nf

.B
copy(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Copies the current selection\&.
.RE

.LP
.nf

.B
cut(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Cuts the current selection\&.
.RE

.LP
.nf

.B
paste(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Pastes the current data\&.
.RE

.LP
.nf

.B
enableContextMenu(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.LP
.nf

.B
enableContextMenu(This, Options :: [Option]) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Option = {enable, boolean()}
.br
.RE
.RE
.RS
.LP
Enable or disable the right click context menu\&.
.LP
By default the standard context menu is enabled, this method can be used to disable it or re-enable it later\&.
.LP
Since: 2\&.9\&.5
.RE

.LP
.nf

.B
isContextMenuEnabled(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if a context menu will be shown on right click\&.
.LP
Since: 2\&.9\&.5
.RE

.LP
.nf

.B
canGoBack(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if it is possible to navigate backward in the history of visited pages\&.
.RE

.LP
.nf

.B
canGoForward(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if it is possible to navigate forward in the history of visited pages\&.
.RE

.LP
.nf

.B
clearHistory(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Clear the history, this will also remove the visible page\&.
.LP
Note: This is not implemented on the WebKit2GTK+ backend\&.
.RE

.LP
.nf

.B
enableHistory(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.LP
.nf

.B
enableHistory(This, Options :: [Option]) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Option = {enable, boolean()}
.br
.RE
.RE
.RS
.LP
Enable or disable the history\&.
.LP
This will also clear the history\&.
.LP
Note: This is not implemented on the WebKit2GTK+ backend\&.
.RE

.LP
.nf

.B
goBack(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Navigate back in the history of visited pages\&.
.LP
Only valid if \fIcanGoBack/1\fR\& returns true\&.
.RE

.LP
.nf

.B
goForward(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Navigate forward in the history of visited pages\&.
.LP
Only valid if \fIcanGoForward/1\fR\& returns true\&.
.RE

.LP
.nf

.B
clearSelection(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Clears the current selection\&.
.RE

.LP
.nf

.B
deleteSelection(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Deletes the current selection\&.
.LP
Note that for \fIwxWEBVIEW_BACKEND_WEBKIT\fR\& the selection must be editable, either through SetEditable or the correct HTML attribute\&.
.RE

.LP
.nf

.B
getSelectedSource(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns the currently selected source, if any\&.
.RE

.LP
.nf

.B
getSelectedText(This) -> unicode:charlist()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns the currently selected text, if any\&.
.RE

.LP
.nf

.B
hasSelection(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if there is a current selection\&.
.RE

.LP
.nf

.B
selectAll(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Selects the entire page\&.
.RE

.LP
.nf

.B
canRedo(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if there is an action to redo\&.
.RE

.LP
.nf

.B
canUndo(This) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Returns true if there is an action to undo\&.
.RE

.LP
.nf

.B
redo(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Redos the last action\&.
.RE

.LP
.nf

.B
undo(This) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Undos the last action\&.
.RE

.LP
.nf

.B
find(This, Text) -> integer()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Text = unicode:chardata()
.br
.RE
.RE
.LP
.nf

.B
find(This, Text, Options :: [Option]) -> integer()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Text = unicode:chardata()
.br
Option = {flags, wx:wx_enum()}
.br
.RE
.RE
.RS
.LP
Finds a phrase on the current page and if found, the control will scroll the phrase into view and select it\&.
.LP
Return: If search phrase was not found in combination with the flags then \fIwxNOT_FOUND\fR\& is returned\&. If called for the first time 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\&.
.LP
Note: This function will restart the search if the flags \fIwxWEBVIEW_FIND_ENTIRE_WORD\fR\& or \fIwxWEBVIEW_FIND_MATCH_CASE\fR\& are changed, since this will require a new search\&. To reset the search, for example resetting the highlights call the function with an empty search phrase\&. This always returns \fIwxNOT_FOUND\fR\& on the macOS WebKit backend\&.
.LP
Since: 2\&.9\&.5
.RE

.LP
.nf

.B
canSetZoomType(This, Type) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Type = wx:wx_enum()
.br
.RE
.RE
.RS
.LP
Retrieve whether the current HTML engine supports a zoom type\&.
.LP
Return: Whether this type of zoom is supported by this HTML engine (and thus can be set through \fIsetZoomType/2\fR\&)\&.
.RE

.LP
.nf

.B
getZoom(This) -> wx:wx_enum()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the zoom level of the page\&.
.LP
See \fIgetZoomFactor/1\fR\& to get more precise zoom scale value other than as provided by \fIwxWebViewZoom\fR\&\&.
.LP
Return: The current level of zoom\&.
.RE

.LP
.nf

.B
getZoomType(This) -> wx:wx_enum()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get how the zoom factor is currently interpreted\&.
.LP
Return: How the zoom factor is currently interpreted by the HTML engine\&.
.RE

.LP
.nf

.B
setZoom(This, Zoom) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Zoom = wx:wx_enum()
.br
.RE
.RE
.RS
.LP
Set the zoom level of the page\&.
.LP
See \fIsetZoomFactor/2\fR\& for more precise scaling other than the measured steps provided by \fIwxWebViewZoom\fR\&\&.
.RE

.LP
.nf

.B
setZoomType(This, ZoomType) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
ZoomType = wx:wx_enum()
.br
.RE
.RE
.RS
.LP
Set how to interpret the zoom factor\&.
.LP
Note: invoke \fIcanSetZoomType/2\fR\& first, some HTML renderers may not support all zoom types\&.
.RE

.LP
.nf

.B
getZoomFactor(This) -> number()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
.RE
.RE
.RS
.LP
Get the zoom factor of the page\&.
.LP
Return: The current factor of zoom\&.
.LP
Since: 3\&.1\&.4
.RE

.LP
.nf

.B
setZoomFactor(This, Zoom) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
This = wxWebView()
.br
Zoom = number()
.br
.RE
.RE
.RS
.LP
Set the zoom factor of the page\&.
.LP
Note: zoom scale in IE will be converted into \fIwxWebViewZoom\fR\& levels for \fIwxWebViewZoomType\fR\& of \fIwxWEBVIEW_ZOOM_TYPE_TEXT\fR\&\&.
.LP
Since: 3\&.1\&.4
.RE

.LP
.nf

.B
isBackendAvailable(Backend) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Backend = unicode:chardata()
.br
.RE
.RE
.RS
.LP
Allows to check if a specific backend is currently available\&.
.LP
Since: 3\&.1\&.4
.RE