QQmlEngine类

相关非成员

enum QQmlModuleImportSpecialVersions

定义了一些可以传递给qmlRegisterModuleImport()和qmlUnregisterModuleImport()版本参数的特殊值。

template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

此模板函数的形式为

template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

这返回被附加类型T附加到指定attachee的附加对象实例。

如果create为true且类型T是一个有效的附加类型，则创建并返回一个新的附加对象实例。

如果类型T不是一个有效的附加类型，或者如果create为false且attachee之前没有创建任何附加对象实例，则返回nullptr。

另请参阅QML_ATTACHED()和提供附加属性。

void qmlClearTypeRegistrations()

清除所有存储的类型注册，例如，使用qmlRegisterType()产生的注册信息。

在存在 QQmlEngine 或aiduò时，请不要调用此函数，否则行为将未定义。必须在调用此函数之前删除现有的 QQmlEngines。此函数仅影响应用程序全局缓存。删除 QQmlEngine 以清除与该引擎相关的所有缓存数据。

QQmlContext *qmlContext(const QObject *object)

返回关联到 object 的 QQmlContext（如果存在）。这等效于 QQmlEngine::contextForObject(object)。

另请参阅：contextForObject() 和 qmlEngine。

QQmlEngine *qmlEngine(const QObject *object)

返回关联到 object 的 QQmlEngine（如果存在）。这等效于 QQmlEngine::contextForObject(object)->engine()，但更高效。

另请参阅：contextForObject() 和 qmlContext。

bool qmlProtectModule(const char *uri, int majVersion)

该函数可保护模块免受进一步修改。这可以用于防止其他插件将类型注入到您的模块中。同时，这也可以提升性能，因为当达到此处导入时，它允许引擎跳过检查是否存在新类型或插件的可能性。

一旦调用 qmlProtectModule，QML 引擎将不再搜索新的 qmldir 文件来加载模块，但它将重用之前加载的任何 qmldir 文件。因此，这一点产生的类型仍然可以继续工作。请注意，不同的 QML 引擎可能加载不同的模块。然而模块保护是全局的，并影响所有引擎。在慢速文件系统中，定位文件和加载插件的开销可能会变得明显。因此，一旦确定不再需要加载模块，保护模块可以是一个非常好的优化。同时请注意，模块锁不仅影响插件，还影响任何其他 qmldir 指令（如 import 或 prefer），以及在文件中声明的任何复合类型或脚本。

此外，在调用此函数之后，任何尝试将 C++ 类型注册到此 URI 和主版本组合的尝试都可能导致运行时错误。

如果找到以 uri 作为 模块标识符 和 majVersion 作为主版本号的模块并将其锁定，则返回 true，否则返回 false。模块必须包含导出的类型才能找到。

template <typename T> 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中，我们将一个字符串分配给bar属性的baz

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

为了让QML引擎知道Bar类型有一个baz属性，我们必须让Bar为人所知

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

由于在QML中实例化Foo类型，它必须使用带元素名的qmlRegisterType()版本注册

返回QML类型id。

另请参阅 QML_ANONYMOUS和在C++和QML之间选择正确集成方法。

模板 <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

这个模板函数使用从uri导入的库中名为qmlName的名称，在QML系统中注册C++类型及其扩展对象，其版本号由versionMajor和versionMinor组成。将搜索主类型中不可用的属性扩展对象。

返回QML类型id。

另请参阅 QML_EXTENDED()、qmlRegisterType()和注册扩展对象。

模板 <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

这个模板函数使用从uri导入的库中名为qmlName的名称，在QML系统中注册C++类型及其扩展，其版本号由versionMajor和versionMinor组成。

尽管这个类型有名称和类型，但无法创建它。如果用户尝试创建此类型的实例，将打印出具有给定reason的错误消息。

这在类型仅用于提供附加属性、枚举值或具有其扩展的抽象基类时很有用。

返回QML类型id。

另请参阅 QML_EXTENDED()、QML_UNCREATABLE()和qmlRegisterUncreatableType()。

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

这个函数在一个特定的uri上注册一个模块，在versionMajor和versionMinor中指定版本。

