Each one of the properties, signals, and methods provided by Sailfish WebView falls into one of the three following categories:

• Stable attributes, as per the WebView type documentation
• Additional attributes
• Experimental attributes

This page documents the additional attributes of the Sailfish WebView. These additional attributes are unlikely to be used by the majority of application developers, however for some use cases they are likely to be useful.

These additional attributes should be largely stable, however we reserve the right to modify or remove any of these attributes in future versions of the Sailfish.WebView import if required.

Properties

WebView::webViewPage

WebViewPage-type property.

The WebViewPage the WebView is embedded in.

This will be populated automatically unless explicitly set.

WebView::canShowSelectionMarkers

bool-type property.

Display markers when the user selects text on a page.

If true the user will be able to select text and items on a page, indicated with handles. Set to false to disable the selection markers.

The default is true.

WebView::textSelectionActive

bool-type read-only property.

Indicates that text is currently being selected by the user.

This read only property will be set to true if the user is currently selecting text on the page, or false otherwise.

While text selection is active, the text selection controller will be receiving touch events (e.g. allowing the selection markers to be dragged) before the web view itself.

WebView::textSelectionController

Item-type property.

The item which handles text selection gestures.

If the client application doesn't explicitly provide a text selection controller, a default TextSelectionController from Sailfish.WebView.Controls will be constructed and used when required.

Any text selection controller provided by the client must conform to the required API. See the documentation for Sailfish.WebView.Controls for more information.

WebView::downloadsEnabled

bool-type property.

Whether downloads are enabled within the webview.

If downloads are enabled, long-press context menus will include options to save the link or image to the device, when appropriate.

WebView::virtualKeyboardMargin

real-type property.

The margin taken by the keyboard at the bottom of the page.

When using a WebView this property will be set automatically when the keyboard is opened or closed, and as such, most developers will never need to change the default behavior by setting this property manually.

In some special cases, if the application developer wishes to control precisely how web content should be arranged to compensate for the open keyboard (e.g. by allowing the keyboard to overlap the web content to some extent, for some reason), they can set this value manually.

WebView::orientation

Qt::ScreenOrientation-type property.

The orientation of the webview.

Ordinarily, the value of this property will follow the orientation of the (Silica) Page in which the web view is shown.

WebView::viewportWidth

real-type property.

The width of the webview viewport, in device pixels.

Note that the viewport width will usually be the same as the width of the web view, but in some cases clients may wish to set the viewport width explicitly (e.g. to show some chrome at one edge or the other, without obscuring some content underneath, while keeping the geometry of the web view item itself unchanged).

Device orientation should be considered when binding to this property.

See also: WebView::contentRect, WebView::orientation, WebView::viewportHeight

WebView::viewportHeight

real-type property.

The height of the webview viewport, in device pixels, which by default is bound to the screen height (in portrait orientation) or width (in landscape orientation).

Note that the viewport height will usually be the same as the height of the web view, but in some cases clients may wish to set the viewport height explicitly (e.g. to show some chrome at one edge or the other, without obscuring some content underneath, while keeping the geometry of the web view item itself unchanged).

Device orientation should be considered when binding to this property.

See also: WebView::contentRect, WebView::orientation, WebView::viewportWidth

WebView::atXBeginning

bool-type read-only property.

Whether the viewport of the webview is scrolled to the far-left of the content.

Effectively, the value of this property will be true if the WebView::scrollableOffset x-value is approximately zero (due to floating-point number comparison semantics).

See also: WebView::atXEnd, WebView::scrollableOffset

WebView::atXEnd

bool-type read-only property.

Whether the viewport of the webview is scrolled to the far-right of the content.

Effectively, the value of this property will be true if the WebView::scrollableOffset x-value plus the (WebView::resolution scaled) WebView::contentRect width is approximately equal to or greater than the WebView::scrollableSize width.

See also: WebView::atXBeginning, WebView::scrollableOffset, WebView::scrollableSize, WebView::contentRect

