WebContext QML Type

Manages state shared between web views More...

Import Statement: import com.canonical.Oxide 1.15
Instantiates: OxideQQuickWebContext

Properties

Methods

Detailed Description

WebContext manages state shared between web views - this includes things like the cookie database, network cache and local storage. Applications can set dataPath and cachePath during construction to specify storage locations.

Applications can loosely control the maximum size of the network cache by setting maxCacheSizeHint during construction.

The user agent string used by web views can be customized using the userAgent and product properties. These control the User-Agent HTTP header and the value of navigator.userAgent. Per-URL user-agent string overrides can also be provided by using userAgentOverrides.

WebContext also provides a mechanism to inject scripts in to web pages via userScripts, addUserScript and removeUserScript.

WebContext allows some cookie behaviour to be configured, using sessionCookieMode and cookiePolicy.

If Oxide::processModel is Oxide.ProcessModelSingleProcess, the first created WebContext will become the application default WebContext (the one provided by Oxide::defaultWebContext) if that hasn't already been created.

Property Documentation

acceptLangs : string

The value used to determine the contents of navigator.languages and of the HTTP Accept-Language header.

Applications can specify this by setting it to a comma delimited list of language codes in order of preference (starting with the most-preferred). Oxide will automatically convert this in to the format used by the HTTP Accept-Language header, including quality values.


allowedExtraUrlSchemes : list<string>

Specifies a list of URL schemes for which requests will be delegated to Qt's networking stack. Requests will be performed with the QNetworkAccessManager provided by the QQmlEngine to which this WebContext belongs.

Some URL schemes will be ignored and never delegated to Qt's networking stack. These are about, blob, chrome, chrome-devtools, data, file, ftp, http, https, ws and wss.

This QML property was introduced in OxideQt 1.3.


cachePath : url

The location of cache related persistent data files, such as the network cache.

This can be set during construction of the WebContext. Attempts to change it afterwards will be ignored.

To define the location of cache related persistent data files, this must be set to a local (file:) URL. Non-local schemes are not supported, and will be ignored.

If this is not set, Oxide will fall back to using dataPath if that is set.


cookieManager : CookieManager

This QML property was introduced in OxideQt 1.3.


cookiePolicy : enumeration

The cookie policy. This can be set to one of the following values:

ConstantDescription
WebContext.CookiePolicyAllowAllNo cookie blocking is performed. This doesn't affect cookie blocking features for individual cookies (eg, Secure, HttpOnly, SameSite).
WebContext.CookiePolicyBlockAllBlock all cookies from being set or read.
WebContext.CookiePolicyBlockThirdPartyPrevent third-party cookies from being set or read. No cookie blocking is performed for first-party cookies.

The default value is WebContext.CookiePolicyAllowAll


dataPath : url

The location of non-cache related persistent data files, such as the cookie database or local storage.

This can be set during construction of the WebContext. Attempts to change it afterwards will be ignored.

To define the location of non-cache related persistent data files, this must be set to a local (file:) URL. Non-local schemes are not supported, and will be ignored.


defaultAudioCaptureDeviceId : string

Allow the application to specify the default audio capture device used when handling calls to MediaDevices.getUserMedia(). This must be set to the ID of a currently detected audio capture device.

By default this is empty, which means that Oxide will use the first audio capture device returned by Oxide::availableAudioCaptureDevices.

This QML property was introduced in OxideQt 1.9.


defaultVideoCaptureDeviceId : string

Allow the application to specify the default video capture device used when handling calls to MediaDevices.getUserMedia(). This must be set to the ID of a currently detected video capture device.

By default this is empty, which means that Oxide will use the first front-facing video capture device returned by Oxide::availableAudioCaptureDevices (or the first device if no front-facing device is available).

This QML property was introduced in OxideQt 1.9.


devtoolsBindIp : string

The IP address of the network interface to run the remote debugging service on. This must be set to a valid IPv4 or IPv6 string literal.

This can't be modified whilst devtoolsEnabled is true.

The default value is 127.0.0.1.


