Класс WebEngine

(SailfishOS::WebEngine)

Предоставляет доступ к контексту веб-движка. Подробнее…

Подключение:

#include <WebEngine>

Список всех членов класса, включая унаследованные

Свойства

initialized : const bool

Публичные функции

void addObservers(const std::vector<std::string> &aObserversList)
bool isInitialized() const
void removeObservers(const std::vector<std::string> &aObserversList)

Публичные слоты

void	addComponentManifest(const QString &manifestPath)
void	addObserver(const QString &aTopic)
void	notifyObservers(const QString &topic, const QString &value)
void	notifyObservers(const QString &topic, const QVariant &value)
void	removeObserver(const QString aTopic)
void	runEmbedding(int aDelay = -1)
void	setProfile(const QString &profilePath)
void	stopEmbedding()

Сигналы

void contextDestroyed()
void initialized()
void lastViewDestroyed()
void lastWindowDestroyed()
void recvObserve(const QString message, const QVariant data)

Статические публичные члены

void	initialize(const QString &profilePath, bool runEmbedding = true)
WebEngine *	instance()

Подробное описание

Предоставляет доступ к контексту веб-движка.

Класс-синглтон, который обеспечивает доступ к контексту веб-движка.

Описание свойств

initialized : const bool

Свойство определяет, был ли контекст инициализирован.

Методы доступа:

bool isInitialized() const

Сигнал уведомления:

void initialized()

См. также WebEngine::initialize.

Описание функций-членов

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

Регистрирует компоненты JavaScript Chrome для загрузки в WebEngine.

WebEngine имеет три основных слоя. Верхний слой представлен в виде QML-компонентов с интерфейсом для разработчиков. Нижний слой — нативный движок рендеринга Gecko.

Между ними находится слой JavaScript, который может взаимодействовать с любым из двух других, используя шаблон наблюдателя/уведомления. Эти компоненты JavaScript считаются привилегированным кодом и запускаются с помощью системного принципала.

Вызов данного метода позволяет добавлять и выполнять новые компоненты JavaScript как часть промежуточного слоя.

manifestPath должен быть абсолютным путём, указывающим на файл манифеста. Файл манифеста должен содержать ссылки на компоненты в том же каталоге, как показано в следующем примере. Пример состоит из трёх файлов: главного файла инициализации, который вызывает addComponentManifest, файла манифеста и компонента, на который есть ссылка в манифесте. Обычно также имеется внешний QML-файл, содержащий компонент WebView, который для краткости опущен.

main — это точка входа в приложение, которая вызывает 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();
 }

Файл манифеста по пути /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

Компонент JavaScript указывается в манифесте и хранится по пути /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]);

В примере просто выводятся различные отладочные сообщения, указывающие на то, что компонент был инициализирован, и когда получено сообщение "exampleTopic". Есть много внутренних компонентов Gecko с общедоступными интерфейсами, к которым нельзя получить доступ напрямую из QML, но к ним можно получить доступ через компонент, установленный таким образом.

Таким образом, здесь представлен общий шаблон для приложения, использующего веб-представление, для установки компонента, выступающего в качестве посредника. Интерфейс QML отправляет сообщение компоненту, который вызывает внутренний интерфейс Gecko, а затем отправляет результат обратно в сообщении, которое принимает внешний интерфейс.

Примечание. В данном контексте термины "привилегированный" и "системный участник" являются терминами gecko. Они не относятся к каким-либо системным привилегиям, внешним по отношению к веб-представлению.

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

Регистрирует WebEngine для получения уведомлений по теме.

Движок Gecko и компоненты EmbedLite используют уведомления для передачи данных и информации о событиях другим компонентам. Метод addObserver позволяет WebEngine зарегистрироваться как интересующемуся конкретной aTopic, чтобы он начал получать уведомления.

Когда WebEngine получает уведомление о зарегистрированной aTopic, он отправляет сигнал recvObserve.

Документация Mozilla nsIObserver предоставляет подробную информацию о базовых процессах.

Существует также неполный список тем для уведомлений наблюдателей, на которые можно подписаться.

См. также addObservers, removeObserver, removeObservers, recvObserve и notifyObservers.

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

Регистрирует WebEngine для получения уведомлений по нескольким темам.

Метод addObservers следует использовать для одновременной регистрации интереса к нескольким темам. aObserversList должен содержать список всех интересующих тем.

Это эквивалентно многократному вызову addObserver.

См. addObserver для более подробной информации об уведомлениях и наблюдателях.

См. также addObserver, removeObserver, removeObservers, recvObserve и notifyObservers.

[signal] void WebEngine::contextDestroyed()

Сигнал испускается после остановки встраивания и готовности контекста к удалению.

Сигнал испускается, когда встраивание было остановлено, непосредственно перед удалением WebEngine и выходом из программы.

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

Инициализирует класс WebEngine.

Инициализирует класс WebEngine. profilePath устанавливает корневой каталог для профиля mozilla gecko. После установки profilePath нельзя изменить. Нужно установить для runEmbedding значение false (по умолчанию — true), чтобы обрабатывать шаги, необходимые перед запуском движка.

Многократные вызовы для инициализации не имеют никакого эффекта.

Метод будет вызываться автоматически во время инициализации QML WebView. Однако при некоторых обстоятельствах может быть полезно выполнить пользовательскую инициализацию. В этом случае initialize можно вызвать вручную, если этот идентификатор был выполнен до инициализации механизма QML.

Одной из причин пользовательской инициализации может быть предоставление дополнительных манифестов компонентов.

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

