Options to configure WebBrowserComponent. More...

#include <juce_WebBrowserComponent.h>

Collaboration diagram for juce::WebBrowserComponent::Options:

[legend]

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
const auto &	getAllowedOrigin () const

auto	getAppleWkWebViewOptions () const

auto	getBackend () const noexcept

const auto &	getEventListeners () const

const auto &	getInitialisationData () const

const auto &	getLifetimeListeners () const

const auto &	getNativeFunctions () const

auto	getNativeIntegrationsEnabled () const

auto	getResourceProvider () const

auto	getUserAgent () const

const auto &	getUserScripts () const

auto	getWinWebView2BackendOptions () const

auto	keepsPageLoadedWhenBrowserIsHidden () const noexcept

Options	withAppleWkWebViewOptions (const AppleWkWebView &appleWkWebViewOptions) const
	Specifies options that influence the WebBrowserComponent's behaviour on Apple systems.

Options	withBackend (Backend backend) const
	Use a particular backend to create the WebViewBrowserComponent.

Options	withEventListener (const Identifier &eventId, NativeEventListener listener) const
	Registers a NativeEventListener that receives events sent to the specified eventId.

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	withKeepPageLoadedWhenBrowserIsHidden () const
	Tell JUCE to keep the web page alive when the WebBrowserComponent is not visible.

Options	withNativeFunction (const Identifier &name, NativeFunction callback) const
	Registers a NativeFunction under the given name.

Options	withNativeIntegrationEnabled (bool enabled=true) const
	Enables native integration features for the code running inside the WebBrowserComponent.

template<typename OptionsType >
OptionsType	withOptionsFrom (OptionsBuilder< OptionsType > &builder) const
	Adds all options provided by the builder to the returned Options object.

Options	withUserAgent (String ua) const
	Use a specific user agent string when requesting web pages.

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	withWebViewLifetimeListener (WebViewLifetimeListener *listener)
	Adds an object that will be notified when the WebBrowserComponent is constructed and destructed.

Options	withWinWebView2Options (const WinWebView2 &winWebView2Options) const
	Specifies options that apply to the Windows implementation when the WebView2 feature is enabled.

Private Attributes
std::optional< String >	allowedOrigin

AppleWkWebView	appleWkWebView

Backend	browserBackend = Backend::defaultBackend

bool	enableNativeIntegration = false

std::vector< std::pair< Identifier, NativeEventListener > >	eventListeners

std::vector< std::pair< String, var > >	initialisationData

bool	keepPageLoadedWhenBrowserIsHidden = false

std::vector< WebViewLifetimeListener * >	lifetimeListeners

std::map< Identifier, NativeFunction >	nativeFunctions

ResourceProvider	resourceProvider

String	userAgent

StringArray	userScripts

WinWebView2	winWebView2

Detailed Description

Options to configure WebBrowserComponent.

Member Enumeration Documentation

◆ Backend

enum class juce::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

◆ getAllowedOrigin()

const auto & juce::WebBrowserComponent::Options::getAllowedOrigin ( ) const

inline

◆ getAppleWkWebViewOptions()

auto juce::WebBrowserComponent::Options::getAppleWkWebViewOptions ( ) const

inline

◆ getBackend()

auto juce::WebBrowserComponent::Options::getBackend ( ) const

inlinenoexcept

◆ getEventListeners()

const auto & juce::WebBrowserComponent::Options::getEventListeners ( ) const

inline

◆ getInitialisationData()

const auto & juce::WebBrowserComponent::Options::getInitialisationData ( ) const

inline

◆ getLifetimeListeners()

const auto & juce::WebBrowserComponent::Options::getLifetimeListeners ( ) const

inline

◆ getNativeFunctions()

const auto & juce::WebBrowserComponent::Options::getNativeFunctions ( ) const

inline

◆ getNativeIntegrationsEnabled()

auto juce::WebBrowserComponent::Options::getNativeIntegrationsEnabled ( ) const

inline

◆ getResourceProvider()

auto juce::WebBrowserComponent::Options::getResourceProvider ( ) const

inline

◆ getUserAgent()

auto juce::WebBrowserComponent::Options::getUserAgent ( ) const

inline

◆ getUserScripts()

const auto & juce::WebBrowserComponent::Options::getUserScripts ( ) const

inline

◆ getWinWebView2BackendOptions()

auto juce::WebBrowserComponent::Options::getWinWebView2BackendOptions ( ) const

inline

