WebPage

Since: BlackBerry 10.0.0

#include <bb/cascades/WebPage>

A webpage that can be used when the app needs to interact with web content but not display it.

This class can also be used together with a WebPageCompositor in order to render web content to a custom OpenGL scene.

If user input events need to be forwarded to the webpage, or simulated, a WebPageEventHandler can be used together with this class.

Note:

The WebPage class must only be used on the main thread. It's not reentrant, unlike WebPageCompositor and WebPageEventHandler. The compositor and event handler can be created on another thread and connected to the webpage if given its uniqueId. Since the uniqueId is a string, it can be marshalled to the thread where the compositor or event handler was created. See WebPageCompositor for sample code.

WebPage is normally used from C++, but here is an example of using WebPage in QML:
import bb.cascades 1.2
import WebPageComponent 1.0

Page {
    Container {
        Label {
            id: statusLabel
        }
        attachedObjects: [
            WebPage {
                id: page
                url: "http://www.example.com"
                onTitleChanged: {
                    statusLabel.setText(title)
                }
            }
        ]
    }
}
Add the following lines to the C++ main program to register WebPage with QML:
qmlRegisterType<bb::cascades::WebPage>("WebPageComponent", 1, 0,"WebPage");


Overview

QML properties

canGoBack: bool [read-only]
canGoForward: bool [read-only]
dialogWebPage: WebPage
icon: QUrl [read-only]
loading: bool [read-only]
loadProgress: int [read-only]
maxContentScale: float [read-only]
minContentScale: float [read-only]
settings: bb::cascades::WebSettings [read-only]
storage: bb::cascades::WebStorage [read-only]
title: QString [read-only]
uniqueId: QString [read-only]
url: QUrl

Properties Index

boolcanGoBack [read-only]
boolcanGoForward [read-only]
WebPagedialogWebPage
QUrlicon [read-only]
boolloading [read-only]
intloadProgress [read-only]
floatmaxContentScale [read-only]
floatminContentScale [read-only]
bb::cascades::WebSettingssettings [read-only]
bb::cascades::WebStoragestorage [read-only]
QStringtitle [read-only]
QStringuniqueId [read-only]
QUrlurl

Public Functions Index

WebPage (QObject *parent=0)
virtual ~WebPage ()
boolcanGoBack () const
boolcanGoForward () const
bb::cascades::WebPage *dialogWebPage () const
voiddownload (WebDownloadRequest *request)
intevaluateJavaScript (const QString &script, JavaScriptWorld::Type world)
voidfindText (const QString &subString, WebFindFlag::Types options=0)
QUrlicon () const
voidloadData (const QByteArray &data, const QString &mimeType, const QUrl &baseUrl)
voidloadFile (const QUrl &fileUrl, const QString &mimeType)
boolloading () const
intloadProgress () const
floatmaxContentScale () const
floatminContentScale () const
voidsetResourceRequestFilter (WebResourceRequestFilter *filter)
bb::cascades::WebSettings *settings () const
voidsetUrl (const QUrl &url)
bb::cascades::WebStorage *storage ()
QStringtitle () const
QStringuniqueId () const
QUrlurl () const

Public Slots Index

voidgoBack ()
voidgoForward ()
voidpostMessage (const QString &message)
voidreload ()
voidresetDialogWebPage ()
voidsetDialogWebPage (bb::cascades::WebPage *page)
voidsetSelection (float x1, float y1, float x2, float y2)
voidstop ()

Signals Index

voidcontextMenuHideRequested ()
voidcontextMenuShowRequested (bb::cascades::ActionSet *actionSet)
voiddialogHideRequested ()
voiddialogShowRequested ()
voiddialogWebPageChanged (bb::cascades::WebPage *newDialogWebPage)
voidenterFullScreenRequested ()
voidexitFullScreenRequested ()
voidiconChanged (const QUrl &icon)
voidinitialized (const QString &uniqueId)
voidjavaScriptInterrupted ()
voidjavaScriptResult (int resultId, const QVariant &result)
voidloadingChanged (bb::cascades::WebLoadRequest *loadRequest)
voidloadProgressChanged (int loadProgress)
voidmaxContentScaleChanged (float maxContentScale)
voidmessageReceived (const QVariantMap &message)
voidmicroFocusChanged ()
voidminContentScaleChanged (float minContentScale)
voidnavigationHistoryChanged ()
voidnavigationRequested (bb::cascades::WebNavigationRequest *request)
voidtitleChanged (const QString &title)
voidurlChanged (const QUrl &url)

Properties

bool canGoBack[read-only]

