Класс 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 = ...)

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

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

QQmlEngine *qmlEngine(const QObject *object)

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

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

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

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
}

См. также Выбор правильного метода интеграции между C++ и QML.

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 может ссылаться через имя типа, с которым он был зарегистрирован, и это имя типа может использоваться в качестве цели в типе Подключения или в противном случае использоваться как любой другой идентификатор типа. Одно исключение из этого – свойство 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);
    }

    ...
}

См. также Выбор правильного метода интеграции между C++ и QML.

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.

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

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

// 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. Это можно сделать, добавив в импорты файла QML типа инструкцию pragma Singleton. Кроме того, тип должен быть определен в файле qmldir со словом singleton, а файл qmldir должен импортироваться файлами QML, использующими синглтон.

int qmlRegisterType()

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

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

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

Например, рассмотрим следующие два класса:

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

public:
    Bar() {}

    QString baz() const { return mBaz; }

    void setBaz(const QString &baz)
    {
        if (baz == mBaz)
            return;

        mBaz = baz;
        emit bazChanged();
    }

signals:
    void bazChanged();

private:
    QString mBaz;
};

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

public:
    Foo() {}

    Bar *bar() { return &mBar; }

private:
    Bar mBar;
};

В QML мы присваиваем строку свойству baz типа bar:

Foo {
    bar.baz: "abc"
    Component.onCompleted: print(bar.baz)
}

Для того, чтобы движок QML знал, что тип Bar имеет свойство baz, мы должны сделать тип Bar известным:

qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterType<Bar>();

Поскольку тип Foo экземпляризован в QML, он должен быть зарегистрирован с помощью версии qmlRegisterType(), которая принимает URI импорта.

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

См. также Выбор правильного метода интеграции между C++ и 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, написанному для предыдущих версий, продолжать работать, даже если доступны более продвинутые версии некоторых ее типов.

См. также Выбор правильного метода интеграции между C++ и 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 {
   ^

Без этого было бы выведено общее сообщение "Game не является типом".

См. также qmlRegisterUncreatableType() и Выбор правильного метода интеграции между C++ и QML.

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() и Выбор правильного метода интеграции между C++ и QML.