Loading...
Searching...
No Matches
juce::WebBrowserComponent::Options Class Reference

## Detailed Description

Options to configure WebBrowserComponent.

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

- juce_gui_extra/misc/juce_WebBrowserComponent.h

## Classes

class | WinWebView2
| Options specific to the WebView2 backend. More...
class | AppleWkWebView
| Options specific to the WkWebView backend used on Apple systems. 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

## Member Enums

## 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 Functions

## withBackend()

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

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

## withKeepPageLoadedWhenBrowserIsHidden()

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

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

## withUserAgent()

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

inline nodiscard

Use a specific user agent string when requesting web pages.

References juce::withMember().

## withWinWebView2Options()

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

inline nodiscard

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

See also
  withBackend

References juce::withMember().

## withAppleWkWebViewOptions()

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

inline nodiscard

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

References juce::withMember().

## withNativeIntegrationEnabled()

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

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

## withNativeFunction()

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

inline 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 juce::WebBrowserComponent::Options::withEventListener | ( | const Identifier & | eventId,
|  | NativeEventListener | listener ) const

inline 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 });
x
float x
Definition juce_UnityPluginInterface.h:197
y
float float y
Definition juce_UnityPluginInterface.h:197
juce::AccessibilityRole::window
@ window
Definition juce_AccessibilityRole.h:72

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

## withUserScript()

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

inline 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 juce::WebBrowserComponent::Options::withInitialisationData | ( | StringRef | name,
|  | const var & | value ) const

inline 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 juce::WebBrowserComponent::Options::withResourceProvider | ( | ResourceProvider | provider,
|  | std::optional< String > | allowedOriginIn = std::nullopt ) const

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

## withWebViewLifetimeListener()

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

inline nodiscard

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

## 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 juce::OptionsBuilder< OptionsType >::buildOptions().

## getBackend()

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

inline noexcept

## keepsPageLoadedWhenBrowserIsHidden()

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

inline noexcept

## getUserAgent()

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

inline

## getWinWebView2BackendOptions()

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

inline

## getAppleWkWebViewOptions()

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

inline

## getNativeIntegrationsEnabled()

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

inline

## getNativeFunctions()

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

inline

## getEventListeners()

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

inline

## getUserScripts()

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

inline

## getInitialisationData()

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

inline

## getResourceProvider()

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

inline

## getAllowedOrigin()

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

inline

## getLifetimeListeners()

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

inline

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited