Browser
Native webview using system browser.
| Module | require("gui") |
| Type | Class |
| Inherits | View |
Using Browser requires relatively new operating systems, for macOS the
minimum version required is 10.10, for Linux it is required to install the
webkit2gtk library with at least version 2.8.
On Windows the latest version of IE installed would be used by default.
On Linux due to poor support of hardware acceleration, the browser may fail to show anything, in that case you may want to disable hardware acceleration.
WebView2 support
On Windows there is support for using WebView2 as browser backend, to enable it, you need to:
- Set the
webview2Supportoption totrue. - Ship the
WebView2Loader.dllfile together with your program. - Have users install Edge Beta/Dev/Canary or WebView2 Runtime on their machines.
There are also a few things to notice:
- When WebView2 failed to initialize for any reason, the browser will fallback to use IE as backend quietly.
- If you don't use WebView2, it is safe to remove the
WebView2Loader.dllfile. - WebView2 can not use stable channels of Edge, it will search channels in the order of WebView2 Runtime, Beta, Dev, and Canary.
- Some
BrowserAPIs are not implemented with WebView2 backend, due to lack of APIs in WebView2.
Class methods
create(options)
Create a new browser view.
Parameters
Browser::Optionsoptions
Return
BrowserregisterProtocol(scheme, handler)
Register a custom protocol with scheme and handler.
When the browser sends a request with scheme, the handler will be
called with handler(url), and the handler must return an instance of
class that inherits from ProtocolJob.
The handler is guaranteed to be called in the main thread.
On Windows with WebView2 backend, this method must be called before creating the Browser view.
Parameters
StringschemeFunctionhandler
Return
BooleanunregisterProtocol(scheme)
Unregister the custom protocol with scheme.
Parameters
Stringscheme
Methods
loadURL(url)
Load the URL.
Parameters
Stringurl
loadHTML(html, baseurl)
Set the webpage contents and base URL.
On Windows with WebView2 backend, baseurl is not respected.
Parameters
Stringhtml - The string to use as the contents of the webpage.Stringbaseurl - A URL used to resolve relative URLs within the document.
getURL()
Return current URL.
Return
StringgetTitle()
Return the title of document.
Return
StringsetUserAgent(userAgent)
Change browser's user agent.
On Windows, due to Internet Explorer's limitations, calling SetUserAgent
would change all web pages' user agents in current process.
This API is not supported on Windows with WebView2 backend.
Parameters
StringuserAgent
isMagnifiable() macOS
Return whether page's magnification can be changed with gestures.
Return
BooleansetMagnifiable(magnifiable) macOS
Set whether page's magnification can be changed with gestures.
Parameters
Booleanmagnifiable
executeJavaScript(code, callback)
Evaluate code in browser and get the evaluated result.
The callback will be called with callback(success, result), the
result argument is a generic value that created from the result of
code.
Note that due to limitations of system toolkits, the execution may fail if
the result of execution of code can not be fully converted to JSON.
On Windows with WebView2 backend, the success may be true even when
exception is threw in the executed code.
On Windows with IE backend, the code is executed synchronously and
the callback is called before this API returns.
Parameters
StringcodeFunctioncallback
getCookiesForURL(url, callback)
Receive cookies under url.
This API will include HTTP only cookies.
This API is not implemented on Windows with IE backend.
Parameters
StringurlFunctioncallback
goBack()
Navigate to the back item in the back-forward list.
canGoBack()
Return whether there is a back item in the back-forward list that can be navigated to.
Return
BooleangoForward()
Navigate to the forward item in the back-forward list.
canGoForward()
Return whether there is a forward item in the back-forward list that can be navigated to.
Return
Booleanreload()
Reload current page.
stop()
Stop loading all resources on the current page.
isLoading()
Return whether current page is loading content.
Return
BooleansetBindingName(name)
Set the name of object which would have the native bindings.
By default native bindings are added to the window object, by calling
this API, native bindings will be added to the window[name] object.
Parameters
Stringname
addBinding(name, func)
Add a native binding to web page with name.
The func will be called with automatically converted arguments.
Parameters
StringnameFunctionfunc
addRawBinding(name, func)
Add a raw handler to web page with name.
The func will be called with a list of arguments passed from JavaScript.
Parameters
StringnameFunctionfunc
removeBinding(name)
Remove the native binding with name.
Parameters
Stringname
beginAddingBindings()
Buffer following calls of addBinding until
endAddingBindings is called.
Adding a native binding is an expensive operation, if you are adding a
lot of bindings, it is recommended to wrap the addBinding calls
between a pair of beginAddingBindings and endAddingBindings
which will buffer the bindings and reduce the cost to minimal.
endAddingBindings()
Consolidate bindings added.
Events
onClose(self)
Emitted when the web page requests to close.
Parameters
Browserself
Preventable
No.onUpdateCommand(self)
Emitted when the back-forward list has changed.
Parameters
Browserself
Preventable
No.onChangeLoading(self)
Emitted when the browser starts or stops loading content.
Parameters
Browserself
Preventable
No.onUpdateTitle(self, title)
Emitted when document's title is changed.
Parameters
BrowserselfStringtitle
Preventable
No.onStartNavigation(self, url)
Emitted when the browser begins provisional navigation.
Parameters
BrowserselfStringurl
Preventable
No.onCommitNavigation(self, url)
Emitted when the browser begins to receive web content.
Parameters
BrowserselfStringurl
Preventable
No.onFinishNavigation(self, url)
Emitted when the navigation is complete.
Parameters
BrowserselfStringurl
Preventable
No.onFailNavigation(self, url, code)
Emitted when the navigation fails.
Parameters
BrowserselfStringurlIntegercode