<qqmlintegration.h>

매크로 문서

QML_ADDED_IN_VERSION(MAJOR, MINOR)

지정된 MAJOR 버전에서 해당 외곽 타입이나 네임스페이스가 추가되었음을 선언합니다.MINOR. 이 버전은 메서드, 슬롯 또는 시그널에 대한 Q_REVISION() 매크로로 지정된 모든 개정 사항 및 Q_PROPERTY()으로 선언된 속성에 대한 모든 REVISION() 속성과 일치하는 것으로 간주됩니다.

QML_ADDED_IN_VERSION()은 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS 또는 QML_INTERFACE 매크로가 정의되어 있어 해당 타입이나 네임스페이스가 QML에서 사용 가능한 경우에만 효과가 있습니다.

해당 타입이 속한 QML 모듈이 이 방식으로 결정된 버전보다 낮은 버전으로 임포트된 경우, 해당 QML 타입은 표시되지 않습니다.

QML_ELEMENT 및 QML_NAMED_ELEMENT도 참조하십시오 .

QML_ANONYMOUS

포함된 타입을 QML에서 사용할 수 있도록 선언하지만, 익명 타입으로 처리됩니다. 이 타입은 QML에서 생성하거나 속성을 선언하는 데 사용할 수 없지만, C++에서 전달될 경우 인식됩니다. QML에서는 C++에서 선언된 경우 이 타입의 속성을 사용할 수 있습니다.

QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE도 참조하십시오 .

QML_ATTACHED(ATTACHED_TYPE)

포함하는 타입이 ATTACHED_TYPE 를 다른 타입에 부착 속성으로 부여한다고 선언합니다. 이는 QML_ELEMENT 또는 QML_NAMED_ELEMENT() 매크로를 사용하여 해당 타입이 QML에 노출될 때 적용됩니다.

QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), 및 ‘부착 속성 제공’항목도 참조하십시오 .

[since 6.5] QML_CONSTRUCTIBLE_VALUE

주변의 값 유형을 생성 가능 유형으로 표시합니다. 즉, 이 유형의 속성에 JavaScript 값을 할당할 때, 해당 유형의 인수를 정확히 하나만 받는 모든 Q_INVOKABLE 생성자를 사용할 수 있습니다.

생성 가능한 값 유형은 다음과 같이 선언할 수 있습니다:

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_CONSTRUCTIBLE_VALUE
public:
    Q_INVOKABLE MyValueType(double d);

    // ...
};

위의 유형을 사용하면, 다음 QML 코드는 주어진 생성자를 사용하여 ` MyValueType ` 값을 생성하고 이를 속성에 할당합니다.

QtObject {
    property myValueType v: 5.4
}

또한 다음과 같은 방식으로 값의 리스트를 생성할 수도 있습니다:

QtObject {
    property list<myValueType> v: [5.4, 4.5, 3.3]
}

Qt 6.8부터는 해당 값 유형이 속한 Qml 모듈을 네임스페이스로 임포트하면, JavaScript의 new 연산자를 사용하여 인스턴스를 생성할 수 있습니다.

import MyModule as MM

QtObject {
    function process(d: real) {
        let v = new MM.myValueType(d);
        // v is a myValueType now
    }
}

이 매크로는 Qt 6.5에서 도입되었습니다.

QML_VALUE_TYPE도 참조하십시오 .

QML_ELEMENT

포함된 타입이나 네임스페이스를 QML에서 사용할 수 있도록 선언하며, 해당 클래스 또는 네임스페이스 이름을 QML 요소 이름으로 사용합니다.

예를 들어, 이 작업을 통해 C++ 클래스 ` Slider `를 ` Slider`라는 이름의 QML 타입으로 사용할 수 있게 됩니다. 이 클래스의 모든 속성, 호출 가능한 메서드 및 열거형이 노출됩니다.

class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
    // ...
public:
    enum Slippiness {
        Dry, Wet, Icy
    };
    Q_ENUM(Slippiness)

    Q_INVOKABLE void slide(Slippiness slippiness);

    // ...
}

빌드 시스템을 사용하여 해당 타입을 com.mycompany.qmlcomponents 타입 네임스페이스에 주요 버전 1 으로 등록할 수 있습니다. qmake의 경우, 프로젝트 파일에 다음을 지정하십시오:

CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1

CMake를 사용하는 경우, URI와 버전을 qt_add_qml_module()에 전달합니다.

qt_add_qml_module(myapp
  URI com.mycompany.qmlcomponents
  VERSION 1.0
)

등록이 완료되면, QML에서 동일한 타입 네임스페이스와 버전 번호를 가져와 해당 타입을 사용할 수 있습니다:

