Member Function Documentation

[slot] void WebEngine::addComponentManifest(const QString &manifestPath)

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 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: the main app initialisation code that calls addComponentManifest, the manifest file and a component referenced in the manifest. The would usually also be a frontend QML file containing a WebView component which is omitted for brevity.

The app main entry point which calls addComponentManifest.

 #include <QtQuick>
 #include <sailfishapp.h>
 #include <libsailfishwebengine/webengine.h>

 int main2(int argc, char *argv[])
 {
     QGuiApplication *app = SailfishApp::application(argc, argv);
     QQuickView *view = SailfishApp::createView();
     view->setSource(SailfishApp::pathTo("application.qml"));

     SailfishOS::WebEngine *webEngine = SailfishOS::WebEngine::instance();
     webEngine->addComponentManifest(QLatin1String("/path/file.manifest"));

     view->show();

     return app->exec();
 }

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 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]);

The example simply prints various debug messages to indicate the component has been initialized and when an "exampleTopic" message is received. There are many internal Gecko components with public interfaces that can't be accessed directly from QML, but can be accessed by a component installed in this way.

A common pattern is therefore for an app using a web view to install a component to act as an intermediary. The QML interface sends a message to the component, which calls the internal Gecko interface, and then sends back the result in a message that's picked up by the front end.

Note: In this context "privileged" and "system principal" are gecko terminology. They don't relate to any system privileges external to the web view.

[slot] void WebEngine::addObserver(const QString &aTopic)

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 addObservers, removeObserver, removeObservers, recvObserve, and notifyObservers.

void WebEngine::addObservers(const std::vector<std::string> &aObserversList)

Registers the WebEngine for receiving notifications on multiple topics.

The addObservers method should be used to register interest in multiple topics simultaneously. The aObserversList should be set to contain a list of all the topics of interest.

This is equivalent to calling addObserver multiple times.

See addObserver for more detailed info about notifications and observers.

See also addObserver, removeObserver, removeObservers, recvObserve, and notifyObservers.

[signal] void WebEngine::contextDestroyed()

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.

[static] void WebEngine::initialize(const QString &profilePath, bool runEmbedding = true)

Initialises the WebEngine class.

Initalizes the WebEngine class. The profilePath sets the root folder for the mozilla gecko profile. Once set the profilePath can't be changed. Set runEmbedding to false (defaults to true) in order to handle steps that are needed before engine startup.

Multiple calls to initialize have no effect.

This method will be called automatically during QML initialisation of the WebView. However under some circumstances it may be useful to perform a custom initalization. In this case initialize can be called manually as long as this id done before the QML engine initialization.

One reason for custom initialization would be to proivde additional component manifests.

 SailfishOS::WebEngine *webEngine = SailfishOS::WebEngine::instance();
 QString profilePath = QStandardPaths::writableLocation(QStandardPaths::CacheLocation);
 webEngine->initialize(profilePath, false);
 webEngine->addComponentManifest(QLatin1String("/path/file.manifest"));

 [...]

 QTimer::singleShot(0, webEngine, SLOT(runEmbedding()));

Note: Using component manifests in this way should be avoided in favour of frame scripts where possible. Frame scritps are likely to cover the majority of cases.

Note: By default When instantiated from QML profilePath is set to QStandardPaths::writableLocation(QStandardPaths::CacheLocation), which is by default ~/.cache/<organisation name>/<application name>. If using a different location care is needed to select a path that's acceptable from an application sandboxing point of view. The standard application paths are safe for profile paths.

See also setProfile, addComponentManifest, and runEmbedding.

[static] WebEngine *WebEngine::instance()

Returns the instance of the singleton WebEngine class.

The returned instance may not be initialized.

See also initialize.

[signal] void WebEngine::lastViewDestroyed()

This signal is emitted when when the last view has been destroyed.

[signal] void WebEngine::lastWindowDestroyed()

This signal is emitted when the last registered window has been destroyed.

By default this is used to delay execution of stopEmbedding until after the last window has closed.

[slot] void WebEngine::notifyObservers(const QString &topic, const QString &value)

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 encoded as a JSON string.

See also addObserver and recvObserve.

[slot] void WebEngine::notifyObservers(const QString &topic, const QVariant &value)

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 which should contain a structure (e.g. a QVariantMap) that will be encoded as a JSON object.

See also addObserver and recvObserve.

[signal] void WebEngine::recvObserve(const QString message, const QVariant data)

This signal is emitted when a notification on an observed topic is received.

After an app has registered an interest in a particular topic by calling addObserver or addObservers, 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 constructed from a JSON object. The exact object structure is at the sender's discretion.

See also addObserver, addObservers, removeObserver, removeObservers, and notifyObservers.

[slot] void WebEngine::removeObserver(const QString aTopic)

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.

Only topics that have previously been registered using addObserver or addObservers should be unregistered using removeObserver.

See addObserver for more detailed info about notifications and observers.

See also removeObservers, addObserver, addObservers, recvObserve, and notifyObservers.

void WebEngine::removeObservers(const std::vector<std::string> &aObserversList)

Unregisters the WebEngine from receiving notifications on multiple topics.

The removeObservers method should be used to unregister interest in multiple topics simultaneously. The aObserversList should be set to contain a list of all the topics that are no longer of interest.

Only topics that have previously been registered using addObserver or addObservers should be included in the aObserversList.

This is equivalent to calling removeObserver multiple times.

See addObserver for more detailed info about notifications and observers.

See also addObservers, removeObserver, removeObservers, recvObserve, and notifyObservers.

[slot] void WebEngine::runEmbedding(int aDelay = -1)

Starts the engine event loop.

When WebEngine is instantiated as a QML component this is called automatically during initialization. However, it can be called earlier to set the WebEngine event loop running in case the initialization process is being overridden.

See WebEngine::initialize for more info.

The aDelay allows for an asynchronous startup. Calling without the aDelay parameter (so it defaults to -1) will cause execution to happen on the nested main loop, which will block until stopEmbedding is called.

See also WebEngine::initialize, stopEmbedding, and setProfile.

[slot] void WebEngine::setProfile(const QString &profilePath)

Sets the location for the profile directory.

This is called during the startup process to set profilePath as the location to store the profile (inside which the .mozilla directory will be created). By default this is set to QStandardPaths::writableLocation(QStandardPaths::CacheLocation), which is usually ~/.cache/<organisation name>/<application name>.

Generally there is no need to call setProfile as the profile will automatically set up on initialization, and can also be passed as parameter to WebEngine::initialize.

When WebEngine is instantiated as a QML component this is also called automatically during initialization. However, it can be called earlier to set a custom profile location in case the initialization process is being overridden.

Note: If using a different location care is needed to select a path that's acceptable from an application sandboxing point of view. The standard application paths are safe for profile paths.

See WebEngine::initialize for more info.

See also WebEngine::initialize, runEmbedding, and stopEmbedding.

[slot] void WebEngine::stopEmbedding()

Stops the engine event loop.

Causes execution of the WebEngine to halt. If runEmbedding was called without the aDelay parameter, this will cause the runEmbedding call to unblock.

See also WebEngine::initialize, runEmbedding, and setProfile.