Класс QQmlEngine

QQmlEngine engine;
QQmlComponent component(&engine);
component.setData("import QtQuick 2.0\nText { text: \"Hello world!\" }", QUrl());
QQuickItem *item = qobject_cast<QQuickItem *>(component.create());

//add item to view, etc
...

Связанные нечлены

QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

Форма этой шаблонной функции:

template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

Эта функция возвращает экземпляр прикреплённого объекта, который был прикреплён к указанному attachee типом T.

Если create равно true и тип T является допустимым типом прикрепления, эта функция создаёт и возвращает новый экземпляр прикреплённого объекта.

Возвращает 0, если тип T не является допустимым типом прикрепления или если create равно false, и ранее не был создан экземпляр прикреплённого объекта для attachee.

См. также Предоставление прикреплённых объектов для аннотаций данных.

void qmlClearTypeRegistrations()

Очищает все сохранённые регистрации типов, такие как те, что создаются с помощью qmlRegisterType().

Не вызывайте эту функцию, пока существует QQmlEngine, так как поведение будет неопределённым. Все существующие QQmlEngines должны быть удалены перед вызовом этой функции. Эта функция затрагивает только глобальный кэш приложения. Удалите QQmlEngine, чтобы очистить все кешированные данные, относящиеся к этому движку.

#include <QtQml>, чтобы использовать этот метод.

QQmlContext *qmlContext(const QObject *object)

Возвращает QQmlContext, связанный с object, если таковой имеется. Это эквивалентно QQmlEngine::contextForObject(object).

Примечание: Добавьте #include <QtQml> для использования этой функции.

См. также contextForObject() и qmlEngine().

QQmlEngine *qmlEngine(const QObject *object)

Возвращает QQmlEngine, связанный с object, если таковой имеется. Это эквивалентно QQmlEngine::contextForObject(object)->engine(), но более эффективно.

Примечание: Добавьте #include <QtQml> для использования этой функции.

См. также contextForObject() и qmlContext().

QQmlInfo QtQml::qmlInfo(const QObject *object)

Выводит сообщения об ошибках, которые включают имя файла и номер строки для указанного QML-объекта object.

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

Для включения имени файла и номера строки необходимо передать объект. Если имя файла и номер строки недоступны для этого экземпляра (он не был создан QML-движком или информация о местоположении отключена), вместо этого будет использоваться "неизвестное местоположение".

Например,

qmlInfo(object) << tr("component property is a write-once property");

выводит

QML MyCustomType (unknown location): component property is a write-once property

bool qmlProtectModule(const char *uri, int majVersion)

Эта функция защищает модуль от регистрации типов в нём. Это может использоваться для предотвращения вставки типов другими плагинами в ваш модуль. Это также может улучшить производительность, так как позволяет движку пропустить проверку на возможность новых типов или плагинов при достижении этого импорта.

Преимущество в производительности в основном проявляется при регистрации прикладных типов из приложения, а не через плагин. Использование qmlProtectModule позволяет движку пропустить проверку плагина при импорте этого uri, что может быть заметно при медленных файловых системах.

После вызова этой функции любая попытка зарегистрировать C++ типы в эту комбинацию uri и версии приведёт к ошибке во время выполнения. Вызовите эту функцию после регистрации всех ваших типов в движке.

#include <QtQml>, чтобы использовать эту функцию.

Возвращает true, если был найден и заблокирован модуль с uri в качестве идентификатора модуля и majVersion как номер основной версии; в противном случае возвращает false. Модуль должен содержать экспортированные типы, чтобы быть найденным.

int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Эта шаблонная функция регистрирует C++ тип и его расширяющий объект в QML-системе с именем qmlName в библиотеке, импортируемой из uri, имеющей номер версии, составленный из versionMajor и versionMinor. Свойства, недоступные в основном типе, будут искаться в расширяющем объекте.

Возвращает идентификатор QML-типа.

#include <QtQml> для использования этой функции.

См. также qmlRegisterType() и Регистрация расширяющих объектов.

int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

Эта шаблонная функция регистрирует C++ тип и его расширение в системе QML с именем qmlName в библиотеке, импортируемой из uri, имеющей номер версии, составленный из versionMajor и versionMinor.

Хотя тип имеет имя и тип, он не может быть создан, и указанная ошибка reason возникнет при попытке создания.

Это полезно, когда тип предназначен только для предоставления прикрепленных свойств, значений перечислений или абстрактного базового класса со своим расширением.

Возвращает идентификатор QML-типа.

#include <QtQml> для использования этой функции.