import com.mycompany.qmlcomponents 1.0

Slider {
    value: 12
    Component.onCompleted: slide(Slider.Icy)

    // ...
}

또한 Q_NAMESPACE 태그가 지정된 네임스페이스를 이 방법으로 사용할 수 있게 하여, 해당 네임스페이스에 포함된 Q_ENUM_NS 태그가 지정된 열거형을 노출할 수 있습니다:

namespace MyNamespace {
  Q_NAMESPACE
  QML_ELEMENT

  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

그러면 QML에서 해당 열거형을 사용할 수 있습니다:

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

참고: 클래스 이름이 동일하지만 서로 다른 네임스페이스에 위치한 경우, 두 클래스 모두에 QML_ELEMENT를 사용하면 충돌이 발생합니다. 대신 그중 하나에 대해서는 QML_NAMED_ELEMENT()를 사용해야 합니다.

관련 항목: C++과 QML 간의 올바른 통합 방법 선택, QML_NAMED_ELEMENT(), Q_REVISION(), QML_ADDED_IN_VERSION()을 참조하십시오 .

QML_EXTENDED(EXTENDED_TYPE)

포함하는 타입이 QML에서 추가적인 속성, 메서드 및 열거형을 제공하기 위해 EXTENDED_TYPE 를 확장으로 사용함을 선언합니다. 이는 QML_ELEMENT 또는 QML_NAMED_ELEMENT() 매크로를 사용하여 해당 타입이 QML에 노출될 때 적용됩니다.

QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE() 및 확장 객체 등록도참조하십시오 .

QML_EXTENDED_NAMESPACE(EXTENSION_NAMESPACE)

포함하는 타입이 QML에서 추가 열거형을 제공하기 위해 ` EXTENSION_NAMESPACE `를 확장으로 사용함을 선언합니다. 이는 ` QML_ELEMENT ` 또는 ` QML_NAMED_ELEMENT()` 매크로를 사용하여 해당 타입이 QML에 노출될 때 적용됩니다. 이 기능이 작동하려면 해당 열거형이 메타오브젝트 시스템에 노출되어야 합니다.

예를 들어, 다음과 같은 C++ 코드가 있다고 가정해 봅시다.

namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum { MyEnumerator = 10 };
    Q_ENUM_NS(MyEnum)
}

class QmlType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_EXTENDED_NAMESPACE(MyNamespace)
}

QML에서 해당 열거형에 다음과 같이 접근할 수 있습니다:

QmlType {
    property int i: QmlType.MyEnumerator // i will be 10
}

