<qqml.h> - Functions to register C++ types to QML
Header: | #include <qqml.h> |
유형
enum | QQmlModuleImportSpecialVersions { QQmlModuleImportModuleAny, QQmlModuleImportLatest, QQmlModuleImportAuto } |
기능
QObject * | qmlAttachedPropertiesObject(const QObject *attachee, bool create = true) |
void | qmlClearTypeRegistrations() |
QObject * | qmlExtendedObject(QObject *base) |
bool | qmlProtectModule(const char *uri, int majVersion) |
int | qmlRegisterAnonymousType(const char *uri, int versionMajor) |
int | qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) |
int | qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason) |
void | qmlRegisterModule(const char *uri, int versionMajor, int versionMinor) |
void | qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest) |
int | qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) |
int | qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject) |
int | qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName) |
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback) |
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback) |
int | qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) |
int | qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName) |
int | qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message) |
int | qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason) |
int | qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message) |
int | qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName) |
void | qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest) |
매크로
QML_DECLARE_TYPE | |
QML_DECLARE_TYPEINFO(Type, Flags) |
개요 - QML 및 C++ 통합, qqmlintegration.h 및 qmltyperegistrar도참조하세요 .
유형 문서
enum QQmlModuleImportSpecialVersions
qmlRegisterModuleImport() 및 qmlUnregisterModuleImport()의 버전 인수에 전달할 수 있는 몇 가지 특수 값을 정의합니다.
Constant | 값 | 설명 |
---|---|---|
QQmlModuleImportModuleAny | -1 | 기본 모듈의 주요 버전으로 전달되면 가져오기가 모듈의 모든 버전에 적용됨을 나타냅니다. |
QQmlModuleImportLatest | -1 | 가져온 모듈의 메이저 또는 마이너 버전으로 전달되면 지정된 메이저 버전의 최신 전체 버전 또는 최신 마이너 버전을 가져온다는 의미입니다. |
QQmlModuleImportAuto | -2 | 가져온 모듈의 메이저 버전으로 전달되면 기본 모듈의 버전이 전달됨을 나타냅니다. |
함수 문서
template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
이 템플릿 함수의 형태는 다음과 같습니다:
template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
지정한 attachee 에 첨부 유형 T 로 첨부된 첨부된 객체 인스턴스를 반환합니다.
create 이 참이고 첨부 유형 T가 유효한 첨부 유형이면 새 첨부 개체 인스턴스를 생성하여 반환합니다.
T 유형이 유효한 첨부 유형이 아니거나 create 이 거짓이고 이전에 attachee 에 대해 첨부 개체 인스턴스가 생성되지 않은 경우 nullptr
을 반환합니다.
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
파일을 찾고 플러그인을 로드하는 오버헤드는 느린 파일 시스템에서 눈에 띄게 나타날 수 있습니다. 따라서 모듈을 더 이상 로드할 필요가 없다고 판단되면 모듈을 보호하는 것이 좋은 최적화 방법일 수 있습니다. 모듈 잠금은 플러그인뿐만 아니라 import
또는 prefer
과 같은 다른 qmldir 지시어와 qmldir
파일에 선언된 모든 복합 유형 또는 스크립트에도 영향을 미친다는 점도 기억하세요.
또한 이 함수가 호출된 후 이 uri, 메이저 버전 조합에 C++ 유형을 등록하려고 시도하면 런타임 오류가 발생합니다.
모듈 식별자가 uri, 메이저 버전 번호가 majVersion 인 모듈이 발견되어 잠겨 있으면 참을 반환하고, 그렇지 않으면 거짓을 반환합니다. 모듈을 찾으려면 모듈에 내보낸 유형이 포함되어 있어야 합니다.
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)
이 템플릿 함수는 versionMajor 및 versionMinor 에서 구성된 버전 번호를 가진 uri 에서 가져온 라이브러리에 qmlName 이라는 이름으로 C++ 유형과 해당 확장 객체를 QML 시스템에 등록합니다. 기본 유형에서 사용할 수 없는 속성은 확장 객체에서 검색됩니다.
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)
이 템플릿 함수는 versionMajor 및 versionMinor 에서 구성된 버전 번호를 가진 uri 에서 가져온 라이브러리에 qmlName 이라는 이름으로 C++ 유형과 해당 확장자를 QML 시스템에 등록합니다.
유형에 이름과 유형이 있지만 생성할 수 없습니다. 사용자가 이 유형의 인스턴스를 만들려고 하면 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
문과 동일한 효과가 있습니다: uri 버전 moduleMajor 을 가져올 때마다 import 버전 importMajor. 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++ 타입의 지정된 리비전을 QML 시스템에 등록합니다.
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 싱글톤 유형 속성은 별칭을 붙일 수 없습니다. 싱글톤 유형 이름이 다른 항목과 동일한 컴포넌트 내의 개체를 식별하지 않기 때문입니다.
참고: cppObject 은 사용되는 QML 엔진보다 오래 지속되어야 합니다. 또한 cppObject는 엔진과 동일한 스레드 선호도를 가져야 합니다. 여러 엔진에 대해 별도의 싱글톤 인스턴스를 사용하려면 qmlRegisterSingletonType 을 사용해야 합니다. 스레드 안전성에 대한 자세한 내용은 스레드 및 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 에서 가져온 라이브러리에 versionMajor 및 versionMinor 에서 구성한 버전 번호를 가진 qmlName 이라는 이름의 싱글톤 유형을 등록하는 데 사용할 수 있습니다. 이 유형은 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 람다를 사용할 수 있습니다:
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 타입의 대상으로 사용하거나 다른 타입 아이디처럼 사용할 수 있습니다. 단, 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)
이 템플릿 함수는 uri 에서 가져온 라이브러리에 versionMajor 및 versionMinor 에서 구성한 버전 번호를 가진 qmlName 이라는 이름의 C++ 타입을 QML 시스템에 등록합니다.
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)
이 함수는 uri 에서 가져온 라이브러리에 versionMajor 및 versionMinor 에서 구성한 버전 번호를 가진 qmlName 이라는 이름의 유형을 QML 시스템에 등록합니다. 이 유형은 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)
이 함수는 uri 에서 가져온 유형 네임스페이스에 versionMajor 및 versionMinor 에서 구성된 버전 번호를 가진 qmlName 이라는 이름으로 유형을 QML 시스템에 등록하지만 유형을 인스턴스화하려고 시도하면 지정된 오류 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)
이 함수는 uri 에서 가져온 라이브러리에서 qmlName 이라는 이름으로 versionMajor 및 versionMinor 에서 구성된 버전 번호를 가진 staticMetaObject 및 해당 확장자를 QML 시스템에 등록합니다.
메타 객체의 인스턴스는 생성할 수 없습니다. 사용자가 만들려고 하면 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)
이 템플릿 함수는 uri 에서 가져온 라이브러리에 versionMajor 및 versionMinor 에서 구성된 버전 번호를 가진 qmlName 이라는 이름의 C++ 타입을 QML 시스템에 등록합니다.
유형에 이름과 유형이 있지만 생성할 수 없으며, 생성을 시도하면 지정된 오류 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을 반환합니다.
참고: : 모듈이 아직 어떤 엔진에서도 액세스되지 않은 경우에도 qmlTypeId는 모듈을 사용 가능하게 만들려고 시도합니다. 이로 인해 모듈에 처음 액세스할 때 오버헤드가 발생할 수 있습니다. 존재하지 않는 모듈에서 유형을 찾으려고 하면 항상 이 오버헤드가 발생합니다.
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()도 참조하세요 .
매크로 문서
QML_DECLARE_TYPE
Q_DECLARE_METATYPE(TYPE *)
및 Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)
QML_DECLARE_TYPEINFO(Type, Flags)
지정된 Flags 에 설명된 대로 지정된 Type 의 추가 속성을 선언합니다.
현재 지원되는 유일한 유형 정보는 QML_HAS_ATTACHED_PROPERTIES
으로, Type 이 첨부된 속성을 지원한다고 선언합니다. Type 에 QML_ATTACHED 매크로가 포함된 경우 QML_DECLARE_TYPEINFO()는 필요하지 않습니다.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.