WebBrowserComponent::Options Class Reference

Options to configure WebBrowserComponent. More...

Classes
class	AppleWkWebView
	Options specific to the WkWebView backend used on Apple systems. More...
class	WinWebView2
	Options specific to the WebView2 backend. More...

Public Types
enum class	Backend { defaultBackend , ie , webview2 }

Public Member Functions
Options	withBackend (Backend backend) const
	Use a particular backend to create the WebViewBrowserComponent.
Options	withKeepPageLoadedWhenBrowserIsHidden () const
	Tell JUCE to keep the web page alive when the WebBrowserComponent is not visible.
Options	withUserAgent (String ua) const
	Use a specific user agent string when requesting web pages.
Options	withWinWebView2Options (const WinWebView2 &winWebView2Options) const
	Specifies options that apply to the Windows implementation when the WebView2 feature is enabled.
Options	withAppleWkWebViewOptions (const AppleWkWebView &appleWkWebViewOptions) const
	Specifies options that influence the WebBrowserComponent's behaviour on Apple systems.
Options	withNativeIntegrationEnabled (bool enabled=true) const
	Enables native integration features for the code running inside the WebBrowserComponent.
Options	withNativeFunction (const Identifier &name, NativeFunction callback) const
	Registers a NativeFunction under the given name.
Options	withEventListener (const Identifier &eventId, NativeEventListener listener) const
	Registers a NativeEventListener that receives events sent to the specified eventId.
Options	withUserScript (StringRef script) const
	Adds a Javascript code that will be evaluated before any other resource is loaded but after the JUCE backend definitions become available, hence the specified script can rely on the presence of window.__JUCE__.backend.
Options	withInitialisationData (StringRef name, const var &value) const
	Ensures that there will be a Javascript Array under window.__JUCE__.initialisationData.name and that it will contain the value provided here.
Options	withResourceProvider (ResourceProvider provider, std::optional< String > allowedOriginIn=std::nullopt) const
	Sets a ResourceProvider object that can complete WebView resource requests and return data without having to issue a network operation.
Options	withWebViewLifetimeListener (WebViewLifetimeListener *listener)
	Adds an object that will be notified when the WebBrowserComponent is constructed and destructed.
template<typename OptionsType>
OptionsType	withOptionsFrom (OptionsBuilder< OptionsType > &builder) const
	Adds all options provided by the builder to the returned Options object.
auto	getBackend () const noexcept
auto	keepsPageLoadedWhenBrowserIsHidden () const noexcept
auto	getUserAgent () const
auto	getWinWebView2BackendOptions () const
auto	getAppleWkWebViewOptions () const
auto	getNativeIntegrationsEnabled () const
const auto &	getNativeFunctions () const
const auto &	getEventListeners () const
const auto &	getUserScripts () const
const auto &	getInitialisationData () const
auto	getResourceProvider () const
const auto &	getAllowedOrigin () const
const auto &	getLifetimeListeners () const

Detailed Description

Options to configure WebBrowserComponent.

Member Enumeration Documentation

Backend

enum class WebBrowserComponent::Options::Backend

strong

Enumerator
defaultBackend	Default web browser backend. WebKit will be used on macOS, gtk-webkit2 on Linux and internet explorer on Windows. On Windows, the default may change to webview2 in the fututre.
ie	Use Internet Explorer as the backend on Windows. By default, IE will use an ancient version of IE. To change this behaviour, you either need to add the following html element into your page's head section: <meta http-equiv="X-UA-Compatible" content="IE=edge" /> or you need to change windows registry values for your application. More information on the latter can be found here: https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/general-info/ee330730(v=vs.85)?redirectedfrom=MSDN#browser-emulation
webview2	Use the chromium based WebView2 engine on Windows.

Member Function Documentation

withBackend()

Options WebBrowserComponent::Options::withBackend ( Backend backend ) const

nodiscard

Use a particular backend to create the WebViewBrowserComponent.

JUCE will silently fallback to the default backend if the selected backend is not supported. To check if a specific backend is supported on your platform or not, use WebBrowserComponent::areOptionsSupported.

References withMember().

withKeepPageLoadedWhenBrowserIsHidden()

Options WebBrowserComponent::Options::withKeepPageLoadedWhenBrowserIsHidden ( ) const

nodiscard

Tell JUCE to keep the web page alive when the WebBrowserComponent is not visible.

By default, JUCE will replace the current page with a blank page - this can be handy to stop the browser using resources in the background when it's not actually being used.

References withMember().

withUserAgent()

Options WebBrowserComponent::Options::withUserAgent ( String ua ) const

nodiscard

Use a specific user agent string when requesting web pages.

References withMember().

withWinWebView2Options()

Options WebBrowserComponent::Options::withWinWebView2Options ( const WinWebView2 & winWebView2Options ) const

nodiscard

Specifies options that apply to the Windows implementation when the WebView2 feature is enabled.

See also

withBackend

References withMember().

withAppleWkWebViewOptions()

Options WebBrowserComponent::Options::withAppleWkWebViewOptions ( const AppleWkWebView & appleWkWebViewOptions ) const

nodiscard

Specifies options that influence the WebBrowserComponent's behaviour on Apple systems.

