QQuickWidget Class

QQuickWidget クラスは、Qt Quick ユーザー・インターフェースを表示するためのウィジェットを提供します。詳細...

Header: #include <QQuickWidget>
CMake: find_package(Qt6 REQUIRED COMPONENTS QuickWidgets)
target_link_libraries(mytarget PRIVATE Qt6::QuickWidgets)
qmake: QT += quickwidgets
Inherits: QWidget

パブリックタイプ

enum ResizeMode { SizeViewToRootObject, SizeRootObjectToView }
enum Status { Null, Ready, Loading, Error }

プロパティ

パブリック関数

QQuickWidget(QWidget *parent = nullptr)
QQuickWidget(QQmlEngine *engine, QWidget *parent)
QQuickWidget(const QUrl &source, QWidget *parent = nullptr)
virtual ~QQuickWidget() override
QQmlEngine *engine() const
QList<QQmlError> errors() const
QSurfaceFormat format() const
QImage grabFramebuffer() const
QSize initialSize() const
QQuickWindow *quickWindow() const
QQuickWidget::ResizeMode resizeMode() const
QQmlContext *rootContext() const
QQuickItem *rootObject() const
void setClearColor(const QColor &color)
void setFormat(const QSurfaceFormat &format)
void setResizeMode(QQuickWidget::ResizeMode)
QUrl source() const
QQuickWidget::Status status() const

パブリックスロット

void setSource(const QUrl &url)

シグナル

void sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)
void statusChanged(QQuickWidget::Status status)

再実装された保護された関数

virtual void dragEnterEvent(QDragEnterEvent *e) override
virtual void dragLeaveEvent(QDragLeaveEvent *e) override
virtual void dragMoveEvent(QDragMoveEvent *e) override
virtual void dropEvent(QDropEvent *e) override
virtual bool event(QEvent *e) override
virtual void focusInEvent(QFocusEvent *event) override
virtual bool focusNextPrevChild(bool next) override
virtual void focusOutEvent(QFocusEvent *event) override
virtual void hideEvent(QHideEvent *) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void keyReleaseEvent(QKeyEvent *e) override
virtual void mouseDoubleClickEvent(QMouseEvent *e) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *event) override
virtual void showEvent(QShowEvent *) override
virtual void wheelEvent(QWheelEvent *e) override

詳しい説明

これはQQuickWindow の便利なラッパーで、メインソースファイルの URL を与えると、自動的に QML シーンをロードして表示します。あるいは、QQmlComponent を使って独自のオブジェクトをインスタンス化し、手動で設定した QQuickWidget に配置することもできます。

典型的な使い方

QQuickWidget *view = new QQuickWidget;
view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
view->show();

QQuickWidgetによるQMLのロードと実行に関連するエラーを受信するには、statusChanged() シグナルに接続し、QQuickWidget::Error を監視します。エラーは、QQuickWidget::errors()を介して利用可能です。

QQuickWidgetは、ビューとルートオブジェクトのサイジングも管理します。デフォルトでは、resizeModeSizeViewToRootObject で、コンポーネントをロードし、ビューのサイズにリサイズします。また、resizeModeSizeRootObjectToView に設定することもできます。この場合、ビューのサイズがルートオブジェクトのサイズに変更されます。

パフォーマンスに関する考慮事項

QQuickWidgetは、QQuickViewQWidget::createWindowContainer() を使用する代替手段です。スタック順序の制限が適用されないため、QQuickWidgetはより柔軟な代替手段となり、通常のウィジェットのように動作します。

しかし、上記の利点はパフォーマンスを犠牲にします:

  • QQuickWindowQQuickView とは異なり、QQuickWidgetは、画面外のカラーバッファ(通常は2Dテクスチャ)をターゲットとするレンダーパスを少なくとも1回追加し、その後にテクスチャクアッドを描画します。これは、特にGPUのフラグメント処理に対する負荷の増加を意味します。
  • QQuickWidgetを使用すると、すべてのプラットフォームでスレッド化されたレンダリングループが無効になります。これは、Animator クラスやvsync駆動アニメーションなど、スレッド化されたレンダリングの利点の一部が利用できなくなることを意味します。

注意: QQuickWidget上でwinId()を呼び出さないようにしてください。この関数はネイティブ・ウィンドウの作成をトリガーし、パフォーマンスの低下やレンダリングの不具合を引き起こします。QQuickWidgetの全体的な目的は、個別のネイティブ・ウィンドウを使用せずにクイック・シーンをレンダリングすることであるため、QQuickWidgetをネイティブ・ウィジェットにすることは常に避けるべきです。

グラフィックスAPIサポート

QQuickWidgetは、software バックエンドと同様に、Qt Quickでサポートされているすべての3DグラフィックスAPIで機能します。しかし、OpenVGなどの他のバックエンドは互換性がなく、QQuickWidgetを構築しようとすると問題が発生します。

プラットフォームのデフォルトのグラフィックAPIをオーバーライドするには、QQuickWindowQQuickView と同じ方法で行います。最初のQQuickWidgetを構築する前の早い段階でQQuickWindow::setGraphicsApi() を呼び出すか、QSG_RHI_BACKEND 環境変数を設定します。

注意: 1つのトップレベル・ウィンドウでは、1つのグラフィックAPIしかレンダリングに使用できません。例えば、Vulkanを使用するQQuickWidgetとQOpenGLWidget を同じトップレベルウィンドウのウィジェット階層に配置しようとすると、問題が発生し、ウィジェットの1つが期待通りにレンダリングされません。

シーングラフとコンテキストの永続性

QQuickWidget はQQuickWindow::isPersistentSceneGraph() をサポートしています。つまり、quickWindow() 関数から返されたウィンドウでQQuickWindow::setPersistentSceneGraph() を呼び出すことで、ウィジェットが非表示になるたびにシーングラフ・ノードと他の Qt Quick シーン関連リソースを解放するように、アプリケーションで決定することができます。デフォルトでは、QQuickWindow と同様に、永続性が有効になっています。

OpenGLで実行する場合、QQuickWindow 、OpenGLコンテキストの永続性も無効にできます。この設定は現在QQuickWidgetによって無視され、コンテキストは常に永続的です。したがって、OpenGLコンテキストは、ウィジェットを非表示にしても破棄されません。コンテキストが破棄されるのは、ウィジェットが破棄されたときか、ウィジェットが別のトップレベルウィジェットの子階層に再arentされたときだけです。しかし、アプリケーションによっては、特にQt QuickシーンでカスタムOpenGLレンダリングを実行するために独自のグラフィックスリソースを持っているアプリケーションでは、QQuickWidgetを別のウィンドウに移動するときにコンテキストが失われるのを処理する準備ができていない可能性があるため、後者を無効にしたい場合があります。そのようなアプリケーションは、QCoreApplication::AA_ShareOpenGLContexts属性を設定することができます。リソースの初期化とクリーンアップの詳細については、QOpenGLWidget ドキュメントを参照してください。

注意: QQuickWidgetは、QOpenGLWidget に比べて、内部OpenGLコンテキストのきめ細かな制御を提供しておらず、微妙な違いがあります。特に、永続的なシーングラフを無効にすると、QCoreApplication::AA_ShareOpenGLContextsの存在に関係なく、ウィンドウの変更時にコンテキストが破棄されます。

制限事項

QQuickWidgetの下に他のウィジェットを配置し、QQuickWidgetを透明にすることは、期待される結果につながりません。これは、実際には、QQuickWidgetは、他のすべての通常の非OpenGLウィジェットよりも先に描画されるため、シースルータイプのソリューションは実現不可能だからです。QQuickWidgetの上にウィジェットがあるような他のタイプのレイアウトは、期待通りに機能します。

