Sailfish Webview

API Documentation

WebEngineSettings QML Type

Provides access to the global Web engine settings. More...

Import Statement: import Sailfish.WebEngine 1.0

List of all members, including inherited members

Properties

autoLoadImages : bool
colorScheme : bool
cookieBehavior : enumeration
doNotTrack : bool
downloadDir : string
initialized : bool
javascriptEnabled : bool
pixelRatio : real
popupEnabled : bool
useDownloadDir : bool

Methods

setPreference(key, value, type)

Detailed Description

The WebEngineSettings component is a singleton which provides access to the global Web engine settings.

The WebEngineSettings QML type is exposed through the Sailfish.WebEngine QML import namespace.

Example of use:

 import QtQuick 2.0
 import Sailfish.Silica 1.0
 import Sailfish.WebView 1.0
 import Sailfish.WebEngine 1.0

 ApplicationWindow {
     id: root
     initialPage: Component {
         WebViewPage {
             WebView {
                 anchors.fill: parent
                 url: "http://www.sailfishos.org"
             }

             Component.onCompleted: {
                 WebEngineSettings.autoLoadImages = false
                 WebEngineSettings.javascriptEnabled = false
             }
         }
     }
 }

See also WebView and WebEngine.

Property Documentation

autoLoadImages : bool

Whether to automatically load images.

When set to true images will be automatically downloaded and rendered. When set to false images will not be downloaded.

The default value is true.

This corresponds to the "permissions.default.image" gecko preference.

Setting this property to false can help avoid tracking by external servers when rendering local content, but may prevent a page from rendering correctly.

colorScheme : bool

The theme to prefer when rendering websites.

Some websites provide sepearate "dark" and "light" themes. The value of this property determines which of the variants the browser will use to render the site:

The colour scheme can be one of:

Constant	Description
`WebEngineSettings.PrefersLightMode`	Use the light theme for the website if one is available.
`WebEngineSettings.PrefersDarkMode`	Use the dark theme for the website if one is available.
`WebEngineSettings.FollowsAmbience`	Select a theme (light or dark) depending on the current ambience.

This corresponds to the "ui.systemUsesDarkTheme" gecko preference.

cookieBehavior : enumeration

The cookie behaviour.

The cookie behaviour can be one of:

Constant	Description
`WebEngineSettings.AcceptAll`	Accept all cookies independent of their origin, the default
`WebEngineSettings.BlockThirdParty`	Accept cookies only if they are from the requested domain.
`WebEngineSettings.BlockAll`	Do not accept any cookies.

This corresponds to the "network.cookie.cookieBehavior" gecko preference.

doNotTrack : bool

Whether or not to send Do Not Track requests to websites

When set to true the browser will send "Do Not Track" requests to websites using the DNT header field.

This corresponds to the "privacy.donottrackheader.enabled" gecko preference.

downloadDir : string

The location to save downloaded files to.

Specifies an absolute path location to save downloaded files to. This property applies only if the useDownloadDir property is set to true.

This corresponds to the "browser.download.downloadDir" gecko preference.

See also useDownloadDir.

initialized : bool

Whether the engine settings have been initialized.

This property returns true when the engine settings have been initialized and false otherwise

See also WebEngine::initialized and WebEngine::initialize.

javascriptEnabled : bool

Whether JavaScript on the page will be automatically executed.

When set to true JavaScript on the page will be executed. When set to false JavaScript will not be executed.

The default value is true.

This corresponds to the "javascript.enabled" gecko preference.

Disabling JavaScript may be beneficial for security, privacy or efficiency reasons, but may also prevent pages from rendering correctly.

pixelRatio : real

The device to logical pixel ratio.

This property represents the number of physical device pixels used to represent each logical pixel of the web rendering.

Hence, a pixelRatio of 2 will cause items to be rendered on screen with twice the dimensions (covering four times the area) as a pixelRatio of 1, for example.

This corresponds to the "layout.css.devPixelsPerPx" gecko preference.

Note: Unlike desktop Firefox, changing this value will only change the rendering of web content; it does not affect the UI scaling.

popupEnabled : bool

Whether to allow popups to open during page loading.

When set to true any popups the page requests to open during loading will be allowed to open. When set to false requests for popups will be blocked from being actioned.

The default value is false.

This corresponds to the "dom.disable_open_during_load" gecko preference.

useDownloadDir : bool

Whether or not to use the default download location.

When set to true downloaded files will be saved to the default download location, as specified by the downloadDir property. When set to false the user will be asked to specify a location for each file downloaded.

This corresponds to the "browser.download.useDownloadDir" gecko preference.

See also downloadDir.

Method Documentation

setPreference(key, value, type)

Directly set gecko engine preferences.

Sets the key preference to value. The type is an optional argument that is by default QMozEngineSettings.UnknownPref.

The type can be one of:

Constant	Description
`WebEngineSettings.UnknownPref`	Unknown preference type, the default. WebEngineSettings interprets value on best effort basis
`WebEngineSettings.StringPref`	Preference interpreted as string type, commonly used with float as well.
`WebEngineSettings.IntPref`	Preference interpreted as int type.
`WebEngineSettings.BoolPref`	Preference interpreted as bool type (true or false).

This is a low-level API to set engine preferences. Higher-level calls, such as those provided by WebEngineSettings, WebEngine and WebView should be used in preference whenever possible.

See the MDN docs for more info about the available preferences.