Класс 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, чтобы очистить все данные кэша, относящиеся к этому движку.

QQmlContext *qmlContext(const QObject *object)

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

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

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

QQmlInfo QtQml::qmlDebug(const QObject *object)

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

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

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

Например,

qmlDebug(object) << "Internal state: 42";

выводит

QML MyCustomType (unknown location): Internal state: 42

Эта функция была добавлена в Qt 5.9.

См. также QtQml::qmlInfo и QtQml::qmlWarning.

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

Примечание: В версиях до Qt 5.9 qmlInfo сообщала сообщения, используя тип предупреждения QtMsgType. Для Qt 5.9 и выше qmlInfo использует информационный QtMsgType. Для отправки предупреждений используйте qmlWarning.

См. также QtQml::qmlDebug и QtQml::qmlWarning.

bool qmlProtectModule(const char *uri, int majVersion)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

int qmlRegisterInterface(const char *typeName)

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

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

void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

Эта функция регистрирует модуль в определённом uri с указанной версией в versionMajor и versionMinor.

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

Эта функция была добавлена в Qt 5.9.

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.
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);

В качестве альтернативы можно использовать лямбда-выражение C++11:

qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
    Q_UNUSED(engine)

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

Для использования зарегистрированного одиночного типа в 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.
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);

В качестве альтернативы вы можете использовать лямбда-функцию C++11:

qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

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

Для использования зарегистрированного типа-синглтона в 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.
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, использующими синглтон.

int qmlRegisterType()

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

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

Возвращает идентификатор типа 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»:

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++, например, когда отображение типов нужно определить процедурно при запуске.

Возвращает -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 {
   ^

Без этого было бы выдано общее сообщение об ошибке «Игра не является типом».

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

int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

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

Экземпляр метаобъекта не может быть создан. Если пользователь попытается создать его, будет выведено сообщение об ошибке с заданным reason.

Эта функция полезна для регистрации пространств имён Q_NAMESPACE.

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

Например:

namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUMS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

Теперь в QML можно использовать зарегистрированные перечисления:

Component.onCompleted: console.log(MyNamespace.Key2)

Эта функция была введена в Qt 5.8.

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

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

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

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

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

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

QQmlInfo QtQml::qmlWarning(const QObject *object)

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

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

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

Например,

qmlInfo(object) << tr("property cannot be set to 0");

выводит

QML MyCustomType (unknown location): property cannot be set to 0

Эта функция была добавлена в Qt 5.9.

См. также QtQml::qmlDebug и QtQml::qmlInfo.