См. также qmlRegisterUncreatableType().

int qmlRegisterInterface(const char *typeName)

Эта шаблонная функция регистрирует C++ тип в системе QML под именем typeName.

#include <QtQml> для использования этой функции.

Возвращает идентификатор QML-типа.

int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

Эта шаблонная функция регистрирует указанную версию C++ типа в системе QML с библиотекой, импортируемой из uri, имеющей номер версии, составленный из versionMajor и versionMinor.

Возвращает идентификатор QML-типа.

template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

Эта функция обычно используется для регистрации ревизии базового класса для использования со специфицированной версией типа (см. Ревизии и версии типов).

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue(* ) ( QQmlEngine *, QJSEngine * ) callback)

Эта функция может быть использована для регистрации поставщика одиночного типа callback в конкретном uri и typeName с версией, указанной в versionMajor и versionMinor.

Установка одиночного типа позволяет разработчикам предоставлять произвольные функции (методы и свойства) клиенту без необходимости создания отдельных экземпляров типа клиентом.

Одиночный тип может быть либо QObject, либо QJSValue. Эта функция должна использоваться для регистрации функции поставщика одиночного типа, которая возвращает QJSValue как одиночный тип.

ПРИМЕЧАНИЕ: Свойства одиночного типа QJSValue не будут вызывать повторную оценку привязки при изменении.

Использование:

// First, define the singleton type provider function (callback).
static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
}

// Second, register the singleton type provider with QML by calling this function in an initialization function.
#include <QtQml>
...
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
...

Для использования зарегистрированного одиночного типа в QML необходимо импортировать этот тип.

import QtQuick 2.0
import Qt.example.qjsvalueApi 1.0 as ExampleApi
Item {
    id: root
    property int someValue: ExampleApi.MyApi.someProperty
}

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(* ) ( QQmlEngine *, QJSEngine * ) callback)

Эта функция может быть использована для регистрации поставщика одиночного типа callback в конкретном uri и typeName с версией, указанной в versionMajor и versionMinor.

Установка одиночного типа в uri позволяет разработчикам предоставлять произвольные функции (методы и свойства) клиентам без необходимости создания отдельных экземпляров типа клиентом.

Одиночный тип может быть либо QObject, либо QJSValue. Эта функция должна использоваться для регистрации функции поставщика одиночного типа, которая возвращает QObject указанного типа T в качестве одиночного типа.

Одиночный тип QObject может быть указан по имени типа, с которым он был зарегистрирован, и это имя типа может быть использовано в качестве целевого объекта в типе Connections или иначе использоваться как любой другой идентификатор типа. Единственное исключение состоит в том, что свойство одиночного типа QObject не может быть алиасом (потому что имя одиночного типа не идентифицирует объект внутри того же компонента, что и любой другой элемент).

ПРИМЕЧАНИЕ: Экземпляр одиночного типа QObject, возвращённый поставщиком одиночного типа, принадлежит движку QML, если только для объекта явно не установлен флаг QQmlEngine::CppOwnership.

Использование:

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    SingletonTypeExample(QObject* parent = 0)
        : QObject(parent), m_someProperty(0)
    {
    }

    ~SingletonTypeExample() {}

    Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty;
};

// Second, define the singleton type provider function (callback).
static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
}

// Third, register the singleton type provider with QML by calling this function in an initialization function.
#include <QtQml>
...
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
...

Для использования зарегистрированного одиночного типа в QML необходимо импортировать одиночный тип.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        someValue = MyApi.doSomething()
    }
}

Поскольку одиночные типы не имеют связанного объекта QQmlContext, то в функциях типа, производного от QObject, зарегистрированного в качестве реализации одиночного типа, информация о контексте и движке QML недоступна. Функция QQmlEngine::contextForObject() возвращает NULL при передаче указателя на объект QObject, реализующий одиночный тип.

Расширение приведенного выше примера:

class SingletonTypeExample : public QObject
{
    ...

    Q_INVOKABLE void doSomethingElse()
    {
        // QML Engine/Context information is not accessible here:
        Q_ASSERT(QQmlEngine::contextForObject(this) == 0);
        Q_ASSERT(qmlContext(this) == 0);
        Q_ASSERT(qmlEngine(this) == 0);
    }

    ...
}

int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Эта функция может быть использована для регистрации одиночного типа с именем qmlName в библиотеке, импортированной из uri, имеющей номер версии, составленный из versionMajor и versionMinor. Тип определяется файлом QML, расположенным по адресу url. URL должен быть абсолютным, т.е. url.isRelative() == false.

