QQmlComponent Class

멤버 함수 설명서

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

데이터가 없는 QQmlComponent를 생성하고, 지정된 engine 및 parent 를 전달합니다. setData()를 사용하여 데이터를 설정합니다.

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

주어진 ` fileName `를 기반으로 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`를 전달합니다.

loadUrl()도 참조하십시오 .

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

주어진 ` url `를 기반으로 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`을 전달합니다.

제공된 URL이 완전하고 정확한지 확인하십시오. 특히, 로컬 파일 시스템에서 파일을 불러올 때는 QUrl::fromLocalFile()을 사용하십시오.

상대 경로는 QQmlEngine::baseUrl()을 기준으로 해석되며, 별도로 지정되지 않는 한 이는 현재 작업 디렉터리입니다.

loadUrl()도 참조하십시오 .

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

주어진 ` fileName `를 기반으로 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`를 전달합니다. ` mode `가 ` Asynchronous`인 경우, 컴포넌트는 비동기적으로 로드 및 컴파일됩니다.

loadUrl()도 참조하십시오 .

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

주어진 ` url `를 기반으로 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`를 전달합니다. ` mode `가 ` Asynchronous`인 경우, 컴포넌트는 비동기적으로 로드 및 컴파일됩니다.

제공된 URL이 완전하고 정확한지 확인하십시오. 특히, 로컬 파일 시스템에서 파일을 불러올 때는 QUrl::fromLocalFile()을 사용하십시오.

상대 경로는 QQmlEngine::baseUrl()을 기준으로 해결되며, 별도로 지정되지 않는 한 이는 현재 작업 디렉터리입니다.

loadUrl()도 참조하십시오 .

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