관련 항목: QML_NAMESPACE_EXTENDED(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(), 확장 객체 등록, Q_ENUM, Q_ENUM_NS.

QML_EXTRA_VERSION(MAJOR, MINOR)

MAJOR 버전에서도 해당 타입을 사용할 수 있도록 선언합니다.MINOR. 이는 하나의 타입을 여러 주요 버전에서 사용할 수 있도록 해야 할 때 유용할 수 있습니다.

다음과 같은 경우 유형이 자동으로 등록됩니다:

• 해당 타입이 도입된 주요 버전( QML_ADDED_IN_VERSION 참조).
• 해당 타입의 구성원이 도입된 모든 메이저 버전.
• 해당 모듈의 현재 메이저 버전(단, 그 이전에 이미 QML_REMOVED_IN_VERSION 상태였던 경우는 제외).

특히, 위 버전들 사이의 PAST_MAJOR_VERSIONS에는 자동으로 등록되지 않습니다. QML_EXTRA_VERSION을 사용하여 타입을 다른 주요 버전에 수동으로 등록할 수 있습니다.

QML_ELEMENT 및 QML_ADDED_IN_VERSION도 참조하십시오 .

QML_FOREIGN(FOREIGN_TYPE)

포함하는 C++ 유형 내의 모든 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_EXTENDED(), QML_EXTENDED_NAMESPACE() 또는 QML_NAMESPACE_EXTENDED() 매크로는 해당 포함 유형이 아닌 FOREIGN_TYPE 에 적용된다고 선언합니다. 포함된 유형은 여전히 Q_GADGET 또는 Q_OBJECT 매크로를 사용하여 메타 객체 시스템에 등록되어야 합니다.

이는 예를 들어 타사 라이브러리에 속해 있어 매크로를 추가하기 위해 수정할 수 없는 유형을 등록하는 데 유용합니다. 네임스페이스를 등록하려면 QML_FOREIGN_NAMESPACE()을 참조하십시오.

QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN_NAMESPACE()도 참조하십시오 .

QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

포함된 C++ 네임스페이스 내의 모든 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION() 또는 QML_REMOVED_IN_MINOR_VERSION() 매크로는 포함된 타입이 아닌 FOREIGN_NAMESPACE 에 적용된다고 선언합니다. 포함된 네임스페이스는 여전히 Q_NAMESPACE 매크로를 사용하여 메타 객체 시스템에 등록되어야 합니다.

이는 예를 들어 타사 라이브러리에 속해 있어 매크로를 추가하기 위해 수정할 수 없는 네임스페이스를 등록하는 데 유용합니다.

QML_ELEMENT, QML_NAMED_ELEMENT() 및 QML_FOREIGN()도 참조하십시오 .

QML_IMPLEMENTS_INTERFACES(interfaces)

이 매크로는 클래스가 어떤 QML interfaces 을 구현하는지 Qt에 알려줍니다. 이 매크로는 QML_INTERFACE 를 사용하여 클래스와 연동할 때에만 사용해야 하며, 그 외의 경우에는 Q_INTERFACES 를 사용해야 합니다. QML_ELEMENT 를 통한 선언적 등록이 제대로 작동하려면 이 매크로가 필수적입니다.

QML_INTERFACE 및 Q_INTERFACES도 참조하십시오 .

QML_INTERFACE

이 매크로는 둘러싸고 있는 C++ 타입을 QML 시스템에 인터페이스로 등록합니다.

QML에서 인터페이스로 등록된 타입은 메타 객체 시스템에서도 인터페이스로 선언되어야 합니다. 예를 들어:

struct FooInterface
{
    QML_INTERFACE
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에서 인터페이스 유형은 암시적으로 익명이며 생성할 수 없습니다.

참고: QML_INTERFACE를 사용하여 유형을 상속할 때는 Q_INTERFACES 대신 QML_IMPLEMENTS_INTERFACES 을 사용하십시오.

QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS도 참조하십시오 .

QML_NAMED_ELEMENT(name)

name 를 요소 이름으로 사용하여, 둘러싸고 있는 타입이나 네임스페이스를 QML에서 사용할 수 있도록 선언합니다. 그 외의 동작은 QML_ELEMENT 와 동일합니다.

class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};

‘C++와 QML 간의 올바른 통합 방법 선택 ’ 및 ‘ QML_ELEMENT ’항목도 참조하십시오 .

QML_REMOVED_IN_VERSION(MAJOR, MINOR)

지정된 MAJOR 에서 해당 포괄형 또는 네임스페이스가 제거되었음을 선언합니다.MINOR 버전. 이는 주로 QML 유형의 구현을 대체할 때 유용합니다. 동일한 QML 이름을 가진 다른 타입이나 네임스페이스에 해당 QML_ADDED_IN_VERSION()이 존재하는 경우, MAJORMINOR 보다 낮은 버전의 모듈을 임포트할 때는 제거된 타입이 사용되며, MAJORMINOR 이상인 버전의 모듈을 임포트할 때는 추가된 타입이 사용됩니다.

QML_REMOVED_IN_VERSION()은 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS 또는 QML_INTERFACE 매크로가 존재하여 QML에서 해당 타입이나 네임스페이스를 사용할 수 있는 경우에만 효과가 있습니다.

QML_ELEMENT 및 QML_NAMED_ELEMENT도 참조하십시오 .

QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)

이 매크로는 둘러싸고 있거나 참조되는 타입을, ` VALUE_TYPE ` 요소의 시퀀스를 관리하는 순차 컨테이너로 선언합니다. ` VALUE_TYPE `는 실제 값 타입이거나 객체 타입에 대한 포인터일 수 있습니다. 컨테이너는 대개 템플릿이므로, 이 매크로를 실제 컨테이너 선언에 직접 추가할 수 있는 경우는 거의 없습니다. QML_FOREIGN 을 사용하여 유형 등록을 템플릿 인스턴스화에 연결해야 합니다. 이 기법을 사용하면, 예를 들어 다음과 같이 순차 컨테이너를 선언할 수 있습니다.

class IntDequeRegistration
{
  Q_GADGET
  QML_FOREIGN(std::deque<int>)
  QML_ANONYMOUS
  QML_SEQUENTIAL_CONTAINER(int)
};

이렇게 하면 QML에서 해당 컨테이너를 JavaScript 배열처럼 사용할 수 있습니다.

class Maze
{
  Q_OBJECT
  Q_ELEMENT
  // 0: North, 1: East, 2: South, 3: West
  Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
  [...]
}