References withMember().

withNativeIntegrationEnabled()

Options WebBrowserComponent::Options::withNativeIntegrationEnabled ( bool enabled = true ) const

nodiscard

Enables native integration features for the code running inside the WebBrowserComponent.

This injects data and function objects under window.__JUCE__.backend through which scripts running in the WebBrowserComponent can send events to the backend and call registered native functions.

You should only enable native integrations if you have full control over the content loaded into the component. Navigating to 3rd party websites with these integrations enabled may expose the application and the computer to security risks.

See also

withNativeFunction, withEventListener

References withMember().

withNativeFunction()

Options WebBrowserComponent::Options::withNativeFunction ( const Identifier & name, NativeFunction callback ) const

nodiscard

Registers a NativeFunction under the given name.

To call this function from the frontend, you can import the JUCE frontend helper module or issue a call to the low-level frontend API.

The callback is always called on the message thread.

import { getNativeFunction } from "./juce";
 
function someJavascriptFunction() {
  const myBackendFunction = getNativeFunction("myBackendFunction");
  myBackendFunction (1, 2, "some string");
}

References jassert, and name.

withEventListener()

Options WebBrowserComponent::Options::withEventListener ( const Identifier & eventId, NativeEventListener listener ) const

nodiscard

Registers a NativeEventListener that receives events sent to the specified eventId.

To send a message to this listener from the frontend, call for example

window.__JUCE__.backend.emitEvent(eventId, { x: 2, y: 6 }); 

Referenced by WebControlParameterIndexReceiver::buildOptions().

withUserScript()

Options WebBrowserComponent::Options::withUserScript ( StringRef script ) const

nodiscard

Adds a Javascript code that will be evaluated before any other resource is loaded but after the JUCE backend definitions become available, hence the specified script can rely on the presence of window.__JUCE__.backend.

This script will be evaluated after all goToUrl() calls.

withInitialisationData()

Options WebBrowserComponent::Options::withInitialisationData ( StringRef name, const var & value ) const

nodiscard

Ensures that there will be a Javascript Array under window.__JUCE__.initialisationData.name and that it will contain the value provided here.

The initialisation data is injected prior to loading any resource. Multiple values added for the same name will all be available in the Array.

References name.

withResourceProvider()

Options WebBrowserComponent::Options::withResourceProvider ( ResourceProvider provider, std::optional< String > allowedOriginIn = std::nullopt ) const

nodiscard

Sets a ResourceProvider object that can complete WebView resource requests and return data without having to issue a network operation.

Requests sent to WebBrowserComponent::getResourceProviderRoot() + "resource.path" will invoke the provider with the path "/resource.path".

If you call WebBrowserComponent::goToURL with the value returned by WebBrowserComponent::getResourceProviderRoot, your resource provider will receive a request for the resource "/" for which you will typically want to return the contents of your index.html.

You can also specify an optional allowedOriginIn parameter that will make your ResourceProvider available to scripts loaded from that origin. E.g. if you specify "http://localhost:3000", then a script loaded from such a local development server will be able to access resources such as getResourceProviderRoot() + "live_data.bin".

Allowing external origins is handy for development, but is a potential security risk in publicly released binaries.

References withMember().

withWebViewLifetimeListener()

Options WebBrowserComponent::Options::withWebViewLifetimeListener ( WebViewLifetimeListener * listener )

nodiscard

Adds an object that will be notified when the WebBrowserComponent is constructed and destructed.

withOptionsFrom()

template<typename OptionsType>

OptionsType WebBrowserComponent::Options::withOptionsFrom

(

OptionsBuilder< OptionsType > &

builder

)

const

Adds all options provided by the builder to the returned Options object.

References OptionsBuilder< OptionsType >::buildOptions().

getBackend()

auto WebBrowserComponent::Options::getBackend ( ) const

noexcept

keepsPageLoadedWhenBrowserIsHidden()

auto WebBrowserComponent::Options::keepsPageLoadedWhenBrowserIsHidden ( ) const

noexcept

getUserAgent()

auto WebBrowserComponent::Options::getUserAgent

(

)

const

getWinWebView2BackendOptions()

auto WebBrowserComponent::Options::getWinWebView2BackendOptions

(

)

const

getAppleWkWebViewOptions()

auto WebBrowserComponent::Options::getAppleWkWebViewOptions

(

)

const

getNativeIntegrationsEnabled()

auto WebBrowserComponent::Options::getNativeIntegrationsEnabled

(

)

const

getNativeFunctions()

const auto & WebBrowserComponent::Options::getNativeFunctions

(

)

const

getEventListeners()

const auto & WebBrowserComponent::Options::getEventListeners

(

)

const

getUserScripts()

const auto & WebBrowserComponent::Options::getUserScripts

(

)

const

getInitialisationData()

const auto & WebBrowserComponent::Options::getInitialisationData

(

)

const

getResourceProvider()

auto WebBrowserComponent::Options::getResourceProvider

(

)

const

getAllowedOrigin()

const auto & WebBrowserComponent::Options::getAllowedOrigin

(

)

const

getLifetimeListeners()

const auto & WebBrowserComponent::Options::getLifetimeListeners

(

)

const