Browser

Native webview using system browser.

Header	#include "nativeui/browser.h"
Namespace	namespace nu
Type	class (RefCounted)
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 webview2_support option to true.
Ship the WebView2Loader.dll file 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.dll file.
WebView2 can not use stable channels of Edge, it will search channels in the order of WebView2 Runtime, Beta, Dev, and Canary.
Some Browser APIs are not implemented with WebView2 backend, due to lack of APIs in WebView2.

Constructors

Browser(const Browser::Options& options)

Create a new browser view.

Parameters

const Browser::Options& options

Class methods

bool RegisterProtocol(const std::string& scheme, std::function<ProtocolJob*(std::string)> 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.

This API is not supported on Windows with WebView2 backend.

Parameters

const std::string& scheme
std::function<ProtocolJob*(std::string)> handler

Return

bool

void UnregisterProtocol(const std::string& scheme);

Unregister the custom protocol with scheme.

This API is not supported on Windows with WebView2 backend.

Parameters

const std::string& scheme

Class properties

`const char*` kClassName

The class name of this view.

Methods

void LoadURL(const std::string& url)

Load the URL.

Parameters

const std::string& url

void LoadHTML(const std::string& html, const std::string& baseurl)

Set the webpage contents and base URL.

On Windows with WebView2 backend, baseurl is not respected.

Parameters

const std::string& html - The string to use as the contents of the webpage.
const std::string& baseurl - A URL used to resolve relative URLs within the document.

std::string GetURL()

Return current URL.

Return

std::string

std::string GetTitle()

Return the title of document.

Return

std::string

void SetUserAgent(const std::string& user_agent)

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

const std::string& user_agent

bool IsMagnifiable() const macOS

Return whether page's magnification can be changed with gestures.

Return

bool

void SetMagnifiable(bool magnifiable) macOS

Set whether page's magnification can be changed with gestures.

Parameters

bool magnifiable

void ExecuteJavaScript(const std::string& code, const std::function<void(bool, base::Value)>& 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 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.

Parameters

const std::string& code
const std::function<void(bool, base::Value)>& callback

void GoBack()

Navigate to the back item in the back-forward list.

bool CanGoBack() const

Return whether there is a back item in the back-forward list that can be navigated to.

Return

bool

void GoForward()

Navigate to the forward item in the back-forward list.

bool CanGoForward() const

Return whether there is a forward item in the back-forward list that can be navigated to.

Return

bool

void Reload()

Reload current page.

void Stop()

Stop loading all resources on the current page.

bool IsLoading() const

Return whether current page is loading content.

Return

bool

void SetBindingName(const std::string& 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

const std::string& name

void AddBinding(const std::string& name, std::function<void(...)> func)

Add a native binding to web page with name.

You can pass an arbitrary function as long as the parameters can be converted from base::Value, otherwise compilation error would happen.

For example, following native binding:

browser->AddBinding("AddRecord", [](std::string key, int value) {
});

accepts following calls:

window.addRecord('Books', 4);
window.addRecord('Videos', 8);

You can also use base::Value directly to accept arbitrary argument:

browser->AddBinding("AddRecord2", [](std::string key, base::Value value) {
})

window.addRecord2('PI', 3.14);
window.addRecord2('The Best Animal', 'Panda');

Note that only functors, function pointers, std::function and captureless labmda functions are accepted in AddBinding. Labmda functions with captures can not have their types deduced automatically, so you have to convert them to std::function first .

Parameters

const std::string& name
std::function<void(...)> func

void AddRawBinding(const std::string& name, std::function<void(Browser*, base::Value)> func)

Add a raw handler to web page with name.

The func will be called with a list of arguments passed from JavaScript.

Parameters

const std::string& name
std::function<void(Browser*, base::Value)> func

void RemoveBinding(const std::string& name)

Remove the native binding with name.

Parameters

const std::string& name

Events

void on_close(Browser* self)

Emitted when the web page requests to close.

Parameters

Browser* self

Preventable

No.

void on_update_command(Browser* self)

Emitted when the back-forward list has changed.

Parameters

Browser* self

Preventable

No.

void on_change_loading(Browser* self)

Emitted when the browser starts or stops loading content.

Parameters

Browser* self

Preventable

No.

void on_update_title(Browser* self, std::string title)

Emitted when document's title is changed.

Parameters

Browser* self
std::string title

Preventable

No.

void on_start_navigation(Browser* self, std::string url)

Emitted when the browser begins provisional navigation.

Parameters

Browser* self
std::string url

Preventable

No.

void on_commit_navigation(Browser* self, std::string url)

Emitted when the browser begins to receive web content.

Parameters

Browser* self
std::string url

Preventable

No.

void on_finish_navigation(Browser* self, std::string url)

Emitted when the navigation is complete.

Parameters

Browser* self
std::string url

Preventable

No.

void on_fail_navigation(Browser* self, std::string url, int code)

Emitted when the navigation fails.

Parameters

Browser* self
std::string url
int code

Preventable

No.

Browser

WebView2 support

Constructors

Browser(const Browser::Options& options)

Parameters

Class methods

bool RegisterProtocol(const std::string& scheme, std::function<ProtocolJob*(std::string)> handler)

Parameters

Return

void UnregisterProtocol(const std::string& scheme);

Parameters

Class properties

const char* kClassName

Methods

void LoadURL(const std::string& url)

Parameters

void LoadHTML(const std::string& html, const std::string& baseurl)

Parameters

std::string GetURL()

Return

std::string GetTitle()

Return

void SetUserAgent(const std::string& user_agent)

Parameters

bool IsMagnifiable() const macOS

Return

void SetMagnifiable(bool magnifiable) macOS

Parameters

void ExecuteJavaScript(const std::string& code, const std::function<void(bool, base::Value)>& callback);

Parameters

void GoBack()

bool CanGoBack() const

Return

void GoForward()

bool CanGoForward() const

Return

void Reload()

void Stop()

bool IsLoading() const

Return

void SetBindingName(const std::string& name)

Parameters

void AddBinding(const std::string& name, std::function<void(...)> func)

Parameters

void AddRawBinding(const std::string& name, std::function<void(Browser*, base::Value)> func)

Parameters

void RemoveBinding(const std::string& name)

Parameters

Events

void on_close(Browser* self)

Parameters

Preventable

void on_update_command(Browser* self)

Parameters

Preventable

void on_change_loading(Browser* self)

Parameters

Preventable

void on_update_title(Browser* self, std::string title)

Parameters

Preventable

void on_start_navigation(Browser* self, std::string url)

Parameters

Preventable

void on_commit_navigation(Browser* self, std::string url)

Parameters

Preventable

void on_finish_navigation(Browser* self, std::string url)

Parameters

Preventable

void on_fail_navigation(Browser* self, std::string url, int code)

Parameters

Preventable

Langauge:

Version:

Formats:

Constructors:

Class methods:

Class properties:

Methods:

`const char*` kClassName