Item {
  Maze {
    id: maze
  }

  function showSolution() {
      maze.solution.forEach([...])
  }
}

QML_ANONYMOUS 및 QML_FOREIGN()도 참조하십시오 .

QML_SINGLETON

QML에서 해당 유형을 싱글톤으로 선언합니다. 이 설정은 해당 유형이 ` Q_OBJECT `이고 QML에서 사용할 수 있는 경우( QML_ELEMENT 또는 QML_NAMED_ELEMENT() 매크로가 정의된 경우)에만 적용됩니다. QML_UNCREATABLE() 매크로를 사용하여 해당 타입이 명시적으로 생성 불가능(uncreatable)으로 표시되지 않은 한, 각 QQmlEngine 는 해당 타입에 처음 접근할 때 타입의 기본 생성자나 T *create(QQmlEngine *, QJSEngine *) 시그니처를 가진 정적 팩토리 함수를 사용하여 싱글톤 인스턴스를 생성하려고 시도합니다. 두 가지가 모두 존재하고 접근 가능한 경우, 기본 생성자가 우선적으로 사용됩니다.

기본 생성자도 없고 팩토리 함수도 없으며, QQmlEngine::setExternalSingletonInstance 를 사용하여 엔진에 인스턴스가 명시적으로 설정되지 않은 경우, 해당 싱글톤에 접근할 수 없습니다. QML 엔진이 싱글톤을 인스턴스화한 경우, 엔진은 일반적으로 싱글톤에 대한 소유권을 가지며 엔진 자체가 소멸될 때 이를 삭제합니다. 반면, 엔진은 명시적으로 지시받지 않는 한 외부 싱글톤에 대한 소유권을 인수하지 않습니다. 싱글톤에서 ` QJSEngine::setObjectOwnership()`를 호출하여 의도된 동작을 명시적으로 지정함으로써 이 동작을 제어할 수 있습니다.

기본 생성 가능한 클래스를 싱글톤으로 선언하려면 QML_SINGLETON을 추가하기만 하면 됩니다:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )
public:
    // members, Q_INVOKABLE functions, etc.
};

싱글톤 클래스가 기본 생성자가 없더라도 수정할 수 있다면, 해당 클래스에 팩토리 함수를 추가하여 접근 가능하게 만들 수 있습니다:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    // Q_PROPERTY( ... )

public:
    static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
    {
        MySingleton *result = nullptr;
        // Create the object using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }

    // members, Q_INVOKABLE functions, etc
};

필요할 때 엔진이 인스턴스를 생성하도록 두는 대신 엔진에 인스턴스를 직접 제공하려면 ` QML_UNCREATABLE()` 매크로를 사용할 수 있습니다. 이 경우, 해당 타입은 기본 생성 가능하거나 팩토리 함수를 가질 필요가 없습니다:

class MySingleton : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    QML_UNCREATABLE("Provided by C++")
    // Q_PROPERTY( ... )
public:
    MySingleton(BackendObject* backend, QObject* parent);

    // members, Q_INVOKABLE functions, etc
};

이를 위해서는 QML에서 싱글톤에 처음 접근하기 전에 QQmlEngine::setExternalSingletonInstance() 를 사용하여 엔진에 MySingleton 인스턴스를 설정해야 합니다. 이는 qmlRegisterSingletonInstance 함수를 대체하는 것입니다.

클래스를 수정할 수 없고, 해당 클래스에 기본 생성자나 적절한 팩토리 함수가 없는 경우, ` QML_FOREIGN ` 래퍼를 제공하여 팩토리 함수를 정의할 수 있습니다:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
public:

    static MySingleton *create(QQmlEngine *, QJSEngine *engine)
    {
        MySingleton *result = nullptr;
        // Create the instance using some custom constructor or factory.
        // The QML engine will assume ownership and delete it, eventually.
        return result;
    }
};

수정할 수 없는 싱글톤을 선언하기 위한 ` QML_FOREIGN ` 방식은 ` QML_UNCREATABLE()`와 함께 사용할 수도 있습니다. 이 경우 팩토리 함수는 필요하지 않지만, 이전과 마찬가지로 첫 사용 전에 인스턴스를 엔진에 설정해야 합니다:

struct SingletonForeign
{
    Q_GADGET
    QML_FOREIGN(MySingleton)
    QML_SINGLETON
    QML_NAMED_ELEMENT(MySingleton)
    QML_UNCREATABLE("Provided from C++")
};

QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), QQmlEngine::setExternalSingletonInstance() 및 QML의 싱글톤에대해서도 참조하십시오 .

[since 6.5] QML_STRUCTURED_VALUE