どうしても必要な場合は、QQuickWidgetにQt::WA_AlwaysStackOnTop 属性を設定することで、この制限を克服することができます。しかし、これはスタック順序を壊すことに注意してください。例えば、QQuickWidgetの上に他のウィジェットを置くことができなくなるので、下に他のウィジェットが見える半透明のQQuickWidgetが必要な状況でのみ使用してください。

この制限は、同じウィンドウ内でQQuickWidgetの下に他のウィジェットがある場合にのみ適用されます。他のアプリケーションやデスクトップが背景に見える状態でウィンドウを半透明にするには、従来の方法で行います:トップレベルのウィンドウにQt::WA_TranslucentBackground を設定し、アルファチャンネルを要求し、Qt Quick Scenegraph のクリアカラーをsetClearColor() でQt::transparent に変更します。

タブキーの処理

[TAB] キーが押されると、QQuickWidget 内のアイテムにフォーカスが当たります。このアイテムが[TAB] キーの押下を処理できる場合、フォーカスはアイテム内でそれに応じて変更され、そうでない場合は、フォーカスチェーン内の次のウィジェットがフォーカスを取得します。

C++ 型の属性を QML に公開する」、「Qt クイックウィジェットの例」、「QQuickView」も参照してください

メンバ型ドキュメント

enum QQuickWidget::ResizeMode

この列挙型は、ビューのリサイズ方法を指定します。

定数説明
QQuickWidget::SizeViewToRootObject0ビューはQMLのルートアイテムのサイズを変更します。
QQuickWidget::SizeRootObjectToView1ビューは自動的にルートアイテムのサイズをビューのサイズに変更する。

enum QQuickWidget::Status

QQuickWidget のロード状態を指定します。

定数説明
QQuickWidget::Null0このQQuickWidget にはソースが設定されていません。
QQuickWidget::Ready1このQQuickWidget は、QML コンポーネントをロードして作成しました。
QQuickWidget::Loading2このQQuickWidget はネットワーク・データをロードしています。
QQuickWidget::Error3つ以上のエラーが発生しました。エラーのリストを取得するには、errors() を呼び出してください。

プロパティ Documentation

resizeMode : ResizeMode

ビューがウィンドウの内容をリサイズするかどうかを指定します。

このプロパティがSizeViewToRootObject に設定されている場合(デフォルト)、ビューは QML 内のルート項目のサイズにリサイズされる。

このプロパティがSizeRootObjectToView に設定されている場合、ビューは自動的にルートアイテムのサイズをビューのサイズに変更する。

このプロパティに関係なく、ビューの sizeHint はルートアイテムの初期サイズとなります。ただし、QMLは動的にロードされるため、そのサイズは変更される可能性があることに注意して下さい。

アクセス関数:

QQuickWidget::ResizeMode resizeMode() const
void setResizeMode(QQuickWidget::ResizeMode)

initialSize()も参照

source : QUrl

このプロパティはQMLコンポーネントのソースのURLを保持します。

特に、ローカルファイルシステムからファイルを読み込む場合にはQUrl::fromLocalFile() を使用してください。

注意: ソースの URL を設定すると、URL が現在の値から変更されていなくても、QML コンポーネントはインスタンス化されます。

アクセス関数:

QUrl source() const
void setSource(const QUrl &url)

[read-only] status : const Status

コンポーネントの現在のstatus

アクセス関数:

QQuickWidget::Status status() const

通知シグナル:

void statusChanged(QQuickWidget::Status status)

メンバー関数ドキュメント

[explicit] QQuickWidget::QQuickWidget(QWidget *parent = nullptr)

デフォルトのQMLエンジンを持つQQuickWidgetをparent の子として構築します。

parent のデフォルト値はnullptr です。

QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)

parent の子として、指定された QMLengine を持つ QQuickWidget を構築します。

注意: QQuickWidgetは与えられたengine オブジェクトの所有権を持ちません。エンジンを破棄するのは呼び出し側の責任です。ビューの前にengine が削除された場合、status() はQQuickWidget::Error を返します。

