Sailfish Webview
API DocumentationWebEngine QML Type
Provides access to the web engine context. More...
Import Statement: | import Sailfish.WebEngine 1.0 |
Properties
- initialized : bool
Signals
- contextDestroyed()
- recvObserve(message, data)
Methods
- addComponentManifest(manifestPath)
- addObserver(aTopic)
- notifyObservers(topic, value)
- removeObserver(aTopic)
Detailed Description
The WebEngine
component is a singleton which provides access to the web engine context.
The WebEngine
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: { WebEngine.addObserver("clipboard:setdata") WebEngine.onRecvObserve.connect(function(message, data) { if (message == "clipboard:setdata" && !data.private) { console.log("Clipboard contents: " + data.data); } }) } } } }
See also WebView.
Property Documentation
Signal Documentation
This signal is emitted after the embedding has been stopped and the context is ready to be deleted.
This signal is emitted when the embedding has been stopped, just prior to the WebEngine being deleted and the program exiting.
This signal is emitted when a notification on an observed topic is received.
After an app has registered an interested in a particular topic by calling addObserver, it can then connect to this signal to be notified about any component sending a notification on the topic.
The message parameter will be the topic in question, the data parameter will contain data sent by the sender in JSON format. The exact JSON structure is at the sender's discretion.
See also addObserver and notifyObservers.
Method Documentation
Register JavaScript chrome components to be loaded into the WebEngine.
The sailfish WebEngine has three main layers. The top layer is exposed as QML components with a developer-facing interface. The lowest level is the native Gecko rendering engine.
Between the two sits a JavaScript chrome layer that can communicate with either of the other layers using an observer/notification pattern. These JavaScript components are considered privileged code and run with the system principal.
This call allows new JavaScript components to be added and executed as part of this intermediary layer.
The manifestPath should be an absolute path pointing to a manifest file. The manifest file should contain references to components in the same folder, as shown in the following example. The example is comprised of three files: a QML user interface file that calls addComponentManifest
, the manifest file and a component referenced in the manifest.
The WebEngine page.qml file calls addComponentManifest
.
import QtQuick 2.1 import Sailfish.Silica 1.0 import Sailfish.Browser 1.0 import Sailfish.WebEngine 1.0 ApplicationWindow { id: root initialPage: Component { WebViewPage { WebView { anchors.fill: parent url: "http://www.sailfishos.org" onLinkClicked: { WebEngine.notifyObservers("exampleTopic", url) } } Component.onCompleted: { WebEngine.addComponentManifest("/path/file.manifest") } } } }
The manifest file at /path/file.manifest
component {20227a22-1722-4753-b8f6-c842b401b4c3} ExampleComponent.js contract @mozilla.org/embedlite-example-component;1 {20227a22-1722-4753-b8f6-c842b401b4c3} category app-startup ExampleComponent service,@mozilla.org/embedlite-example-component;1
The JavaScript chrome component referenced in the manifest and stored at /path/ExampleComponent.js
const Ci = Components.interfaces; const Cu = Components.utils; Cu.import("resource://gre/modules/XPCOMUtils.jsm"); Cu.import("resource://gre/modules/Services.jsm"); XPCOMUtils.defineLazyServiceGetter(Services, "embedlite", "@mozilla.org/embedlite-app-service;1", "nsIEmbedAppService"); Services.scriptloader.loadSubScript("chrome://embedlite/content/Logger.js"); function ExampleComponent() { Logger.debug("JSComp: ExampleComponent.js loaded"); } ExampleComponent.prototype = { classID: Components.ID("{20227a22-1722-4753-b8f6-c842b401b4c3}"), QueryInterface: XPCOMUtils.generateQI([Ci.nsIObserver]), observe: function(aSubject, aTopic, aData) { switch (aTopic) { case "app-startup": Services.obs.addObserver(this, "exampleTopic", false); break; case "exampleTopic": Logger.debug("ExampleComponent: exapleTopic data: " + aData); break; } }, }; this.NSGetFactory = XPCOMUtils.generateNSGetFactory([ExampleComponent]);
Registers the WebEngine for receiving notifications on a topic
The Gecko engine and EmbedLite components use notifications to transfer data and information about events to other components. The addObserver
method allows the WebEngine to be registered as interested in the particular aTopic so that it will start receiving notifications about them.
When WebEngine receives a notification on a registered aTopic it will emit a recvObserve
signal.
The Mozilla nsIObserver documentation provides details about the underlying processes.
There is also a non-exhaustive list of observer notification topics that can be subscribed to.
See also removeObserver, recvObserve, and notifyObservers.
Sends a broadcast notification that can be observed by other components.
Sends a notification that will be picked up by any component that has registered an observer for topic.
Additional data can be sent with the notification using the value parameter in JSON format.
See also addObserver and recvObserve.
Unregisters the WebEngine from receiving notifications on a topic.
If a component which previously registered an interest in receiving notifications on aTopic by calling addObserver is no longer interested in receiving them, it can call removeObserver
to indicate this.
Calling removeObserver
does not guarantee that no more notifications on the topic will be received, since other components may have registered an interest with the WebEngine
. The WebEngine
will stop emitting signals on the topic only once all interests have been deregistered.
See also addObserver, recvObserve, and notifyObservers.