Класс 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 *QQmlEngine::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 QQmlEngine::qmlClearTypeRegistrations()

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

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

QQmlContext *QQmlEngine::qmlContext(const QObject *object)

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

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

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

QQmlInfo QQmlEngine::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 *QQmlEngine::qmlEngine(const QObject *object)

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

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

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

QQmlInfo QQmlEngine::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 QQmlEngine::qmlProtectModule(const char *uri, int majVersion)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

int QQmlEngine::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 QQmlEngine::qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

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

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

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

int QQmlEngine::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 QQmlEngine::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 QQmlEngine::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()
    }
}

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

int QQmlEngine::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 QQmlEngine::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 QQmlEngine::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 QQmlEngine::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 QQmlEngine::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 is not a type».

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

int QQmlEngine::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 QQmlEngine::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 QQmlEngine::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().

QQmlInfo QQmlEngine::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.