<qqml.h> - Functions to register C++ types to QML

함수 문서

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

이 템플릿 함수의 형식은 다음과 같습니다.

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

이 함수는 부착 유형 T에 의해 지정된 attachee 에 부착된 부착된 객체 인스턴스를 반환합니다.

attachee 가 nullptr 인 경우, nullptr 를 반환합니다.

T 유형의 기존 부착된 객체 인스턴스가 존재하는 경우, 해당 인스턴스를 반환합니다. 그렇지 않은 경우, ` createIfMissing `가 ` true `이고 T가 유효한 부착 유형이면 새로 생성된 인스턴스를 반환하며, 그렇지 않은 경우 ` nullptr `를 반환합니다.

QML_ATTACHED() 및 '부착 속성 제공'항목도 참조하십시오.

void qmlClearTypeRegistrations()

qmlRegisterType()를 통해 생성된 것과 같은 저장된 모든 유형 등록 정보를 지웁니다.

이 함수는 애플리케이션 전역 캐시에만 영향을 미칩니다. 해당 엔진과 관련된 모든 캐시된 데이터를 지우려면 QQmlEngine 을 삭제하십시오.

QObject *qmlExtendedObject(QObject *base)

이 함수는 base 에 속하는 확장 객체가 있는 경우 해당 객체를 반환합니다. 그렇지 않은 경우 nullptr 를 반환합니다.

QML_EXTENDED도 참조하십시오 .

bool qmlProtectModule(const char *uri, int majVersion)

이 함수는 모듈이 더 이상 수정되지 않도록 보호합니다. 이를 통해 다른 플러그인이 해당 모듈에 타입을 삽입하는 것을 방지할 수 있습니다. 또한, 이 임포트가 수행될 때 엔진이 새로운 타입이나 플러그인의 존재 여부를 확인하는 과정을 건너뛸 수 있게 해줌으로써 성능을 향상시킬 수도 있습니다.

qmlProtectModule이 호출되면, QML 엔진은 모듈을 로드하기 위해 새로운 qmldir 파일을 더 이상 검색하지 않습니다. 다만, 이전에 로드했던 qmldir 파일은 재사용합니다. 따라서 이 시점에 존재하는 타입은 계속 작동합니다. QML 엔진에 따라 로드되는 모듈이 다를 수 있다는 점에 유의하십시오. 그러나 모듈 보호는 전역적이며 모든 엔진에 영향을 미칩니다. 파일 시스템 속도가 느린 경우, qmldir 파일을 찾고 플러그인을 로드하는 데 드는 오버헤드가 눈에 띄게 나타날 수 있습니다. 따라서 더 이상 모듈을 불러올 필요가 없다고 확신할 때 모듈을 보호하는 것은 좋은 최적화 방법이 될 수 있습니다. 또한 모듈 잠금은 플러그인뿐만 아니라 import 나 prefer 와 같은 다른 qmldir 지시문은 물론, qmldir 파일에 선언된 모든 복합 유형이나 스크립트에도 영향을 미친다는 점에 유의하십시오.

또한, 이 함수가 호출된 후에는 이 URI와 메이저 버전 조합에 C++ 타입을 등록하려는 모든 시도가 런타임 오류를 유발합니다.

모듈 식별자가 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);

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)

이 템플릿 함수는 C++ 타입과 해당 확장 객체를 QML 시스템에 ‘ qmlName ’라는 이름으로 등록합니다. 이 타입은 uri 에서 가져온 라이브러리에 포함되며, 버전 번호는 versionMajor 와 versionMinor 로 구성됩니다. 기본 타입에 없는 속성은 확장 객체에서 검색됩니다.

QML 타입 ID를 반환합니다.

QML_EXTENDED(), qmlRegisterType() 및 확장 객체 등록을참조하십시오 .

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

이 템플릿 함수는 C++ 타입과 그 확장 기능을 QML 시스템에 ‘ 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)

이 템플릿 함수는 uri 에서 가져온 라이브러리를 사용하여, versionMajor 및 versionMinor 로 구성된 버전 번호를 가진 C++ 타입 ` T `을 QML 시스템의 지정된 리비전 metaObjectRevision 에 등록합니다.

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 QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

이 함수는 versionMajor 및 versionMinor 로 구성된 버전 번호를 가진, uri 에서 가져온 라이브러리에 qmlName 라는 이름의 싱글톤 타입을 등록하는 데 사용할 수 있습니다. 이 타입은 url 에 위치한 QML 파일로 정의됩니다. URL은 절대 URL이어야 하며, 즉 url.isRelative() == false여야 합니다.

또한, 해당 타입의 QML 파일에는 import 문 중 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 문을 추가함으로써 가능합니다. 또한 해당 타입은 singleton 키워드와 함께 qmldir 파일에 정의되어야 하며, singleton을 사용하는 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 람다식을 사용할 수도 있습니다:

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 ` 싱글톤 타입 인스턴스는, 해당 객체에 `QQmlEngine::CppOwnership` 플래그가 명시적으로 설정되어 있지 않은 한 QML 엔진이 소유합니다.

사용법:

// 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 람다식을 사용할 수도 있습니다:

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)

이 템플릿 함수는 qmlName 라는 이름으로, uri 에서 가져온 라이브러리에 C++ 타입을 등록하며, 버전 번호는 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 `를 “com.mycompany.qmlcomponents”라는 유형 네임스페이스의 버전 1.0에 대해 ` Slider `라는 QML 유형으로 등록합니다:

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)

이 함수는 qmlName 라는 이름으로 QML 시스템에 타입을 등록하며, 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은 타입이 아닙니다"와 같은 일반적인 오류 메시지가 표시됩니다.

QML_UNAVAILABLE, 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 유형 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)

이 템플릿 함수는 qmlName 라는 이름으로, uri 에서 가져온 라이브러리 내에 C++ 타입을 QML 시스템에 등록하며, 이 라이브러리의 버전 번호는 versionMajor 와 versionMinor 로 구성됩니다.

이 타입은 이름과 타입을 가지고 있지만 생성할 수는 없으며, 생성을 시도하면 message 오류가 발생합니다.

이는 타입이 부착 속성이나 열거형 값을 제공하는 용도로만 사용될 때 유용합니다.

QML 타입 ID를 반환합니다.

QML_UNCREATABLE(), qmlRegisterTypeNotAvailable() 및 C++과 QML 간의 올바른 통합 방법 선택을참조하십시오 .

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

특정 uri 에 qmlName 라는 이름으로 등록되고, versionMajor 및 versionMinor 에 지정된 버전을 가진 타입의 QML 타입 ID를 반환합니다.

이 함수는 qmlRegisterType() 및 qmlRegisterSingletonType()과 같은 QML 타입 등록 함수와 동일한 값을 반환합니다.

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 의 import.importMinor 는 버전 moduleMajor 의 uri 가 자동으로 임포트될 때 더 이상 자동으로 임포트되지 않게 됩니다. 버전 확인 방식은 qmlRegisterModuleImport()와 동일하게 작동합니다.

qmlRegisterModuleImport()도 참조하십시오 .