◆ keepsPageLoadedWhenBrowserIsHidden()

auto juce::WebBrowserComponent::Options::keepsPageLoadedWhenBrowserIsHidden ( ) const

inlinenoexcept

◆ withAppleWkWebViewOptions()

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

inline

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

References juce::withMember().

◆ withBackend()

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

inline

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 juce::withMember().

◆ withEventListener()

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

inline

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 });

juce::AccessibilityRole::window

@ window

Referenced by juce::WebControlParameterIndexReceiver::buildOptions().

◆ withInitialisationData()

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

inline

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.

◆ withKeepPageLoadedWhenBrowserIsHidden()

Options juce::WebBrowserComponent::Options::withKeepPageLoadedWhenBrowserIsHidden ( ) const

inline

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 juce::withMember().

◆ withNativeFunction()

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

inline

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.

◆ withNativeIntegrationEnabled()

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

inline

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 juce::withMember().

◆ withOptionsFrom()

template<typename OptionsType >

OptionsType juce::WebBrowserComponent::Options::withOptionsFrom ( OptionsBuilder< OptionsType > & builder ) const

inline

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

References OptionsBuilder< OptionsType >::buildOptions().

◆ withUserAgent()

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

inline

Use a specific user agent string when requesting web pages.

References juce::withMember().

◆ withUserScript()

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

inline

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.

◆ withWebViewLifetimeListener()

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

inline

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

◆ withWinWebView2Options()

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

inline

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

See also: withBackend

References juce::withMember().

Member Data Documentation

◆ allowedOrigin

std::optional<String> juce::WebBrowserComponent::Options::allowedOrigin

private

◆ appleWkWebView

AppleWkWebView juce::WebBrowserComponent::Options::appleWkWebView

private

◆ browserBackend

Backend juce::WebBrowserComponent::Options::browserBackend = Backend::defaultBackend

private

◆ enableNativeIntegration

bool juce::WebBrowserComponent::Options::enableNativeIntegration = false

private

◆ eventListeners

std::vector<std::pair<Identifier, NativeEventListener> > juce::WebBrowserComponent::Options::eventListeners

private

◆ initialisationData

std::vector<std::pair<String, var> > juce::WebBrowserComponent::Options::initialisationData

private

◆ keepPageLoadedWhenBrowserIsHidden

bool juce::WebBrowserComponent::Options::keepPageLoadedWhenBrowserIsHidden = false

private

◆ lifetimeListeners

std::vector<WebViewLifetimeListener*> juce::WebBrowserComponent::Options::lifetimeListeners

private

◆ nativeFunctions

std::map<Identifier, NativeFunction> juce::WebBrowserComponent::Options::nativeFunctions

private

◆ resourceProvider

ResourceProvider juce::WebBrowserComponent::Options::resourceProvider

private

◆ userAgent

String juce::WebBrowserComponent::Options::userAgent

private

◆ userScripts

StringArray juce::WebBrowserComponent::Options::userScripts

private

◆ winWebView2

WinWebView2 juce::WebBrowserComponent::Options::winWebView2

private

The documentation for this class was generated from the following file:

juce_WebBrowserComponent.h

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Backend

Member Function Documentation

◆ getAllowedOrigin()

◆ getAppleWkWebViewOptions()

◆ getBackend()

◆ getEventListeners()

◆ getInitialisationData()

◆ getLifetimeListeners()

◆ getNativeFunctions()

◆ getNativeIntegrationsEnabled()

◆ getResourceProvider()

◆ getUserAgent()

◆ getUserScripts()

◆ getWinWebView2BackendOptions()

◆ keepsPageLoadedWhenBrowserIsHidden()

◆ withAppleWkWebViewOptions()

◆ withBackend()

◆ withEventListener()

◆ withInitialisationData()

◆ withKeepPageLoadedWhenBrowserIsHidden()

◆ withNativeFunction()

◆ withNativeIntegrationEnabled()

◆ withOptionsFrom()

◆ withUserAgent()

◆ withUserScript()

◆ withWebViewLifetimeListener()

◆ withWinWebView2Options()

Member Data Documentation

◆ allowedOrigin

◆ appleWkWebView

◆ browserBackend

◆ enableNativeIntegration

◆ eventListeners

◆ initialisationData

◆ keepPageLoadedWhenBrowserIsHidden

◆ lifetimeListeners

◆ nativeFunctions

◆ resourceProvider

◆ userAgent

◆ userScripts

◆ winWebView2