Кроме того, файл QML типа должен иметь в своих операциях импорта оператор pragma Singleton.

Одиночный тип может быть указан по имени типа, с которым он был зарегистрирован, и это имя типа может быть использовано в качестве целевого объекта в типе Connections или иначе использоваться как любой другой идентификатор типа. Единственное исключение состоит в том, что свойство одиночного типа не может быть алиасом (потому что имя одиночного типа не идентифицирует объект внутри того же компонента, что и любой другой элемент).

Использование:

// First, define your QML singleton type which provides the functionality.
pragma Singleton
import QtQuick 2.0
Item {
    property int testProp1: 125
}

// Second, register the QML singleton type by calling this function in an initialization function.
#include <QtQml>
...
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");
...

Для использования зарегистрированного одиночного типа в QML необходимо импортировать одиночный тип.

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: RegisteredSingleton.testProp1
}

Также возможно регистрация одиночных типов QML без использования функции qmlRegisterSingletonType. Это можно сделать, добавив оператор pragma Singleton в операциях импорта файла QML типа. Кроме того, тип должен быть определён в файле qmldir со словом singleton, а qmldir должен быть импортирован файлами QML, использующими singleton.

int qmlRegisterType()

Это перегруженная функция.

Эта шаблонная функция регистрирует тип C++ в системе QML. Экземпляры этого типа не могут быть созданы из системы QML.

#include <QtQml> для использования этой функции.

Возвращает идентификатор типа QML.

int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Эта шаблонная функция регистрирует тип C++ в системе QML с именем qmlName в библиотеке, импортированной из uri, имеющей номер версии, составленный из versionMajor и versionMinor.

Возвращает идентификатор типа QML.

Существуют два варианта этой шаблонной функции:

template<typename T>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

Первый — это стандартная форма, которая регистрирует тип T как новый тип. Второй позволяет зарегистрировать конкресную версию класса в указанной версии (см. Ревизии и версии типов).

Например, это регистрирует класс C++ MySliderItem как тип QML с именем Slider для версии 1.0 пространства имён типа "com.mycompany.qmlcomponents":

#include <QtQml>

...

qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

После регистрации тип можно использовать в QML, импортировав указанное пространство имён типа и номер версии:

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

Обратите внимание, что вполне разумно, чтобы библиотека регистрировала типы в более ранних версиях, чем фактическая версия библиотеки. Действительно, обычно новая библиотека позволяет работать QML, написанному для предыдущих версий, даже если доступны более продвинутые версии некоторых её типов.

int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Эта функция регистрирует тип в системе QML с именем qmlName в библиотеке, импортированной из uri, имеющей номер версии, составленный из versionMajor и versionMinor. Тип определяется файлом QML, расположенным по адресу url. URL должен быть абсолютным, т.е. url.isRelative() == false.

Обычно файлы QML могут загружаться как типы непосредственно из других файлов QML или с использованием файла qmldir. Эта функция позволяет регистрировать файлы типов из кода C++, например, когда отображение типов необходимо определять процедурно при запуске.

#include <QtQml> для использования этой функции.

Возвращает -1, если регистрация не удалась.

int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

Эта функция регистрирует тип в системе QML с именем qmlName в пространстве имён типа, импортированном из uri, имеющем номер версии, составленный из versionMajor и versionMinor, но любая попытка создать тип выведет заданную ошибку message.

Обычно типы, экспортируемые плагином, должны быть неизменными. Однако, если тип C++ недоступен, вы должны по крайней мере «зарезервировать» имя QML типа и дать пользователю недоступного типа понятное сообщение об ошибке.

Возвращает идентификатор типа QML.

Пример:

#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif

Это заставит любой QML, который импортирует пространство имён типа "MinehuntCore" и пытается использовать тип, вывести сообщение об ошибке:

fun.qml: Get back to work, slacker!
   Game {
   ^

Без этого будет выведено общее сообщение «Игра — не тип».

#include <QtQml> для использования этой функции.

См. также qmlRegisterUncreatableType().

int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

Эта шаблонная функция регистрирует тип C++ в системе QML с именем qmlName в библиотеке, импортированной из uri, имеющей номер версии, составленный из versionMajor и versionMinor.

Хотя у типа есть имя и тип, он не может быть создан, и заданное сообщение об ошибке message будет получено, если попытка создания будет предпринята.

Это полезно в ситуациях, когда тип предназначен только для предоставления присоединённых свойств или значений перечислений.

Возвращает идентификатор типа QML.

#include <QtQml> для использования этой функции.

См. также qmlRegisterTypeNotAvailable().