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

class MySingleton : public QObject {
  Q_OBJECT
  static int typeId;
  // ...
};

// Register with QObject* callback
MySingleton::typeId = qmlRegisterSingletonType<MySingleton>(...);

// Retrieve as QObject*
QQmlEngine engine;
MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

// Register with QJSValue callback
int typeId = qmlRegisterSingletonType(...);

// Retrieve as QJSValue
QQmlEngine engine;
QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

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

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

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, major версии приведёт к ошибке во время выполнения. Вызовите эту функцию после регистрации всех ваших типов в движке.

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

int qmlRegisterAnonymousType(const char *uri, int versionMajor)

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

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

Для указания модуля, к которому принадлежит тип, используйте uri и versionMajor.

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

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");
qmlRegisterAnonymousType<Bar>("App", 1);

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

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

Эта функция была представлена в Qt 5.14.

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

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.

Типы, зарегистрированные как интерфейсы в движке, также должны объявлять себя как интерфейсы с помощью системы метаобъектов. Например:

struct FooInterface
{
public:
    virtual ~FooInterface();
    virtual void doSomething() = 0;
};

Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

При регистрации в движке QML таким образом, они могут использоваться в качестве типов свойств:

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

Когда вы присваиваете подкласс QObject этому свойству, движок QML выполняет приведение интерфейса к типу FooInterface* автоматически.

Возвращает идентификатор типа 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 может быть вызван по имени типа, с которым он был зарегистрирован, и это имя типа может использоваться в качестве цели в типе 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.qobjectSingleton", 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()
    }
}

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

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

Возвращает идентификатор QML типа типа, зарегистрированного с именем qmlName в определённом uri и версии, указанной в versionMajor и versionMinor.

Эта функция возвращает то же значение, что и функции регистрации типов QML, такие как qmlRegisterType() и qmlRegisterSingletonType().

Если qmlName, uri и versionMajor соответствуют зарегистрированному типу, но указанная в versionMinor младшая версия больше, то возвращается идентификатор типа с ближайшей младшей версией.

Возвращает -1, если соответствующий тип не найден или один из переданных параметров некорректен.

Функция была добавлена в Qt 5.12.

См. также qmlRegisterType() и qmlRegisterSingletonType().