WebView::atYBeginning

bool-type read-only property.

Whether the viewport of the webview is scrolled to the top of the content.

Effectively, the value of this property will be true if the WebView::scrollableOffset y-value is approximately zero (due to floating-point number comparison semantics).

See also: WebView::atYEnd, WebView::scrollableOffset

WebView::atYEnd

bool-type read-only property.

Whether the viewport of the webview is scrolled to the bottom of the content.

Effectively, the value of this property will be true if the WebView::scrollableOffset y-value plus the (WebView::resolution scaled) WebView::contentRect height is approximately equal to or greater than the WebView::scrollableSize height.

See also: WebView::atYBeginning, WebView::scrollableOffset, WebView::scrollableSize, WebView::contentRect

WebView::dragging

bool-type read-only property.

Whether the user is currently dragging the scrollable area.

Note that if the touch events are being consumed by the content (e.g. panning within a maps application, which causes loading new tiles), rather than the web view itself, this property will not be set.

WebView::moving

bool-type read-only property.

Whether the scrollable area is currently moving due to inertia from a previous drag gesture.

WebView::pinching

bool-type read-only property.

Whether the user is currently performing a pinch gesture in order to zoom the web view.

Note that if the touch events are being consumed by the content (e.g. zooming within a maps application, which causes loading new higher-resolution tiles), rather than the web view itself, this property will not be set.

WebView::chrome

bool-type property.

Whether the chrome (i.e. user interface elements for navigation) is visible.

When using the web view component, no navigation chrome is shown. If you want to mimic the behaviour of the chrome toolbar in the browser, then you can show or hide your custom navigation chrome elements according to the value of this property.

By default, the chrome will be shown or hidden in response to certain gestures. The client can override this behavior by setting the value manually.

See also: WebView::chromeGestureEnabled, WebView::chromeGestureThreshold

WebView::chromeGestureEnabled

bool-type property.

Whether the gesture to show the navigation chrome is enabled.

If true, chrome is set to false (hiding the navigation chrome) when a pan or flick gesture causes movement exceeding the chromeGestureThreshold, and automatically set back to true when a similar gesture in the opposite direction is detected.

See also: WebView::chrome, WebView::chromeGestureThreshold

WebView::chromeGestureThreshold

real-type property.

The movement threshold for detecting a chrome gesture.

See also: WebView::chromeGestureEnabled, WebView::chrome

WebView::desktopMode

bool-type property.

Whether the web view will attempt to load the desktop version of the site rather than the mobile version.

It depends on the web service whether the desktop mode can be served or not.

WebView::backgroundColor

color-type read-only property.

The background color currently specified by the loaded page.

Signals

WebView::recvAsyncMessage(string message, variant data)

Emitted if the async message is not handled by the built-in handler, and a message listener has been registered for the specified message.

Clients who have their own handling for async messages can connect to this signal in order to implement custom behavior.

Methods

WebView::addMessageListener(string name)

Register a listener for asynchronous messages with the specified name.

The web view will emit recvAsyncMessage() for messages with that name which are sent by event handlers etc.

WebView::sendAsyncMessage(string name, variant data)

Send an asynchronous message with the specified name and data.

If a message listener is registered for the message, the listener will be delivered the message.

WebView::loadFrameScript(string name)

Loads the specified frame script.

A frame script is JavaScript which is loaded before any content, and has the ability to manipulate the content DOM.

A developer could load a custom frame script for their WebView instance in order to add an event listener of some kind (via addEventListener()), do some custom handling of the event, and then notify the application via an async message.

e.g.

 webView.loadFrameScript(Qt.resolvedUrl("customframescript.js"));
 webView.addMessageListener("appMessageHandler")

where the custom frame script has something like:

 document.addEventListener("click", function() {
     sendAsyncMessage("appMessageHandler", {"click": true})
     // the web view will emit recvAsyncMessage().
 });