Sailfish Webview

API Documentation

WebEngineSettings Class

(SailfishOS::WebEngineSettings)

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

Header: #include <WebEngineSettings>

List of all members, including inherited members

Public Types

enum	ColorScheme { PrefersLightMode, PrefersDarkMode, FollowsAmbience }
enum	CookieBehavior { AcceptAll, BlockThirdParty, BlockAll }
enum	PreferenceType { UnknownPref, StringPref, IntPref, BoolPref }

Properties

autoLoadImages : bool
colorScheme : ColorScheme
cookieBehavior : CookieBehavior
doNotTrack : bool
downloadDir : QString

initialized : const bool
javascriptEnabled : bool
pixelRatio : qreal
popupEnabled : bool
useDownloadDir : bool

Public Functions

bool	autoLoadImages() const
ColorScheme	colorScheme() const
CookieBehavior	cookieBehavior() const
bool	doNotTrack() const
QString	downloadDir() const
void	enableLowPrecisionBuffers(bool enabled)
void	enableProgressivePainting(bool enabled)
bool	isInitialized() const
bool	javascriptEnabled() const
qreal	pixelRatio() const
bool	popupEnabled() const
void	setAutoLoadImages(bool enabled)
void	setColorScheme(ColorScheme colorScheme)
void	setCookieBehavior(CookieBehavior cookieBehavior)
void	setDoNotTrack(bool doNotTrack)
void	setDownloadDir(const QString &downloadDir)
void	setJavascriptEnabled(bool enabled)
void	setPixelRatio(qreal pixelRatio)
void	setPopupEnabled(bool enabled)
void	setPreference(const QString &key, const QVariant &value)
void	setPreference(const QString &key, const QVariant &value, PreferenceType preferenceType)
void	setTileSize(const QSize &size)
void	setUseDownloadDir(bool useDownloadDir)
bool	useDownloadDir() const

Signals

void	autoLoadImagesChanged()
void	cookieBehaviorChanged()
void	downloadDirChanged()
void	initialized()
void	javascriptEnabledChanged()
void	pixelRatioChanged()
void	popupEnabledChanged()
void	useDownloadDirChanged()

Static Public Members

void	initialize()
WebEngineSettings *	instance()

Detailed Description

Provides access to the global web engine settings.

Singleton class which provides access to the global Web engine settings.

Member Type Documentation

enum WebEngineSettings::ColorScheme

This enum type specifies the theme for the rendering engine to use.

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

enum WebEngineSettings::CookieBehavior

This enum type specifies the cookie behaviour for the engine to use.

Constant	Value	Description
`SailfishOS::WebEngineSettings::AcceptAll`	`0`	Accept all cookies independent of their origin.
`SailfishOS::WebEngineSettings::BlockThirdParty`	`1`	Accept cookies only if they are from the requested domain.
`SailfishOS::WebEngineSettings::BlockAll`	`2`	Do not accept any cookies.

enum WebEngineSettings::PreferenceType

This enum type specifies possible preference types that can used.

Constant	Value	Description
`SailfishOS::WebEngineSettings::UnknownPref`	`0`	Unknown preference type. WebEngineSettings interprets value on best effort basis.
`SailfishOS::WebEngineSettings::StringPref`	`32`	Preference interpreted as string type, commonly used with float as well.
`SailfishOS::WebEngineSettings::IntPref`	`64`	Preference interpreted as int type.
`SailfishOS::WebEngineSettings::BoolPref`	`128`	Preference interpreted as bool type (true or false).

Property Documentation

autoLoadImages : bool

This property holds 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.

Access functions:

bool	autoLoadImages() const
void	setAutoLoadImages(bool enabled)

Notifier signal:

void	autoLoadImagesChanged()

colorScheme : ColorScheme

This property holds 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.

Access functions:

ColorScheme	colorScheme() const
void	setColorScheme(ColorScheme colorScheme)

cookieBehavior : CookieBehavior

This property holds 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.

Access functions:

CookieBehavior	cookieBehavior() const
void	setCookieBehavior(CookieBehavior cookieBehavior)

Notifier signal:

void	cookieBehaviorChanged()

doNotTrack : bool

This property holds 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.

Access functions:

bool	doNotTrack() const
void	setDoNotTrack(bool doNotTrack)

downloadDir : QString

This property holds 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.

Access functions:

QString	downloadDir() const
void	setDownloadDir(const QString &downloadDir)

Notifier signal:

void	downloadDirChanged()