Примечание. По возможности следует избегать использования манифестов компонентов таким образом в пользу скриптов фреймов. Скрипты фреймов, вероятно, охватывают большинство случаев.

Примечание. По умолчанию при создании экземпляра из QML profilePath устанавливается как QStandardPaths::writableLocation(QStandardPaths::CacheLocation), который по умолчанию ~/.cache/<organisation name>/<application name>. Если используется другое расположение, необходимо выбрать путь, приемлемый с точки зрения песочницы приложения. Стандартные пути приложений безопасны для путей профиля.

См. также setProfile, addComponentManifest и runEmbedding.

[static] WebEngine *WebEngine::instance()

Возвращает экземпляр синглтона WebEngine.

Возвращённый экземпляр может быть не инициализирован.

См. также initialize.

[signal] void WebEngine::lastViewDestroyed()

Сигнал испускается, когда последнее представление было уничтожено.

[signal] void WebEngine::lastWindowDestroyed()

Сигнал испускается, когда последнее зарегистрированное окно было уничтожено.

По умолчанию это используется для задержки выполнения stopEmbedding до закрытия последнего окна.

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

Отправляет широковещательное уведомление, которое могут получить другие компоненты.

Отправляет уведомление, которое будет получено любым компонентом, зарегистрировавшим наблюдателя для topic.

Дополнительные данные можно отправить вместе с уведомлением, используя параметр value, заданный в виде строки JSON.

См. также addObserver и recvObserve.

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

Отправляет широковещательное уведомление, которое могут получить другие компоненты.

Отправляет уведомление, которое будет получено любым компонентом, зарегистрировавшим наблюдателя для topic.

Дополнительные данные могут быть отправлены с уведомлением с помощью параметра value, который должен содержать структуру (например, QVariantMap), которая будет задана как объект JSON.

См. также addObserver и recvObserve.

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

Сигнал испускается, когда получено уведомление по наблюдаемой теме.

После того, как приложение зарегистрировало интерес к определённой теме, вызвав addObserver или addObservers, оно может затем подключиться к этому сигналу, чтобы получать уведомления о любом компоненте, отправляющем уведомление по теме.

Параметр message будет рассматриваемой темой, параметр data будет содержать данные от отправителя, созданные из объекта JSON. Точная структура объекта остаётся на усмотрение отправителя.

См. также addObserver, addObservers, removeObserver, removeObservers и notifyObservers.

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

Отменяет регистрацию WebEngine для получения уведомлений по теме.

Если компонент, который ранее зарегистрировал интерес к получению уведомлений о aTopic, вызвав addObserver, больше не заинтересован в их получении, он может вызвать removeObserver для отмены.

Вызов removeObserver не гарантирует, что больше не будут получены уведомления по этой теме, поскольку другие компоненты могли зарегистрировать интерес с помощью WebEngine. WebEngine перестанет посылать сигналы по теме только после отмены всех подписок.

Только для тем, которые ранее были зарегистрированы с помощью addObserver или addObservers, регистрация должна отменяться с помощью removeObserver.

См. addObserver для более подробной информации об уведомлениях и наблюдателях.

См. также removeObservers, addObserver, addObservers, recvObserve и notifyObservers.

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

Отменяет регистрацию WebEngine для получения уведомлений по нескольким темам.

Метод removeObservers следует использовать для одновременной отмены регистрации интереса к нескольким темам. aObserversList должен содержать список всех тем, которые больше не представляют интереса.

Только темы, ранее зарегистрированные с помощью addObserver или addObservers, должны быть включены в aObserversList.

Это эквивалентно многократному вызову removeObserver.

См. addObserver для более подробной информации об уведомлениях и наблюдателях.

См. также addObservers, removeObserver, removeObservers, recvObserve и notifyObservers.

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

Запускает цикл событий движка.

Когда WebEngine создаётся как компонент QML, он вызывается автоматически во время инициализации. Однако его можно вызвать раньше, чтобы запустить цикл обработки событий WebEngine в случае переопределения процесса инициализации.

См. WebEngine::initialize для получения дополнительной информации.

aDelay допускает асинхронный запуск. Вызов без параметра aDelay (поэтому по умолчанию он равен -1) вызовет выполнение во вложенном основном цикле, который будет заблокирован до тех пор, пока stopEmbedding вызывается.

См. также WebEngine::initialize, stopEmbedding и setProfile.

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

Устанавливает местоположение для каталога профиля.

Метод вызывается во время процесса запуска, чтобы установить profilePath в качестве места для хранения профиля (внутри которого будет создан каталог .mozilla). По умолчанию установлено значение QStandardPaths::writableLocation(QStandardPaths::CacheLocation), которое обычно ~/.cache/<organisation name>/<application name>.

Как правило, нет необходимости вызывать setProfile, так как профиль будет автоматически настроен при инициализации, а также может быть передан в качестве параметра в WebEngine::initialize.

Когда WebEngine создаётся как компонент QML, он также вызывается автоматически во время инициализации. Однако его можно вызвать раньше, чтобы задать расположение пользовательского профиля в случае переопределения процесса инициализации.

Примечание: Если используется другое расположение, необходимо выбрать путь, приемлемый с точки зрения песочницы приложения. Стандартные пути приложений безопасны для путей профиля.

См. WebEngine::initialize для получения дополнительной информации.

См. также WebEngine::initialize, runEmbedding и stopEmbedding.

[slot] void WebEngine::stopEmbedding()

Осчтанавливает цикл событий движка.

Вызывает остановку выполнения WebEngine. Если runEmbedding был вызван без параметра aDelay, это вызовет разблокировку вызова runEmbedding.

См. также WebEngine::initialize, runEmbedding и setProfile.