True if the navigation history contains a previous page.

Since:

BlackBerry 10.0.0

bool canGoForward[read-only]

True if the navigation history contains a next page.

Since:

BlackBerry 10.0.0

WebPage dialogWebPage

The webpage to use for displaying modal dialog content.

Interaction with the webpage, particularly form controls, can trigger various modal dialogs. These are themselves built from web content, and should be displayed in a separate WebPage object.

The initial value of this property is 0. The modal dialog functionality is optional, and is disabled when the value of the dialogWebPage property is 0.

If a separate WebPage to be used for modal dialogs is provided by setting this property to a non-0 value, the app must handle the dialogShowRequested() signal to display that webpage to the user, and allow interaction with that webpage. WebPageCompositor and :WebPageEventHandler can be used for this purpose. The app must also handle the dialogHideRequested() signal to hide that webpage.

Note:

If the dialogWebPage is non-0 but is not displayed and/or not interactive after prompted by dialogShowRequested(), the modal dialog sequence will not be executed properly, and dialogHideRequested() will never be emitted. It's therefore not recommended to change the value of this property unless the app is prepared to handle the dialogShowRequested() signal properly.

Since:

BlackBerry 10.0.0

QUrl icon[read-only]

The favicon of the currently loaded webpage.

Since:

BlackBerry 10.0.0

bool loading[read-only]

True if the web view is currently loading a webpage, false otherwise.

Since:

BlackBerry 10.0.0

int loadProgress[read-only]

The progress of loading the current webpage.

Since:

BlackBerry 10.0.0

float maxContentScale[read-only]

Suggested maximum content scale factor for pinch zoom.

Since:

BlackBerry 10.0.0

float minContentScale[read-only]

Suggested minimum content scale factor for pinch zoom.

Since:

BlackBerry 10.0.0

bb::cascades::WebSettings settings[read-only]

Settings for this webpage.

Since:

BlackBerry 10.0.0

bb::cascades::WebStorage storage[read-only]

Access to the web storage interface used to clear databases and access cookies.

Since:

BlackBerry 10.0.0

QString title[read-only]

The title of the currently loaded webpage.

Since:

BlackBerry 10.0.0

QString uniqueId[read-only]

The unique ID of this webpage.

Since:

BlackBerry 10.0.0

QUrl url

The currently loaded URL.

Since:

BlackBerry 10.0.0

Public Functions

