QQuickWidget Class
QQuickWidget クラスは、Qt Quick ユーザー・インターフェイスを表示するためのウィジェットを提供します。詳細...
ヘッダー | #include <QQuickWidget> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS QuickWidgets) target_link_libraries(mytarget PRIVATE Qt6::QuickWidgets) |
qmake: | QT += quickwidgets |
継承: | QWidget |
パブリックな型
enum | ResizeMode { SizeViewToRootObject, SizeRootObjectToView } |
enum | Status { Null, Ready, Loading, Error } |
プロパティ
- resizeMode : ResizeMode
- source : QUrl
- status : const Status
パブリック機能
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は、ビューとルートオブジェクトのサイジングも管理します。デフォルトでは、resizeMode はSizeViewToRootObject で、コンポーネントをロードし、ビューのサイズにリサイズします。また、resizeMode をSizeRootObjectToView に設定することもできます。この場合、ビューのサイズがルートオブジェクトのサイズに変更されます。
パフォーマンスに関する考慮事項
QQuickWidgetは、QQuickView とQWidget::createWindowContainer() を使用する代替手段です。スタック順序に関する制限は適用されないため、QQuickWidgetはより柔軟な代替手段となり、通常のウィジェットのように動作します。
しかし、上記の利点はパフォーマンスを犠牲にします:
- QQuickWindow やQQuickView とは異なり、QQuickWidgetは、オフスクリーン・カラーバッファ(典型的には2Dテクスチャ)をターゲットとするレンダーパスを少なくとも1回追加し、その後にテクスチャ・クワッドを描画します。これは、特にGPUのフラグメント処理に対する負荷の増加を意味します。
- QQuickWidgetを使用すると、すべてのプラットフォームでスレッド化されたレンダリングループが無効になります。これは、Animator クラスやvsync駆動アニメーションなど、スレッド化されたレンダリングの利点の一部が利用できなくなることを意味します。
注意: QQuickWidget上でwinId()を呼び出さないようにしてください。この関数はネイティブ・ウィンドウの作成をトリガーし、パフォーマンスの低下やレンダリングの不具合を引き起こします。QQuickWidgetの全体的な目的は、個別のネイティブ・ウィンドウを使用せずにクイック・シーンをレンダリングすることなので、QQuickWidgetをネイティブ・ウィジェットにすることは常に避けるべきです。
グラフィックスAPIサポート
QQuickWidgetは、software
バックエンドと同様に、Qt Quick でサポートされているすべての3DグラフィックスAPIで機能します。しかし、OpenVGなどの他のバックエンドは互換性がなく、QQuickWidgetを構築しようとすると問題が発生します。
プラットフォームのデフォルト・グラフィックスAPIのオーバーライドは、QQuickWindow およびQQuickView と同じ方法で行います。最初の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 を設定し、アルファチャンネルを要求し、setClearColor() を介して、Qt Quick Scenegraph のクリアカラーをQt::transparent に変更します。
タブキー処理
[TAB]
キーが押されると、QQuickWidget 内のアイテムにフォーカスが当たります。このアイテムが[TAB]
キーの押下を処理できる場合、フォーカスはアイテム内でそれに応じて変更され、そうでない場合、フォーカスチェーンの次のウィジェットがフォーカスを取得します。
C++ 型の属性を QML に公開する、Qt Quick ウィジェットの例、QQuickViewも参照してください 。
メンバ型ドキュメント
enum QQuickWidget::ResizeMode
この列挙型は、ビューのサイズを変更する方法を指定します。
定数 | 値 | 説明 |
---|---|---|
QQuickWidget::SizeViewToRootObject | 0 | ビューはQMLのルートアイテムのサイズを変更する。 |
QQuickWidget::SizeRootObjectToView | 1 | ビューは自動的にルートアイテムのサイズをビューのサイズに変更します。 |
enum QQuickWidget::Status
QQuickWidget のロード状態を指定する。
定数 | 値 | 説明 |
---|---|---|
QQuickWidget::Null | 0 | このQQuickWidget にはソースが設定されていません。 |
QQuickWidget::Ready | 1 | このQQuickWidget は、QML コンポーネントをロードして作成しました。 |
QQuickWidget::Loading | 2 | このQQuickWidget はネットワーク・データをロードしています。 |
QQuickWidget::Error | 3 | つ以上のエラーが発生しました。エラーのリストを取得するには、errors() を呼び出してください。 |
プロパティのドキュメント
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 コンポーネントがインスタンス化されます。
アクセス関数
[read-only]
status : const Status
コンポーネントの現在のstatus 。
アクセス関数:
QQuickWidget::Status | status() const |
通知シグナル:
void | statusChanged(QQuickWidget::Status status) |
メンバ関数ドキュメント
[explicit]
QQuickWidget::QQuickWidget(QWidget *parent = nullptr)
parent の子として、デフォルトの QML エンジンを持つ QQuickWidget を構築します。
parent のデフォルト値はnullptr
です。
QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)
与えられた QMLengine をparent の子として QQuickWidget を構築します。
注意: QQuickWidgetは与えられたengine オブジェクトの所有権を持ちません。エンジンを破棄するのは呼び出し側の責任です。もしengine がビューより先に削除された場合、status() はQQuickWidget::Error を返します。
[explicit]
QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)
デフォルトの QML エンジンと、与えられた QMLsource をparent の子として持つ 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)
再実装: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)
再実装:QWidget::focusInEvent(QFocusEvent *event)。
[override virtual protected]
bool QQuickWidget::focusNextPrevChild(bool next)
再インプリメント:QWidget::focusNextPrevChild(bool next).
[override virtual protected]
void QQuickWidget::focusOutEvent(QFocusEvent *event)
再実装: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
ルートオブジェクトの初期サイズを返す。
resizeMode がSizeRootObjectToView の場合、ルートオブジェクトはビューのサイズにリサイズされます。この関数は、サイズ変更前のルートオブジェクトのサイズを返します。
[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)
再実装:QWidget::mouseMoveEvent(QMouseEvent *event)。
[override virtual protected]
void QQuickWidget::mousePressEvent(QMouseEvent *e)
再実装:QWidget::mousePressEvent(QMouseEvent *event)。
[override virtual protected]
void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)
再実装:QWidget::mouseReleaseEvent(QMouseEvent *event)。
[override virtual protected]
void QQuickWidget::paintEvent(QPaintEvent *event)
再実装:QWidget::paintEvent(QPaintEvent *event)。
QQuickWindow *QQuickWidget::quickWindow() const
このウィジェットがQt Quick レンダリングを駆動するために使用する、オフスクリーンQQuickWindow を返します。これは、QQuickWidget によって現在公開されていないQQuickWindow API を使用したい場合に便利です。例えば、QQuickWindow::beforeRendering() シグナルに接続して、Qt Quick'自身のレンダリングの下にネイティブの OpenGL コンテンツを描画します。
警告: この関数の戻り値は注意して使用してください。特に、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)
color 。デフォルトでは不透明色です。
半透明のQQuickWidget を取得するには、color をQt::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 を返す。
注: プロパティ・ソースのゲッター関数。
setSource()も参照してください 。
[signal]
void QQuickWidget::statusChanged(QQuickWidget::Status status)
このシグナルは、コンポーネントの現在のstatus が変更されたときに発行される。
注: プロパティstatus に対するノーティファイアシグナル。
[override virtual protected]
void QQuickWidget::wheelEvent(QWheelEvent *e)
再実装:QWidget::wheelEvent(QWheelEvent *event)。
© 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.