这可以用来使某个模块版可用，即使没有为该版本注册类型。这在保持相关模块版本同步时特别有用。

void qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

注册模块uri的qmakeir-import，其主版本为moduleMajor。

这与qmultir文件中的导入语句具有相同的效果：当导入moduleMajor版本的uri时，会自动导入 mniejsze warianty，包括importMajor. 如果 importMajor 是 QQmlModuleImportLatest，则会导入该模块的最新版本，此时 importMinor 不重要。如果 importMinor 是 QQmlModuleImportLatest，则会选择 importMajor 的最新次要版本。如果 importMajor 是 QQmlModuleImportAuto，则导入的版本与 uri 正在导入的版本相同，此时 importMinor 不重要。如果 moduleMajor 是 QQmlModuleImportModuleAny，则针对 uri 的任何主版本应用模块导入。例如，您可能指定，当任何版本的 MyModule 被导入时，应导入 MyOtherModule 的最新版本。那么，以下调用是合适的。

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportLatest);

或者，您可能指定，当导入 "MyModule" 的主版本 5 时，导入 "MyOtherModule" 的 3.14 版本。

qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);

最后，如果您希望每次导入 "MyModule" 时都导入相同的 "MyOtherModule" 版本，请指定以下内容。

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportAuto);

另请参阅 qmlUnregisterModuleImport。

模板 <typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

这个模板函数使用从 uri 导入的库在 QML 系统中注册指定的 C++ 类型的特定版本，其版本号由 versionMajor 和 versionMinor 组成。

返回QML类型id。

template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

此函数通常用于将基类的修订版注册为指定类型的指定版本（请参阅 类型修订版和版本）。

int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)

此函数用于注册特定 uri 和 typeName 的单例对象 cppObject。其版本由 versionMajor 和 versionMinor 组成。

将单例类型安装到 URI 允许您不要求客户端为该类型创建单独实例，就为 QML 代码提供任意的功能（方法属性）。

使用此函数将给定类型 T 的对象注册为单例类型。

使用注册的单例类型名称可以引用 QObject 单例类型，这些名称可以用作Connections类型的目标，或作为任何其他类型 ID。然而，有一个例外：QObject 单例类型属性不能重命名，因为单例类型名称不能标识同一组件中任何其他项。

注意：qmlRegisterSingleton只能在所有该模块的类型都按程序方式进行注册时使用。

用法

// 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:
    explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE int doSomething()
    {
        setSomeProperty(5);
        return m_someProperty;
    }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) {
        if (m_someProperty != val) {
            m_someProperty = val;
            emit somePropertyChanged(val);
        }
    }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty = 0;
};

// Second, create an instance of the object

// allocate example before the engine to ensure that it outlives it
QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
QQmlEngine engine;

// Third, register the singleton type provider with QML by calling this
// function in an initialization function.
qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());

为了在QML中使用已注册的单例类型，您必须导入对应版本的URI。

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        console.log(MyApi.doSomething())
    }
}

参见：QML_SINGLETON 和 qmlRegisterSingletonType.

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue> (QQmlEngine *, QJSEngine *)> callback)

此函数可用于在特定uri和typeName中注册单例类型提供程序callback，版本由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 lambda

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
}

参见：QML_SINGLETON 和 选择C++和QML之间正确的集成方法.

template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject> *(QQmlEngine *, QJSEngine *)> callback)

此函数可用于在特定uri和typeName中注册单例类型提供程序callback，版本由versionMajor和versionMinor指定。

将单例类型安装到URI中允许开发者向客户端提供任意功能（方法和属性），而无需客户端实例化类型的单个实例。

单例类型可以是QObject或QJSValue。此函数应用于注册返回给定类型T的QObject的单例类型提供程序函数。

可以通过在注册时所使用的类型名称来引用QObject单例类型，并可以使用此类型名称作为Connections类型的目标或其他类型id使用。此例外的例外是，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 = nullptr)
        : 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 lambda

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

参见：QML_SINGLETON 和 选择C++和QML之间正确的集成方法.

int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

此功能可用于以名称 qmlName 注册单例类型，在从具有版本号由 versionMajor 和 versionMinor 组成的 uri 导入的库中。该类型由位于 url 的 QML 文件定义。URL 必须是绝对 URL，即 url.isRelative() == false。