[explicit] QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)

デフォルトの QML エンジンと、与えられた QMLsourceparent の子として持つ QQuickWidget を構築します。

parent のデフォルト値はnullptr です。

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

QQuickWidget を破棄します。

[override virtual protected] void QQuickWidget::dragEnterEvent(QDragEnterEvent *e)

再インプリメント:QWidget::dragEnterEvent(QDragEnterEvent *event)。

[override virtual protected] void QQuickWidget::dragLeaveEvent(QDragLeaveEvent *e)

再インプリメント:QWidget::dragLeaveEvent(QDragLeaveEvent *event)。

[override virtual protected] void QQuickWidget::dragMoveEvent(QDragMoveEvent *e)

再リンプルメント: (QDragLeaveEvent *event):QWidget::dragMoveEvent(QDragMoveEvent *event)。

[override virtual protected] void QQuickWidget::dropEvent(QDropEvent *e)

再実装:QWidget::dropEvent(QDropEvent *event)。

QQmlEngine *QQuickWidget::engine() const

QML コンポーネントのインスタンス化に使用するQQmlEngine へのポインタを返します。

QList<QQmlError> QQuickWidget::errors() const

最後のコンパイルまたは作成時に発生したエラーのリストを返します。ステータスがError でない場合、空のリストが返されます。

statusも参照してください

[override virtual protected] bool QQuickWidget::event(QEvent *e)

再インプリメント:QWidget::event(QEvent *event)。

[override virtual protected] void QQuickWidget::focusInEvent(QFocusEvent *event)

再リンプルメント: (QEvent *event):QWidget::focusInEvent(QFocusEvent *event)。

[override virtual protected] bool QQuickWidget::focusNextPrevChild(bool next)

再リプルメント: (QFocusEvent *event):QWidget::focusNextPrevChild(bool next).

[override virtual protected] void QQuickWidget::focusOutEvent(QFocusEvent *event)

再リンプルメント: (bool next):QWidget::focusOutEvent(QFocusEvent *event)。

QSurfaceFormat QQuickWidget::format() const

実際の表面フォーマットを返します。

ウィジェットがまだ表示されていない場合は、要求されたフォーマットが返されます。

setFormat()も参照してください

QImage QQuickWidget::grabFramebuffer() const

フレームをレンダリングし、画像に読み戻します。

注意: これは高価な操作になる可能性があります。

[override virtual protected] void QQuickWidget::hideEvent(QHideEvent *)

再インプリメントです:QWidget::hideEvent(QHideEvent *event)。

QSize QQuickWidget::initialSize() const

ルートオブジェクトの初期サイズを返します。

resizeModeSizeRootObjectToView の場合、ルートオブジェクトはビューのサイズにリサイズされます。この関数は、サイズ変更前のルートオブジェクトのサイズを返します。

[override virtual protected] void QQuickWidget::keyPressEvent(QKeyEvent *e)

再実装:QWidget::keyPressEvent(QKeyEvent *event)。

[override virtual protected] void QQuickWidget::keyReleaseEvent(QKeyEvent *e)

再インプリメント:QWidget::keyReleaseEvent(QKeyEvent *event)。

[override virtual protected] void QQuickWidget::mouseDoubleClickEvent(QMouseEvent *e)

再リンプルメント:QWidget::mouseDoubleClickEvent(QMouseEvent *event)。

[override virtual protected] void QQuickWidget::mouseMoveEvent(QMouseEvent *e)

再リンプルメント: (QMouseEvent *event)QWidget::mouseMoveEvent(QMouseEvent *event)。

[override virtual protected] void QQuickWidget::mousePressEvent(QMouseEvent *e)

再リンプルメント: (QMouseEvent *event)QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)

再リンプルメント: (QMouseEvent *event)QWidget::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::paintEvent(QPaintEvent *event)

再リンプルメント: (QMouseEvent *event):QWidget::paintEvent(QPaintEvent *event)。

QQuickWindow *QQuickWidget::quickWindow() const

このウィジェットが Qt Quick レンダリングを駆動するために使用するオフスクリーンQQuickWindow を返します。QQuickWindow QQuickWidget例えば、Qt Quick 自身のレンダリングの下にネイティブの OpenGL コンテンツを描画するためにQQuickWindow::beforeRendering() シグナルに接続するなどです。

警告 この関数の戻り値は注意して使用してください。特に、QQuickWindow を決して表示しようとしないでください。また、他のQWindow-only API を使用する際には十分注意してください。

警告 オフスクリーンウィンドウは、特にウィジェットが別のQQuickWindow に移動されたときに、QQuickWidget のライフタイム中に削除(および再作成)される可能性があります。ウィンドウがいつ置き換えられたかを知る必要がある場合は、そのdestroyed() シグナルに接続してください。

QQmlContext *QQuickWidget::rootContext() const

この関数はコンテキスト階層のルートを返します。各QMLコンポーネントはQQmlContext の中にインスタンス化されます。QQmlContext はQMLコンポーネントにデータを渡すために不可欠です。QMLでは、コンテキストは階層的に配置され、この階層はQQmlEngine によって管理されます。

QQuickItem *QQuickWidget::rootObject() const

ビューのルートitem を返します。setSource() が呼び出されていない場合、壊れたQtQuick コードで呼び出された場合、あるいはQtQuick のコンテンツが作成されている場合には null になることがあります。

[signal] void QQuickWidget::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

このシグナルは、シーングラフの初期化中にerror が発生したときに発行される。

アプリケーションは、OpenGLコンテキストの作成失敗のようなエラーをカスタム方法で処理したい場合、このシグナルに接続する必要があります。スロットがシグナルに接続されていない場合、動作は異なります:Quickはmessage を表示するか、メッセージボックスを表示し、アプリケーションを終了します。

このシグナルはGUIスレッドから発行されます。

QQuickWindow::sceneGraphError()も参照してください

void QQuickWidget::setClearColor(const QColor &color)

clearcolor を設定します。デフォルトでは不透明色です。

半透明のQQuickWidget を取得するには、colorQt::transparent に設定してこの関数を呼び出し、Qt::WA_TranslucentBackground ウィジェット属性をトップレベル・ウィンドウに設定し、setFormat() でアルファ・チャネルを要求します。

QQuickWindow::setColor()も参照してください

void QQuickWidget::setFormat(const QSurfaceFormat &format)

このウィジェットが使用するコンテキストとオフスクリーンサーフェスのサーフェスformat を設定します。

与えられた OpenGL バージョンまたはプロファイルのコンテキストを要求する必要があるときに、この関数を呼び出します。深度、ステンシル、アルファバッファのサイズは自動的に処理されるので、明示的に要求する必要はありません。

QWindow::setFormat(),QWindow::format(),format()も参照

[slot] void QQuickWidget::setSource(const QUrl &url)

ソースをurl に設定し、QML コンポーネントをロードしてインスタンス化します。

特に、ローカルファイルシステムからファイルをロードする場合はQUrl::fromLocalFile() を使用する。

同じ URL でこのメソッドを複数回呼び出すと、QML コンポーネントは再インスタンス化されます。

注: プロパティsource のセッター関数。

source()も参照

[override virtual protected] void QQuickWidget::showEvent(QShowEvent *)

再インプリメント:QWidget::showEvent(QShowEvent *event)。

QUrl QQuickWidget::source() const

設定されている場合、ソース URL を返す。

備考: プロパティ source のゲッター関数。

setSource()も参照

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

このシグナルは、コンポーネントの現在のstatus が変更されたときに発行されます。

注: プロパティstatus に対するノーティファイアシグナル。

[override virtual protected] void QQuickWidget::wheelEvent(QWheelEvent *e)

再インプリメント:QWidget::wheelEvent(QWheelEvent *event)。

本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。