qqml.h 代理页面

功能文档

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不是有效的附加类型，则返回nullptr ；如果create 为 false 且之前未为attachee 创建过附加对象实例，则返回 。

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

void qmlClearTypeRegistrations()

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

请勿在QQmlEngine 存在时调用此函数，否则将导致行为未定义。在调用此函数之前，必须删除任何现有的 QQmlEngines。此函数只影响应用程序的全局缓存。删除QQmlEngine 可清除与该引擎相关的所有缓存数据。

QObject *qmlExtendedObject(QObject *base)

该函数返回属于base 的扩展对象（如果有）。否则返回nullptr 。

另请参见 QML_EXTENDED 。

bool qmlProtectModule(const char *uri, int majVersion)

该函数可保护模块不再被修改。这可用于防止其他插件向模块注入类型。它还能提高性能，因为当达到这个导入时，它允许引擎跳过检查新类型或插件的可能性。

一旦 qmlProtectModule 被调用，QML 引擎将不再搜索新的qmldir 文件来加载模块。但它会重新使用之前加载过的任何qmldir 文件。因此，此时存在的类型仍可继续使用。请注意，不同的 QML 引擎可能加载不同的模块。不过，模块保护是全局性的，会影响所有引擎。如果文件系统较慢，查找qmldir 文件和加载插件的开销可能会很明显。因此，一旦确定不再需要加载模块，对其进行保护是一种很好的优化。还要注意的是，模块锁不仅会影响插件，还会影响任何其他 qmldir 指令，如import 或prefer ，以及qmldir 文件中声明的任何复合类型或脚本。

此外，调用此函数后，任何将 C++ 类型注册到此 uri、主要版本组合中的尝试都将导致运行时错误。

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

template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)

此模板函数在 QML 系统中将 C++ 类型注册为匿名类型。生成的 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);

由于Foo 类型是在 QML 中实例化的，因此它必须在接受元素名称的qmlRegisterType() 版本中注册。

返回 QML 类型 id。

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

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

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

返回 QML 类型 ID。

另请参阅 QML_EXTENDED(),qmlRegisterType() 和Registering Extension Objects（注册扩展对象）。

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

该模板函数在 QML 系统中注册 C++ 类型及其扩展名qmlName ，该扩展名位于从uri 导入的库中，其版本号由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)

为主要版本moduleMajor 的模块uri 注册 qmldir-import 。

这与 qmldir 文件中的import 语句效果相同：每当导入moduleMajor 版本的uri 时，importMajor 版本的import.importMinor 也会自动导入。如果importMajor 是QQmlModuleImportLatest ，则会导入该模块的最新版本，而importMinor 并不重要。如果importMinor 是QQmlModuleImportLatest ，则选择importMajor 的最新次版本。如果importMajor 是QQmlModuleImportAuto ，则导入import 的版本是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()。

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

此模板函数在 QML 系统中注册 C++ 类型的指定修订版，该修订版从uri 导入，其版本号由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)

该函数用于注册一个单例对象cppObject ，特定的uri 和typeName 。其版本是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 QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

该函数可用于在从uri 导入的库中注册一个名称为qmlName 的单例类型，其版本号由versionMajor 和versionMinor 组成。该类型由位于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 文件中定义，使用单例的 QML 文件必须导入 qmldir。

另请参阅 QML_SINGLETON 。

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 之间选择正确的集成方法。

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 注册为 QML 类型Slider ，版本 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 {
   ^

如果没有这条信息，就会出现 "Game is not a type"（游戏不是一种类型）的通用信息。

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

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

该函数在 QML 系统中注册staticMetaObject 及其扩展名，该扩展名位于从uri 导入的库中的qmlName ，其版本号由versionMajor 和versionMinor 组成。

元对象的实例无法创建。如果用户试图创建它，则会打印一条带有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() 和Choosing the Correct Integration Method Between C++ and QML。

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

返回已注册的 QML 类型 id，该类型的名称是qmlName ，在特定的uri 中注册，版本在versionMajor 和versionMinor 中指定。

此函数返回与 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() 注册的模块导入。

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

另请参见 qmlRegisterModuleImport()。