此外，类型的 QML 文件必须在它的导入语句中包含 pragma Singleton 语句。

单例类型可以通过其注册的类型名称进行引用，并且此类型名称可以用作 Connections 类型的目标或用于任何其他类型 ID。一个例外是，单例类型属性可能不能重命名（因为单例类型名称不能识别与其他任何项相同的组件内的对象）。

用法

// 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
}

还可以不使用 qmlRegisterSingletonType 函数而注册 QML 单例类型。这可以通过在类型的 QML 文件的导入语句中添加 pragma Singleton 语句来完成。此外，类型必须在具有单例关键字的 qmldir 文件中定义，并且 qmldir 必须由使用单例的 QML 文件导入。

另请参阅 QML_SINGLETON.

template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

此模板函数将在 QML 系统中注册 C++ 类型，并使用名称 qmlName，在从 uri 导入的库中，该版本号由 versionMajor 和 versionMinor 组成。

返回QML类型id。

此模板函数有两种形式

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 注册为名为 Slider 的 QML 类型，属于版本为 1.0 的类型命名空间 "com.mycompany.qmlcomponents"。

qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

注册后，类型可以使用指定的类型命名空间和版本号在 QML 中使用。

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

请注意，库为比实际库版本更旧的版本注册类型是完全合理的。实际上，新库通常允许之前版本编写的 QML 继续工作，即使有一些类型的更高级版本可用。

另请参阅 QML_ELEMENT，QML_NAMED_ELEMENT()，以及 在 C++ 和 QML 之间选择正确的集成方法。

int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

此函数在 QML 系统中注册具有名称 qmlName 的类型，在从 uri 导入的库中，该版本号由 versionMajor 和 versionMinor 组成。该类型由位于 url 的 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类型id。

示例

#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif

这将导致任何导入"MinehuntCore"类型命名空间并尝试使用该类型的QML产生一个错误信息

fun.qml: Get back to work, slacker!
   Game {
   ^

否则，会给出通用的“游戏不是一个类型”的信息。

另请参阅 QML_UNAVAILABLE、qmlRegisterUncreatableType()，以及在C++和QML之间选择正确的集成方法。

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

此函数在QML系统中以从uri导入的库中的名称qmlName注册指定的staticMetaObject及其扩展。

不能创建元实例。如果用户尝试创建它，将打印出带有给定reason的错误信息。

此函数用于注册Q_NAMESPACE命名空间。

返回QML类型id。

例如

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

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

在QML方面，你现在可以使用注册的枚举

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

另请参阅 QML_ELEMENT、QML_NAMED_ELEMENT()以及QML_UNCREATABLE。

template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

此模板函数将在 QML 系统中注册 C++ 类型，并使用名称 qmlName，在从 uri 导入的库中，该版本号由 versionMajor 和 versionMinor 组成。

虽然该类型有一个名称和一个类型，但它不能被创建，如果尝试创建，则会给出给定的错误message。

这在只打算提供附加属性或枚举值的地方很有用。

返回QML类型id。

另请参阅 QML_UNCREATABLE、qmlRegisterTypeNotAvailable以及在C++和QML之间选择正确的集成方法。

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

返回具有在特定uri中注册并具有在versionMajor和versionMinor中指定的版本的名称qmlName的类型ID。

此函数返回与QML类型注册函数如qmlRegisterType() 和qmlRegisterSingletonType()类似的值。

如果qmlName、uri和versionMajor与已注册的类型匹配，但指定在versionMinor中的次要版本更高，则返回最接近次要版本的类型的ID。

如果未找到匹配的类型或提供的参数之一无效，则返回-1。

另请参阅QML_ELEMENT、QML_NAMED_ELEMENT、QML_SINGLETON、qmlRegisterType() 和 qmlRegisterSingletonType().

void qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

删除先前使用qmlRegisterModuleImport()注册的模块导入。

调用此函数可确保当使用moduleMajor版本的uri时，不会自动导入版本importMajor.importMinor的import。版本解析的方式与qmlRegisterModuleImport()相同。

另请参阅qmlRegisterModuleImport().