See also useDownloadDir.

initialized : const bool

This property holds whether the engine settings have been initialized.

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

Access functions:

bool	isInitialized() const

Notifier signal:

void	initialized()

See also WebEngine::initialize and QMozContext::initialize.

javascriptEnabled : bool

This property holds 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.

Access functions:

bool	javascriptEnabled() const
void	setJavascriptEnabled(bool enabled)

Notifier signal:

void	javascriptEnabledChanged()

pixelRatio : qreal

This property holds 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.

Access functions:

qreal	pixelRatio() const
void	setPixelRatio(qreal pixelRatio)

Notifier signal:

void	pixelRatioChanged()

See also WebView::resolution.

popupEnabled : bool

This property holds 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.

Access functions:

bool	popupEnabled() const
void	setPopupEnabled(bool enabled)

Notifier signal:

void	popupEnabledChanged()

useDownloadDir : bool

This property holds 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.

Access functions:

bool	useDownloadDir() const
void	setUseDownloadDir(bool useDownloadDir)

Notifier signal:

void	useDownloadDirChanged()

See also downloadDir.

Member Function Documentation

void WebEngineSettings::enableLowPrecisionBuffers(bool enabled)

Sets whether to enable low precision buffers.

When enabled the rendering engine will display low resolution tiles to the screen while the full resolution tiles are being rendered.

This can be used to make scrolling more responsive, but initially only showing a lower resolution version of the page.

This corresponds to the "layers.low-precision-buffer" gecko preference.

void WebEngineSettings::enableProgressivePainting(bool enabled)

Sets whether or not to use progressive rendering.

When enabled the rendering engine will use progressive rendering for the page.

This corresponds to the "layers.progressive-paint" gecko preference.

`[static]` void WebEngineSettings::initialize()

Initialises the WebEngineSettings class.

The initialize method sets up default gecko preferences needed in order for the WebView to work correctly.

If you need to set specific settings which differ from the default, it's recommended that you do so after this initialisation has been called, to avoid your settings being overwritten by it.

This will be called automatically during QML initialisation, but it can also be called manually in your code in order to control the order of initialisation. Calling this method after intialialisation has already been performed has no effect.

Hence the following is safe:

 SailfishOS::WebEngine::instance() *engineSettings = SailfishOS::WebEngineSettings::instance();
 engineSettings->initialize();
 engineSettings->setPreference(QStringLiteral("ui.textSelectBackground"), QLatin1String("#55ff55"));

`[static]` WebEngineSettings *WebEngineSettings::instance()

Returns the instance of the singleton WebEngineSettings class.

The returned instance may not be intialised.

See also initialize.

void WebEngineSettings::setPreference(const QString &key, const QVariant &value)

Directly set gecko engine preferences.

Sets the key preference to value.

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.

void WebEngineSettings::setPreference(const QString &key, const QVariant &value, PreferenceType preferenceType)

Directly set gecko engine preferences.

This function overloads setPreference().

Sets the key preference to value. The type is the type of the prererence value.

See also setPreference.

void WebEngineSettings::setTileSize(const QSize &size)

Sets the tile size used for rendering pages.

Setting the tile size is equivalent to setting the two gecko properties "layers.tile-width" and "layers.tile-height".

Sailfish Webview

Contents

WebEngineSettings Class

Public Types

Properties

Public Functions

Signals

Static Public Members

Detailed Description

Member Type Documentation

enum WebEngineSettings::ColorScheme

enum WebEngineSettings::CookieBehavior

enum WebEngineSettings::PreferenceType

Property Documentation

autoLoadImages : bool

colorScheme : ColorScheme

cookieBehavior : CookieBehavior

doNotTrack : bool

downloadDir : QString

initialized : const bool

javascriptEnabled : bool

pixelRatio : qreal

popupEnabled : bool

useDownloadDir : bool

Member Function Documentation

void WebEngineSettings::enableLowPrecisionBuffers(bool enabled)

void WebEngineSettings::enableProgressivePainting(bool enabled)

[static] void WebEngineSettings::initialize()

[static] WebEngineSettings *WebEngineSettings::instance()

void WebEngineSettings::setPreference(const QString &key, const QVariant &value)

void WebEngineSettings::setPreference(const QString &key, const QVariant &value, PreferenceType preferenceType)

void WebEngineSettings::setTileSize(const QSize &size)

`[static]` void WebEngineSettings::initialize()

`[static]` WebEngineSettings *WebEngineSettings::instance()