WebPage (

Constructs a WebPage.

Parameters
parent

Optional parent for this object.

Since:

BlackBerry 10.0.0

virtual~WebPage ()

Destructor.

bool canGoBack ()

Whether the navigation history contains a previous page.

See also:

goBack()

Since:

BlackBerry 10.0.0

bool canGoForward ()

Whether the navigation history contains a next page.

See also:

goForward()

Since:

BlackBerry 10.0.0

bb::cascades::WebPage * dialogWebPage ()

Return:

The WebPage to use for modal dialogs.

void download (

Downloads a file to the local file system.

The provided @c WebDownloadRequest object indicates what to download, and where. It also emits various signals during the downloading process to indicate how the operation progresses.

Parameters
request

An instance of WebDownloadRequest indicating what to download, and where.

Since:

BlackBerry 10.0.0

int evaluateJavaScript (

Evaluates the specified JavaScript.

Note: A javaScriptResult will be emitted as a result of this asynchronous operation.

Parameters
script

The JavaScript code to run.

world

The JavaScript world in which the code should run. If left unspecified, Normal is the default.

Return:

A token that can be kept to match up the result of this evaluateJavaScript with a subsequent javaScriptResult.

See also:

javaScriptResult

Since:

BlackBerry 10.0.0

void findText (
  • const QString &subString,
  • WebFindFlag::Typesoptions )

Finds a given substring within the current page.

This method will find and highlight, but not select, text in the page that matches the string that is passed in. This feature is typically used to assist users in locating a specific passage of interest within a webpage.

Parameters
subString

The string to locate.

options

A set of WebFindFlag values.

See also:

WebFindFlag.

Since:

BlackBerry 10.0.0

QUrl icon ()

The URL for the favicon for the current page, if any.

Since:

BlackBerry 10.0.0

void loadData (

Loads the specified data from memory.

Note: The view will be updated asynchronously. This method returns immediately.

Parameters
data

The data to load.

mimeType

The MIME type of the data. It can be omitted if unknown.

baseUrl

A base URL to resolve relative paths against. If not required it can be omitted.

Since:

BlackBerry 10.0.0

void loadFile (

Loads a file from the local file system.

Parameters
fileUrl

Must be a file:/// URL, typically constructed using QUrl::fromLocalFile.

mimeType

The mime type of the file contents.

Since:

BlackBerry 10.0.0

bool loading ()

True if the web view is currently loading a webpage, false otherwise.

Since:

BlackBerry 10.0.0

int loadProgress ()

The progress of loading the current webpage.

The range is from 0 to 100.

Since:

BlackBerry 10.0.0

float maxContentScale ()

Suggested maximum content scale factor for pinch zoom.

The value of this property can be specified by web content. In order to apply the suggested value, place the WebView in a ScrollView that has pinch to zoom enabled, and connect the maxContentScaleChanged() signal to setMaxContentScale().

Return:

Suggested maximum scale factor allowed.

See also:

setMaxContentScale() and setPinchToZoomEnabled().

Since:

BlackBerry 10.0.0

float minContentScale ()

Suggested minimum content scale factor for pinch zoom.

The value of this property can be specified by web content. In order to apply the suggested value, place the WebView in a ScrollView that has pinch to zoom enabled, and connect the minContentScaleChanged() signal to setMinContentScale().

Return:

Suggested minimum scale factor allowed.

See also:

setMinContentScale() and setPinchToZoomEnabled().

Since:

BlackBerry 10.0.0

void setResourceRequestFilter (

Specifies a WebResourceRequestFilter for this WebPage.

The WebResourceRequestFilter provides a powerful API for consumers to strictly control the networking requests going in and out of this webpage.

Parameters
filter

A WebResourceRequestFilter implementation. It can be set to null to remove a former filter.

Since:

BlackBerry 10.0.0

bb::cascades::WebSettings * settings ()

The WebSettings object associated with this WebView.

Since:

BlackBerry 10.0.0

void setUrl (

Sets a URL of a page to load.

Parameters
url

The URL to load.

Since:

BlackBerry 10.0.0

bb::cascades::WebStorage * storage ()

The WebStorage object associated with this WebView.

The WebStorage class provides an API for the caching and storage that the WebView generates internally during browsing operations. It can be used to clear those caches and delete all other accumulated information.

Since:

BlackBerry 10.0.0

QString title ()

The title of the currently loaded webpage.

Since:

BlackBerry 10.0.0

QString uniqueId ()

Gets the unique ID of the underlying WebKit webpage instance.

QUrl url ()

The currently loaded URL.

Return:

The currently loaded URL.

Since:

BlackBerry 10.0.0

Public Slots

void goBack ()

Navigates to the previous page in the navigation history.

If there's no previous page, this method does nothing.

Since:

BlackBerry 10.0.0

void goForward ()

Navigates to the next page in the navigation history.

If there's no next page, this method does nothing.

Since:

BlackBerry 10.0.0

void postMessage (

Posts a message to an onmessage function registered with the navigator.cascades object by JavaScript code executing on the page.

Parameters
message

A string that will be sent to the onmessage handler registered, if any.

Since:

BlackBerry 10.0.0

void reload ()

Reloads the current page.

Since:

BlackBerry 10.0.0

void resetDialogWebPage ()

Resets the webpage to use for displaying modal dialog content to 0, effectively disabling the modal dialog feature for this WebPage.

Since:

BlackBerry 10.0.0

void setDialogWebPage (

Sets the webpage to use for displaying modal dialog content.

Since:

BlackBerry 10.0.0

void setSelection (
  • floatx1,
  • floaty1,
  • floatx2,
  • floaty2 )

Sets the selection of the webpage to a range starting at (x1, y1) in webpage content coordinates, extending to (x2, y2).

Parameters
x1

X coordinate of the start point for the range to select, in content coordinates.

y1

Y coordinate of the start point for the range to select, in content coordinates.

x2

X coordinate of the end point for the range to select, in content coordinates.

y2

Y coordinate of the end point for the range to select, in content coordinates.

Since:

BlackBerry 10.0.0

void stop ()

Stops any loading in progress.

If no loading is in progress, this method does nothing.

Since:

BlackBerry 10.0.0

Signals

void contextMenuHideRequested ()

Emitted when interaction with the webpage causes it to want to hide the context menu.

Since:

BlackBerry 10.0.0

void contextMenuShowRequested (

Emitted when interaction with the webpage causes it to want to display a context menu.

Parameters
actionSet

The ActionSet to display in the context menu.

Since:

BlackBerry 10.0.0

void dialogHideRequested ()

Emitted when interaction with the webpage causes it to want to hide a previously requested modal dialog.

Since:

BlackBerry 10.0.0

void dialogShowRequested ()

Emitted when interaction with the webpage causes it to want to display another page in a modal dialog.

The page that should be displayed is the one returned by dialogWebPage().

Since:

BlackBerry 10.0.0

void dialogWebPageChanged (

Emitted when the dialogWebPage property changes.

Since:

BlackBerry 10.0.0

void enterFullScreenRequested ()

Emitted when the webpage wants to enter full screen mode.

The web content may request the webpage to be shown in full screen mode. If appropriate, the embedder can listen to this signal and start rendering the webpage full screen until prompted by the exitFullScreenRequested() signal.

void exitFullScreenRequested ()

Emitted when the webpage wants to exit full screen mode.

void iconChanged (

Emitted when the URL of the favicon of the webpage has changed.

Parameters
icon

The URL for the new icon.

Since:

BlackBerry 10.0.0

void initialized (

Emitted when the page is initialized and ready to go.

Since:

BlackBerry 10.0.0

void javaScriptInterrupted ()

Emitted if JavaScript code executing on the webpage is terminated because it was running for too long.

Since:

BlackBerry 10.0.0

void javaScriptResult (

Emitted as a response to evaluateJavaScript().

Parameters
resultId

A token to match up a response with a call to evaluateJavaScript().

result

The final result of the JavaScript operation as a QVariant. The underlying type naturally depends on the JavaScript evaluated.

Since:

BlackBerry 10.0.0

void loadingChanged (

Emitted when a webpage load request has changed status and the loading property is changed (when loading started, finished, or failed).

Here's a QML example demonstrating the use of a WebLoadRequest:
onLoadingChanged: {
    if (loadRequest.status == WebLoadStatus.Started) {
        statusLabel.setText("Load started.")
    }
    else if (loadRequest.status == WebLoadStatus.Succeeded) {
        statusLabel.setText("Load finished.")
    }
    else if (loadRequest.status == WebLoadStatus.Failed) {
        statusLabel.setText("Load failed.")
    }
}
Parameters
loadRequest

Contains the URL and status of the load request that changed status.

See also:

WebLoadRequest

Since:

BlackBerry 10.0.0

void loadProgressChanged (
  • intloadProgress)

Emitted when the loading progress of the webpage changes.

Parameters
loadProgress

The new progress value.

Since:

BlackBerry 10.0.0

void maxContentScaleChanged (
  • floatmaxContentScale)

Emitted when the web content suggests a new value for the maximum content scale.

Parameters
maxContentScale

The new suggested value for maximum content scale.

Since:

BlackBerry 10.0.0

void messageReceived (

Emitted when JavaScript code executing on the webpage calls navigator.cascades.postMessage().

Parameters
message

Contains at least two key-value pairs, a URL and the message, stored as a QUrl under the "origin" key and QString under the "data" keys, respectively.

Since:

BlackBerry 10.0.0

void microFocusChanged ()

Emitted, for example, when the caret moves within an editable text field.

This could be used as a notification to update context-dependent controls, such as buttons used to create a rich text editor.

Since:

BlackBerry 10.0.0

void minContentScaleChanged (
  • floatminContentScale)

Emitted when the web content suggests a new value for the minimum content scale.

Parameters
minContentScale

The new suggested value for minimum content scale.

Since:

BlackBerry 10.0.0

void navigationHistoryChanged ()

Emitted when navigation history has changed.

The navigation history is considered to have changed when navigating to a different page. Depending on the type of navigation, the availability of the goBack() and goForward() actions may change.

Since:

BlackBerry 10.0.0

void navigationRequested (

Emitted for every navigation request.

The request object contains the URL and type of the navigation action, for example, "a link click on 'http://www.rim.com/". The navigation will be accepted by default. To reject the request, you can change the action property of the WebNavigationRequest or call WebNavigationRequest::ignore() In the case of OpenWindow type, accepting the request loads the URL in the current tab. To open it in a new tab it must be rejected and loaded into another WebView independently. The request object cannot be used after the signal handler function ends.

Here's a QML example:
onNavigationRequested: {
    console.log("NavigationRequested: " + request.url + " navigationType=" + request.navigationType)
    if (shouldAcceptNavigationToUrl(request.url)) {
        request.action = WebNavigationRequestAction.Accept
    } else {
        request.action = WebNavigationRequestAction.Ignore
    }
}
Since:

BlackBerry 10.0.0

void titleChanged (

Emitted when the title of the webpage has changed.

Parameters
title

The new title.

Since:

BlackBerry 10.0.0

void urlChanged (

Emitted when the URL of the webpage has changed (after the change is committed).

This will be emitted after navigationRequested().

Parameters
url

The new URL.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus