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 がインスタンスを構築する際は、次の3つのステップで行われます。

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` を作成し、その太さを `bold` に設定してから、そのフォントを初期プロパティとして渡します。

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

コンポーネントのステータスが変更されるたびに発行されます。status は新しいステータスになります。