주변의 값형을 구조화된 값형으로 표시합니다. 구조화된 값형은 JavaScript 객체로부터 속성별로 생성될 수 있으며, 가급적 그렇게 생성되어야 합니다. 그러나 구조화된 값형은 항상 ` QML_CONSTRUCTIBLE_VALUE`이기도 합니다. 즉, 기본형으로부터의 생성을 처리하기 위해 ` Q_INVOKABLE ` 생성자를 여전히 제공할 수 있습니다.

구조화된 값 유형은 다음과 같이 선언할 수 있습니다:

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)
    QML_STRUCTURED_VALUE
    Q_PROPERTY(double d READ d WRITE setD)
    Q_PROPERTY(string e READ e WRITE setE)

    // ...
};

그런 다음 이 유형의 속성을 다음과 같이 채울 수 있습니다:

QtObject {
    property myValueType v: ({d: 4.4, e: "a string"})
}

추가된 괄호는 JavaScript 객체가 JavaScript 코드 블록으로 오해되는 것을 방지하기 위해 필요합니다.

다음과 같은 방식으로 값의 목록도 생성할 수 있습니다:

QtObject {
    property list<myValueType> v: [
        {d: 4.4, e: "a string"},
        {d: 7.1, e: "another string"}
    ]
}

이 매크로는 Qt 6.5에서 도입되었습니다.

QML_VALUE_TYPE 및 QML_CONSTRUCTIBLE_VALUE도 참조하십시오 .

QML_UNAVAILABLE

이 매크로는 QML에서 해당 포괄 타입을 사용할 수 없도록 선언합니다. 또한 사용자가 지정한 추가 QML 매크로를 활용하여, ‘ QQmlTypeNotAvailable ’라는 내부 더미 타입을 ‘ QML_FOREIGN()’ 타입으로 등록합니다.

일반적으로 모듈에서 내보내는 타입은 고정되어 있어야 합니다. 하지만 C++ 타입을 사용할 수 없는 경우, 최소한 해당 QML 타입 이름을 "예약"하고, 사용할 수 없는 타입을 사용하는 사용자에게 의미 있는 오류 메시지를 제공해야 합니다.

예시:

#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif

이렇게 하면 “Game” 유형을 사용하려고 시도하는 모든 QML에서 오류 메시지가 표시됩니다:

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

이 기법을 사용하면, 완전한 ` QObject` 클래스가 아닌 ` Q_GADGET ` 구조체만으로도 오류 메시지를 사용자 정의할 수 있습니다. ` QML_UNCREATABLE()`가 없더라도, `QML_UNAVAILABLE`은 완전히 알려지지 않은 유형에 대해 일반적으로 표시되는 "유형이 아닙니다"라는 오류 메시지보다 더 구체적인 오류 메시지를 제공합니다.

관련 항목: QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN().

QML_UNCREATABLE(reason)

포함된 타입을 QML에서 생성할 수 없음을 선언합니다. 이 설정은 해당 타입이 QML에서 QML_ELEMENT 또는 QML_NAMED_ELEMENT() 매크로를 통해 사용 가능한 경우 적용됩니다. QML에서 해당 타입을 생성하려는 시도가 감지되면 “ reason ” 오류 메시지가 출력됩니다.

일부 QML 유형은 암묵적으로 생성할 수 없으며, 특히 QML_ANONYMOUS 로 노출된 유형이나 QML_ELEMENT 또는 QML_NAMED_ELEMENT()로 노출된 네임스페이스가 이에 해당합니다.

타입이 QML_SINGLETON으로 선언된 싱글톤인 경우, QML_UNCREATABLE을 추가하면 QQmlEngine::setExternalSingletonInstance 을 사용하여 엔진에 해당 타입의 인스턴스가 명시적으로 설정될 것이라는 약속을 나타냅니다.

Qt 6.0부터는 이유를 지정하는 대신 ""를 사용하여 표준 메시지를 대신 사용할 수 있습니다.

QML_ELEMENT, QML_NAMED_ELEMENT() 및 QML_ANONYMOUS도 참조하십시오 .

QML_VALUE_TYPE(name)

name 를 이름으로 사용하여, 둘러싸고 있는 타입이나 네임스페이스를 QML에서 사용할 수 있도록 선언합니다. 해당 타입은 값 타입이어야 하며, 이름은 소문자로 지정해야 합니다.

class MyValueType
{
    Q_GADGET
    QML_VALUE_TYPE(myValueType)

    // ...
};

‘C++와 QML 간의 올바른 통합 방법 선택 ’ 및 ‘ QML_NAMED_ELEMENT ’항목도 참조하십시오 .