WebSettings
Since: BlackBerry 10.0.0
#include <bb/cascades/WebSettings>
Settings for the WebView control.
Each WebView instance has an associated WebSettings instance, which can be referenced by reading the WebView settings property. You should never have any reason to create an instance of this class yourself. This class has to be a QObject derivative in order to be accessible from QML.
Overview
QML properties
activeTextEnabled | : bool |
background | : bb::cascades::Color |
binaryFontDownloadingEnabled | : bool |
certificatePath | : QString |
cookiesEnabled | : bool |
credentialAutoFillEnabled | : bool |
customHttpHeaders | : QVariantMap |
defaultFontSize | : int |
defaultFontSizeFollowsSystemFontSize | : bool |
defaultTextCodecName | : QString |
devicePixelRatio | : double |
formAutoFillEnabled | : bool |
imageDownloadingEnabled | : bool |
javaScriptEnabled | : bool |
minimumFontSize | : int |
spatialNavigationEnabled | : bool |
textAutosizingEnabled | : bool |
userAgent | : QString |
userStyleSheetLocation | : QUrl |
viewport | : QVariantMap |
webInspectorEnabled | : bool |
zoomToFitEnabled | : bool |
QML signals
Properties Index
Public Functions Index
Signals Index
bool | activeTextEnabledChanged (bool enabled) |
void | backgroundChanged (const QVariant &newBackground) |
void | binaryFontDownloadingEnabledChanged (bool enabled) |
void | certificatePathChanged (const QString &path) |
void | cookiesEnabledChanged (bool enabled) |
void | credentialAutoFillEnabledChanged (bool enabled) |
void | customHttpHeadersChanged (const QVariantMap &newCustomHttpHeaders) |
void | defaultFontSizeChanged (int newDefaultFontSize) |
void | defaultFontSizeFollowsSystemFontSizeChanged (bool newDefaultFontSizeFollowsSystemFontSize) |
void | defaultTextCodecNameChanged (const QString &codec) |
void | devicePixelRatioChanged (double newDevicePixelRatio) |
void | formAutoFillEnabledChanged (bool enabled) |
void | imageDownloadingEnabledChanged (bool enabled) |
void | javaScriptEnabledChanged (bool enabled) |
void | minimumFontSizeChanged (int newMinimumFontSize) |
void | spatialNavigationEnabledChanged (bool enabled) |
void | textAutosizingEnabledChanged (bool enabled) |
void | userAgentChanged (QString newUserAgent) |
void | userStyleSheetLocationChanged (QUrl newUserStyleSheetLocation) |
void | viewportArgumentsChanged (const QVariantMap &newViewportArguments) |
void | webInspectorEnabledChanged (bool enabled) |
void | zoomToFitEnabledChanged (bool enabled) |
Properties
bool
Specifies whether a post-processor should run over loaded content to highlight any activeText segments and connect them to the Invocation Framework.
BlackBerry 10.0.0
QVariant
Sets the background color of the webpage.
If you wish to enable controls behind the WebView to appear through the webpage, you must set a non-opaque color.
The default is opaque white.
BlackBerry 10.0.0
bool
Specifies whether binary "WebFonts" should be loaded automatically.
The default is true.
BlackBerry 10.0.0
QString
Set the path that stores trusted certificates for the WebView.
This property sets a directory that stores trusted certificates for HTTPS connections created from this WebView. It can be used to restrict the trusted certificates to those in a particular location. If it is not set, the default certificate store (which includes certificates from several locations) is used.
BlackBerry 10.3.2
bool
Specifies whether network cookies should be enabled.
The default is true.
BlackBerry 10.0.0
bool
Specifies whether known credentials can be automatically submitted with HTTP requests.
The default is false, setting this to true can reduce the number of times the user is prompted for credentials.
BlackBerry 10.1.0
BlackBerry 10.3.1 The web browser engine always enables auto fill of credentials, the value of the credentialAutoFillEnabled setting is ignored.
QVariantMap
Specifies custom HTTP headers that will be added to every outgoing network request.
Each key value pair in the map will be converted to UTF8 strings and added to outgoing requests as "<key>: <value>".
WebView { url: "http://myserver.mynetwork.net/anycontent.html" settings.customHttpHeaders: { "Pragma": "no-cache" } }The default is an empty map, i.e. no custom HTTP headers.
BlackBerry 10.0.0
int
Specifies a default font size (in CSS pixels) to use when none is present in the HTML.
The default is 16.
BlackBerry 10.0.0
bool
Specifies that the default font size should follow the system font size.
Any value set using the defaultFontSize property will be ignored while this setting is true.
If your web content uses relative font sizes, like em or %, enabling this setting will allow the user to control the font size of your content using the system font size setting.
Please note that the textAutosizingEnabled feature already accounts for system font size, so it's not recommended to have both defaultFontSizeFollowsSystemFontSize and textAutosizingEnabled simultaneously set to true.
The default is false.
BlackBerry 10.0.0
QString
Sets the default character encoding fallback for when no encoding information is available.
The default is ISO-8859-1.
BlackBerry 10.1.0
double
Specifies the default scaling factor.
The devicePixelRatio is the ratio between physical pixels and device-independent pixels (CSS pixels) on the device.
Increasing devicePixelRatio will zoom in the content and decreasing it will zoom out the content.
Beyond the devicePixelRatio, which scales the very CSS pixels of the webpage, the web content can also be scaled due to zoomToFitEnabled being set to true. An "initial-scale" viewport argument present on the web page or injected using the viewport property can also influence scaling. The "initial-scale" is a multiplier applied in addition to the devicePixelRatio.
There are two approaches to scaling your web content.
Use the default devicePixelRatio to optimize for a mix of desktop and mobile web content. Typically, the default value is appropriate for loading existing web content from the world wide web. At the default devicePixelRatio, a font size of ~16 CSS pixels is pleasant to read. The user may adjust the system font size setting if they prefer bigger or smaller text, and the textAutosizingEnabled feature (enabled by default) takes the system font size setting into account when adjusting font size for improved readability. Enabling defaultFontSizeFollowsSystemFontSize is not recommended in this scenario.
Use a devicePixelRatio of 1.0 and tailor your web content to fit the standard screen width of BlackBerry 10 devices. Typically, a value of 1.0 is used when the web content is created specifically for BlackBerry 10 devices. At this devicePixelRatio, a font size of ~40 CSS pixels is pleasant to read, but you can enable defaultFontSizeFollowsSystemFontSize to have the default font size be adjusted to exactly match the system font size setting. When using a devicePixelRatio of 1.0, defaultFontSizeFollowsSystemFontSize is recommended over the textAutosizingEnabled feature. The text autosizing algorithm can't properly adjust font sizes without an accurate devicePixelRatio value.
BlackBerry 10.0.0
bool
Specifies whether known form fields can be automatically filled out on the user's behalf.
The default is false, setting to true can reduce the amount of input the user needs to type.
BlackBerry 10.1.0
bool
Specifies whether images should be loaded automatically.
The default is true.
BlackBerry 10.0.0
bool
Indicates whether the execution of JavaScript should be enabled in the main frame of the webpage.
The default is true.
BlackBerry 10.0.0
int
Specifies a minimum font size in CSS pixels.
The default is 8.
BlackBerry 10.0.0
bool
Specifies whether text will have its font size automatically adjusted for improved readability.
Web content designed for desktop web browsers can contain text too small to be readable when the column of text is zoomed to fit the screen width. Text autosizing improves the situation by adjusting font size of text depending on column width and the screen's pixel density (DPI). If the user has changed the system font size setting, the effects of the text autosizing algorithm will be attenuated (if system font size is smaller than the default setting) or magnified (if the system font size is greater) to accommodate the user's setting.
This means that the text autosizing feature already accounts for system font size, so it's not recommended to have both defaultFontSizeFollowsSystemFontSize and textAutosizingEnabled simultaneously set to true.
To determine the scaling required, the text autosizing algorithm depends on the devicePixelRatio, so autosizing works best if devicePixelRatio is left at it's default value. Setting devicePixelRatio to 1.0 effectively disables autosizing.
The default is true.
BlackBerry 10.2.0
QString
Specifies a userAgent string to be used instead of the device default userAgent.
The default is the same as the userAgent employed by the BlackBerry Browser; it depends on the form factor and operating system version present on the device.
BlackBerry 10.0.0
QUrl
Specifies a default override CSS file location.
The default is an empty URL, which indicates that there is no user style sheet.
BlackBerry 10.0.0
QVariantMap
Exposes all of the arguments of the HTML Meta Viewport Tag.
This map can be assigned a series of key value pairs from the following sets:
The following case-sensitive strings are accepted as keys: { "initial-scale", "minimum-scale", "maximum-scale", "width", "height", "user-scalable" }
The "initial-scale" is a multiplier applied in addition to the devicePixelRatio.
The following case-sensitive strings are accepted for all viewport values though not all of them are necessarily useful for each property: { "auto", "desktop-width", "device-width", "device-height" }
In addition, any non-negative floating point values are also acceptable.
To set a common type of meta viewport tag that requests that the content be laid out to the screen width in the current orientation, and zoomed 1:1, use this:
The default is an empty map which indicates no user specified viewport meta tag should be used.
WebView { id: webView url: "http://myserver.mynetwork.net/anycontent.html" settings.viewport: { "initial-scale" : 1.0 } }
BlackBerry 10.0.0
bool
Indicates whether the execution of JavaScript should be enabled in the main frame of the webpage.
The default is false. The WebInspector is specifically for debugging and should never be enabled in released software.
BlackBerry 10.0.0
bool
Specifies whether the content should be zoomed out to fit the screen upon loading.
The default is true.
BlackBerry 10.0.0
Public Functions
QVariant
Gets the background of this WebView.
The QVariant returned wraps around a bb::cascades::Paint instance.
BlackBerry 10.0.0
QString
Gets the path that stores trusted certificates for HTTPS connections.
A filesystem path, or the empty string if the default certificate store is used.
BlackBerry 10.3.2
QVariantMap
Gets a map of custom HTTP headers that will be added to every outgoing network request.
An empty map indicates no custom HTTP headers are in use.
A map where each key value pair corresponds to an HTTP header.
BlackBerry 10.0.0
bool
Gets whether the default font size follows the system font size.
BlackBerry 10.0.0
double
Gets device pixel ratio.
BlackBerry 10.0.0
bool
Gets whether or not active text matching after loading is enabled for the WebView.
BlackBerry 10.0.0
bool
Gets whether or not credentials are automatically filled if available.
BlackBerry 10.1.0
BlackBerry 10.3.1 The web browser engine always enables auto fill of credentials.
bool
Gets whether or not forms are automatically filled if available.
BlackBerry 10.1.0
bool
Gets whether or not font sizes are automatically increased to make text legible.
BlackBerry 10.2.0
bool
Gets whether or not zoom to fit after loading is enabled for the WebView.
Any zooming done due to this setting is a multiplier applied in addition to the devicePixelRatio. Viewport arguments present on the webpage or injected using the viewport property will override this setting and prevent zooming to fit.
BlackBerry 10.0.0
Q_SLOT void
Resets active text matching to false.
BlackBerry 10.0.0
Q_SLOT void
Resets the background to opaque white.
BlackBerry 10.0.0
Q_SLOT void
Resets binary font downloading to true.
BlackBerry 10.0.0
Q_SLOT void
Resets the trusted certificate path to the default.
BlackBerry 10.3.2
Q_SLOT void
Resets cookies enabled to true.
BlackBerry 10.0.0
Q_SLOT void
Resets credential auto fill to default.
BlackBerry 10.1.0
BlackBerry 10.3.1
Q_SLOT void
Resets the custom HTTP headers to an empty map.
BlackBerry 10.0.0
Q_SLOT void
Resets the default font size to its default value of 16.
BlackBerry 10.0.0
Q_SLOT void
Resets whether the default font size follows the system font size to the default value of false.
BlackBerry 10.0.0
Q_SLOT void
Resets back to default encoding of ISO-8859-1.
BlackBerry 10.1.0
Q_SLOT void
Resets device pixel ratio to default value.
Default value is the ratio between physical pixels and dips on the device.
BlackBerry 10.0.0
Q_SLOT void
Resets form auto fill to default.
BlackBerry 10.1.0
Q_SLOT void
Resets imageDownloadingEnabled to its default value of true.
BlackBerry 10.0.0
Q_SLOT void
Resets javaScriptEnabled to its default value of true.
BlackBerry 10.0.0
Q_SLOT void
Resets the minimum font size to its default value of 8.
BlackBerry 10.0.0
Q_SLOT void
Resets back to the default, which is to enable text autosizing.
BlackBerry 10.2.0
Q_SLOT void
Resets the user style sheet to its default value of an empty URL.
BlackBerry 10.0.0
Q_SLOT void
Resets the user viewport arguments to an empty map.
BlackBerry 10.0.0
Q_SLOT void
Resets the web inspector to being disabled.
BlackBerry 10.0.0
Q_SLOT void
Resets zoom to fit enabled to true.
BlackBerry 10.0.0
Q_SLOT void
Sets activeText parsing enabled.
Parameters | |
---|---|
enabled |
Set true to enable active text matching, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets a bb::cascades::Paint& background for this WebView.
Presently only ColorPaint is supported. Other Paints will be ignored. A non-opaque color can be used to allow controls behind this WebView to be visible.
The default background is opaque white.
This setting takes effect when the webpage is reloaded.
Parameters | |
---|---|
paint |
A ColorPaint to be used as a background for this WebView. |
BlackBerry 10.0.0
Q_SLOT void
Sets whether or not WebFonts should be downloaded.
Parameters | |
---|---|
enabled |
Set true to enable downloading of web fonts, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets the path that stores trusted certificates for HTTPS connections.
Parameters | |
---|---|
path |
A filesystem path, or the empty string to use the default certificate store. |
BlackBerry 10.3.2
Q_SLOT void
Sets whether or not cookies should be enabled.
Parameters | |
---|---|
enabled |
Set true to enable cookies, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets whether or not credentials are automatically filled if available.
Parameters | |
---|---|
enabled |
Set true to enable credential auto fill. |
BlackBerry 10.1.0
BlackBerry 10.3.1 The web browser engine always enables auto fill of credentials, the value of the credentialAutoFillEnabled setting is ignored.
Q_SLOT void
Sets a map of custom HTTP headers to be added to every outgoing network request.
Parameters | |
---|---|
httpHeaders |
A QVariantMap where each key value pair corresponds to an HTTP header. |
BlackBerry 10.0.0
Q_SLOT void
Sets the default font size for the WebView.
Parameters | |
---|---|
size |
A default font size in CSS pixels. |
BlackBerry 10.0.0
Q_SLOT void
Sets whether the default font size follows the system font size.
Parameters | |
---|---|
follows |
Set true to enable this feature, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets a default character encoding.
Parameters | |
---|---|
codec |
The encoding to be used when no other encoding information is available. |
BlackBerry 10.1.0
Q_SLOT void
Sets device pixel ratio.
Parameters | |
---|---|
ratio |
A pixel ratio. |
BlackBerry 10.0.0
Q_SLOT void
Sets whether or not forms are automatically filled if available.
Parameters | |
---|---|
enabled |
Set true to enable form auto fill. |
BlackBerry 10.1.0
Q_SLOT void
Sets whether images will be downloaded by the WebView.
Parameters | |
---|---|
enabled |
Set true to enable image downloading, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Set whether JavaScript will be enabled on the WebView.
This setting takes effect when the webpage is reloaded.
Parameters | |
---|---|
enabled |
Set true to enable JavaScript, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets the WebView minimum font size.
Parameters | |
---|---|
size |
A minimum font size in CSS pixels. |
BlackBerry 10.0.0
Q_SLOT void
Sets whether or not font sizes are automatically increased to make text legible.
Parameters | |
---|---|
enabled |
Set true to enable text autosizing, false to disable. |
BlackBerry 10.2.0
Q_SLOT void
Sets a userAgent string to use instead of the default userAgent.
Parameters | |
---|---|
userAgent |
A new user agent string to use with outgoing HTTP requests. |
BlackBerry 10.0.0
Q_SLOT void
Sets a location for a default CSS file.
Parameters | |
---|---|
location |
A URL to a file containing default CSS. |
BlackBerry 10.0.0
Q_SLOT void
Sets a map of meta viewport arguments.
Parameters | |
---|---|
arguments |
A QVariantMap of viewport arguments to be used if none is specified in the HTML. |
BlackBerry 10.0.0
Q_SLOT void
Sets the WebInspector on or off.
Parameters | |
---|---|
enabled |
Set true to enable the WebInspector, false to disable. |
BlackBerry 10.0.0
Q_SLOT void
Sets zoom to fit behaviour for the WebView.
Parameters | |
---|---|
enabled |
Set true to enable zoom to fit on load, false to disable. |
BlackBerry 10.0.0
QUrl
Gets the userStyleSheetLocation for the WebView.
An empty QUrl indicates no user stylesheet is in use.
BlackBerry 10.0.0
QVariantMap
Gets a map of user viewport arguments for the WebView.
An empty map indicates no user viewport arguments are in use.
BlackBerry 10.0.0
Signals
bool
Emitted when active text matching enabled changes.
Parameters | |
---|---|
enabled |
Whether active text matching is enabled or disabled. |
BlackBerry 10.0.0
void
Emitted when the background setting changes.
The newBackground QVariant provided wraps a bb::cascades::Paint instance.
Parameters | |
---|---|
newBackground |
The new background |
BlackBerry 10.0.0
void
Emitted when web font downloading enabled changed.
Parameters | |
---|---|
enabled |
Whether web font downloading is enabled or disabled. |
BlackBerry 10.0.0
void
Emitted when the trusted certificate path for HTTPS connections changes.
Parameters | |
---|---|
path |
A filesystem path, or the empty string to use the default certificate store. |
BlackBerry 10.3.2
void
Emitted when cookies enabled changed.
Parameters | |
---|---|
enabled |
Whether cookies are enabled or disabled. |
BlackBerry 10.0.0
void
Emitted when credential auto fill changes.
Parameters | |
---|---|
enabled |
Whether credential auto fill is enabled. |
BlackBerry 10.1.0
BlackBerry 10.3.1
void
Emitted when the custom HTTP headers change.
Parameters | |
---|---|
newCustomHttpHeaders |
The new custom HTTP headers. |
BlackBerry 10.0.0
void
Emitted when the default font size changes.
Parameters | |
---|---|
newDefaultFontSize |
The new default font size. |
BlackBerry 10.0.0
void
Emitted when the default font size starts or stops following the system font size.
Parameters | |
---|---|
newDefaultFontSizeFollowsSystemFontSize |
The new value of the setting. |
BlackBerry 10.0.0
void
Emitted when the default character encoding changes.
Parameters | |
---|---|
codec |
The new default character encoding. |
BlackBerry 10.1.0
void
Emitted when the device pixel ratio changes.
Parameters | |
---|---|
newDevicePixelRatio |
The new device pixel ratio. |
BlackBerry 10.0.0
void
Emitted when form auto fill changes.
Parameters | |
---|---|
enabled |
Whether form auto fill is enabled. |
BlackBerry 10.1.0
void
Emitted when image downloading enabled changes.
Parameters | |
---|---|
enabled |
Whether image downloading is enabled or not. |
BlackBerry 10.0.0
void
Emitted when JavaScript enabled changes.
Parameters | |
---|---|
enabled |
Whether JavaScript is enabled or not. |
BlackBerry 10.0.0
void
Emitted when the minimum font size changes.
Parameters | |
---|---|
newMinimumFontSize |
The new minimum font size. |
BlackBerry 10.0.0
void
Emitted when text autosizing changes.
Parameters | |
---|---|
enabled |
Whether text autosizing is enabled. |
BlackBerry 10.2.0
void
Emitted when the user agent string changes.
Parameters | |
---|---|
newUserAgent |
The new user agent string. |
BlackBerry 10.0.0
void
Emitted when the user style sheet location changes.
Parameters | |
---|---|
newUserStyleSheetLocation |
The new user style sheet location. |
BlackBerry 10.0.0
void
Emitted when the map of user viewport arguments changes.
Parameters | |
---|---|
newViewportArguments |
The new map of user viewport arguments. |
BlackBerry 10.0.0
void
Emitted when web inspector enabled changes.
Parameters | |
---|---|
enabled |
Whether the web inspector is enabled or disabled. |
BlackBerry 10.0.0
void
Emitted when zoom to fit enabled changes.
Parameters | |
---|---|
enabled |
Whether zoom to fit is enabled or disabled. |
BlackBerry 10.0.0