주어진 ` uri ` 및 ` typeName `을 사용하여 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`을 전달합니다. 가능한 경우, 컴포넌트는 동기식으로 로드됩니다.

이 함수는 Qt 6.5에서 도입되었습니다.

loadFromModule()도 참조하십시오 .

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

주어진 ` uri ` 및 ` typeName `을 사용하여 `QQmlComponent`를 생성하고, 지정된 ` parent ` 및 ` engine`을 전달합니다. ` mode `가 ` Asynchronous`인 경우, 컴포넌트는 비동기적으로 로드 및 컴파일됩니다.

이 함수는 Qt 6.5에서 도입되었습니다.

loadFromModule()도 참조하십시오 .

[override virtual noexcept] QQmlComponent::~QQmlComponent()

QQmlComponent 를 파괴하라.

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *context)

지정된 ` context` 내에서 이 컴포넌트의 객체 인스턴스를 생성합니다. 생성 실패 시 ` nullptr `를 반환합니다.

QQmlComponent 가 인스턴스를 생성할 때는 다음 세 단계로 진행됩니다:

1. 객체 계층 구조가 생성되고 상수 값이 할당됩니다.
2. 속성 바인딩이 처음 평가됩니다.
3. 해당되는 경우, 객체에 대해 ` QQmlParserStatus::componentComplete()`가 호출됩니다.

QQmlComponent::beginCreate()는 1단계만 수행한다는 점에서 QQmlComponent::create()과 다릅니다. 2단계와 3단계를 완료하려면 QQmlComponent::completeCreate()를 호출해야 합니다.

이 중단점은 부착된 속성을 사용하여 인스턴스화된 컴포넌트에 정보를 전달할 때 유용할 수 있는데, 속성 바인딩이 적용되기 전에 초기 값을 구성할 수 있게 해주기 때문입니다.

반환된 객체 인스턴스의 소유권은 호출자에게 이전됩니다.

completeCreate() 및 QQmlEngine::ObjectOwnership도 참조하십시오 .

[virtual] void QQmlComponent::completeCreate()

이 메서드는 컴포넌트 인스턴스 생성에 대한 정교한 제어를 제공합니다. 일반적으로 프로그래머는 QQmlComponent::create()를 사용하여 컴포넌트를 생성해야 합니다.

이 함수는 QQmlComponent::beginCreate()로 시작된 컴포넌트 생성을 완료하며, 반드시 그 후에 호출되어야 합니다.

beginCreate()도 참조하십시오 .

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

지정된 context 내에서 이 컴포넌트를 사용하여 객체 인스턴스를 생성합니다. 생성 실패 시 nullptr 를 반환합니다.

context 가 nullptr (기본값)인 경우, 엔진의 root context 에서 인스턴스를 생성합니다.

반환된 객체 인스턴스의 소유권은 호출자에게 이전됩니다.

이 컴포넌트에서 생성되는 객체가 비주얼 항목인 경우, 비주얼 부모가 있어야 하며, 이는 QQuickItem::setParentItem()를 호출하여 설정할 수 있습니다. 자세한 내용은 Qt Quick 의 ‘개념 - 비주얼 부모’를 참조하십시오.

QQmlEngine::ObjectOwnership도 참조하십시오 .

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

제공된 ` incubator`을 사용하여 이 컴포넌트로부터 객체 인스턴스를 생성합니다. ` context `은 객체 인스턴스를 생성할 컨텍스트를 지정합니다.

context 가 nullptr (기본값)인 경우, 엔진의 root context 에서 인스턴스가 생성됩니다.

forContext 이 객체 생성이 의존하는 컨텍스트를 지정합니다. forContext 이 비동기적으로 생성되고 있으며, QQmlIncubator::IncubationMode 이 QQmlIncubator::AsynchronousIfNested 인 경우, 이 객체도 비동기적으로 생성됩니다. forContext 이 nullptr (기본값)인 경우, context 가 이 결정에 사용됩니다.

생성된 객체와 그 생성 상태는 incubator 를 통해 확인할 수 있습니다.

QQmlIncubator도 참조하십시오 .

QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

지정된 ` context` 내에서 이 컴포넌트의 객체 인스턴스를 생성하고, ` initialProperties`를 사용하여 최상위 속성을 초기화합니다.

initialProperties 중 설정할 수 없는 항목이 있으면 경고가 발생합니다. 필수 속성 중 설정되지 않은 것이 있으면 객체 생성이 실패하고 nullptr 를 반환하며, 이 경우 isError()는 true 를 반환합니다.

context 가 nullptr (기본값)인 경우, 엔진의 root context 에 인스턴스가 생성됩니다.

반환된 객체 인스턴스의 소유권은 호출자에게 이전됩니다.

QQmlComponent::create도 참조하십시오 .

QQmlContext *QQmlComponent::creationContext() const

해당 컴포넌트가 생성된 QQmlContext 를 반환합니다. 이는 QML에서 직접 생성된 컴포넌트에만 적용됩니다.

QQmlEngine *QQmlComponent::engine() const

이 컴포넌트의 ` QQmlEngine `를 반환합니다.

QList<QQmlError> QQmlComponent::errors() const

마지막 컴파일 또는 생성 작업 중에 발생한 오류 목록을 반환합니다. ` isError()`가 설정되어 있지 않으면 빈 목록이 반환됩니다.

[since 6.5] bool QQmlComponent::isBound() const

해당 컴포넌트가 ` pragma ComponentBehavior: Bound`를 지정하는 QML 파일에서 생성된 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.

이 함수는 Qt 6.5에서 도입되었습니다.

bool QQmlComponent::isError() const

status() == QQmlComponent::Error 인 경우 true를 반환합니다.

bool QQmlComponent::isLoading() const

status() == QQmlComponent::Loading 일 경우 true를 반환합니다.

bool QQmlComponent::isNull() const

status() == QQmlComponent::Null 일 때 true를 반환합니다.

bool QQmlComponent::isReady() const

status() == QQmlComponent::Ready 일 때 true를 반환합니다.

[slot, since 6.5] void QQmlComponent::loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)

모듈 uri 에서 typeName 에 대한 QQmlComponent 를 불러옵니다. 타입이 QML 파일을 통해 구현된 경우, mode 를 사용하여 이를 불러옵니다. C++로 구현된 타입은 항상 동기식으로 불러옵니다.

QQmlEngine engine;
QQmlComponent component(&engine);
component.loadFromModule("QtQuick", "Item");
// once the component is ready
std::unique_ptr<QObject> item(component.create());
Q_ASSERT(item->metaObject() == &QQuickItem::staticMetaObject);

이 함수는 Qt 6.5에서 도입되었습니다.

loadUrl()도 참조하십시오 .

[slot] void QQmlComponent::loadUrl(const QUrl &url)

제공된 url 에서 QQmlComponent 를 불러오세요.

제공된 URL이 완전하고 정확한지 확인하십시오. 특히, 로컬 파일 시스템에서 파일을 불러올 때는 QUrl::fromLocalFile()을 사용하십시오.

상대 경로는 QQmlEngine::baseUrl()을 기준으로 해결되며, 별도로 지정되지 않는 한 이는 현재 작업 디렉터리입니다.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url) { receiver->loadUrl(url); });

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

제공된 url 에서 QQmlComponent 를 불러오십시오. mode 가 Asynchronous 인 경우, 컴포넌트는 비동기적으로 불러와지고 컴파일됩니다.

제공된 URL이 완전하고 정확한지 확인하십시오. 특히, 로컬 파일 시스템에서 파일을 불러올 때는 QUrl::fromLocalFile()을 사용하십시오.

상대 경로는 QQmlEngine::baseUrl()을 기준으로 해결되며, 별도로 지정되지 않는 한 이는 현재 작업 디렉터리입니다.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url, QQmlComponent::CompilationMode mode) { receiver->loadUrl(url, mode); });

[signal] void QQmlComponent::progressChanged(qreal progress)

컴포넌트의 로딩 진행 상황이 변경될 때마다 발생합니다. ` progress `는 0.0(아직 로딩되지 않음)에서 1.0(완료됨) 사이의 현재 진행 상황을 나타냅니다.

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

QQmlComponent 가 지정된 QML data 을 사용하도록 설정합니다. url 가 제공된 경우, 이를 사용하여 컴포넌트 이름을 설정하고 이 컴포넌트가 해결하는 항목에 대한 기본 경로를 제공합니다. 컴포넌트는 동기식으로 로드 및 컴파일됩니다.

void QQmlComponent::setInitialProperties(QObject *object, const QVariantMap &properties)

QQmlComponent 에서 생성된 object 의 최상위 properties 를 설정합니다.

이 메서드는 컴포넌트 인스턴스 생성에 대한 고급 제어 기능을 제공합니다. 일반적으로 프로그래머는 QQmlComponent::createWithInitialProperties 를 사용하여 컴포넌트에서 객체 인스턴스를 생성해야 합니다.

이 메서드는 ` beginCreate ` 호출 후, ` completeCreate ` 호출 전에 사용해야 합니다. 제공된 속성이 존재하지 않으면 경고가 발생합니다.

이 메서드는 초기 중첩 속성을 직접 설정하는 것을 허용하지 않습니다. 대신, 중첩 속성이 있는 값 유형 속성의 초기 값을 설정하려면 해당 값 유형을 생성하고, 중첩 속성을 할당한 다음, 생성될 객체의 초기 속성으로 해당 값 유형을 전달하면 됩니다.

예를 들어, `fond.bold`를 설정하려면 ` QFont`를 생성하고, 그 `weight`를 `bold`로 설정한 다음, 해당 폰트를 초기 속성으로 전달하면 됩니다.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

컴포넌트의 상태가 변경될 때마다 발생합니다. ` status `는 새로운 상태가 됩니다.