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

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

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.

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

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

Эта функция должна использоваться, когда тип не будет ссылаться по имени. В частности, она должна использоваться для типов 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.

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

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.