devtoolsEnabled : bool

Whether to enable remote debugging. The default is false.

Note: Use this with caution, as this makes a remote debugging service available on the specified network interface.


devtoolsPort : int

The port to run the remote debugging service on. This can be set to a value between 1024 and 65535.

This can't be modified whilst devtoolsEnabled is true.

The default value is 8484.


doNotTrack : bool

Whether to enable do-not-track. The default is false.

Setting this to true will result in the DNT header being added and set to 1 in outgoing HTTP requests. It will also result in navigator.doNotTrack indicating that do-not-track is enabled.

When set to false, Oxide behaves as if no preference has been specified (the DNT header is omitted from HTTP requests and navigator.doNotTrack is an undefined value.

This QML property was introduced in OxideQt 1.9.


hostMappingRules : list<string>

This provides a mechanism to allow applications to map host:port pairs to other host:port pairs. Where a match exists, network connections to a host:port pair will be automatically mapped to the replacement host:port pair.

This is mostly useful for automated testing.

Each entry in this list is a string with a format that can be one of:

This can be set during construction only. Attempts to change this after WebContext is constructed will have no effect.

This QML property was introduced in OxideQt 1.3.


maxCacheSizeHint : int

Specify a soft upper limit for the size of the network cache in MB. This can only be set during construction. Attempts to change it after WebContext is constructed will be ignored.

By default this is 0, which means that Oxide will determine an appropriate value automatically.

This QML property was introduced in OxideQt 1.6.


popupBlockerEnabled : bool

Whether to prevent sites from creating new windows with window.open() without being initiated by a user action. The default is true.


product : string

The product name used to build the default user agent string. Setting this will cause userAgent to change if it is set to the default.

The default value is "Chrome/X.X.X.X", where "X.X.X.X" is the Chromium version that this Oxide build is based on.

Setting this to an empty string will restore the default value.

See also userAgent.


sessionCookieMode : enumeration

Determines the restoration behaviour of session cookies. This can be set during construction only, and may be set to one of the following values:

ConstantDescription
WebContext.SessionCookieModeEphemeralSession cookies that exist in the cookie database from the previous session are discarded, and no session cookies created during this session are persisted to the cookie database in a way that allows them to be restored.
WebContext.SessionCookieModePersistentSession cookies that exist in the cookie database from the previous session are discarded. Session cookies created during this session are persisted to the cookie database in a way that allows them to be restored.
WebContext.SessionCookieModeRestoredSession cookies that exist in the cookie database from the previous session are restored, and session cookies created during this session are persisted to the cookie database in a way that allows them to be restored. This is intended to be used by applications to recover from an unclean shutdown or for a web browser to provide session restore functionality.

Attempts to change this value after WebContext is constructed will have no effect.

The default value is WebContext.SessionCookieModePersistent.


userAgent : string

The default user agent string used for the User-Agent header in HTTP requests and for navigator.userAgent. By default, this is the Chrome user-agent string, with the product name based on the value of product.

Setting this to an empty string will restore the default value.

See also product.


userAgentOverrides : list<variant>

Allows the application to specify a list of per-URL overrides for the user-agent string.

The format is a list of variants. Each variant is a list of 2 strings. The first string is a regular expression used to match URLs. The second string is the override user-agent string to use in the case that the regular expression is a match for a URL.

Behaviour is unspecified for URLs that match more than one entry.

This QML property was introduced in OxideQt 1.9.


userScripts : list<UserScript>

This property holds the list of user scripts that will be injected in to web pages.


Method Documentation

void addUserScript(UserScript script)

Append script to the list of user scripts.

If script doesn't have a parent, then this WebContext will set itself as the parent and assume ownership of it.

If script already exists in the list of user scripts, then it will be moved to the end of the list.

If script is deleted after being added to the list of scripts, then it will be removed from the list automatically.


void removeUserScript(UserScript script)

Remove script from the list of user scripts.

If script is owned by this WebContext, then removing it will cause its parent to be cleared. This means that script will become unowned.