グラフィックス・ビュー・フレームワーク

Graphics Viewは、多数のカスタムメイドの2Dグラフィカル・アイテムを管理し、相互作用するためのサーフェスと、アイテムを視覚化するためのビュー・ウィジェットを提供し、ズームと回転をサポートする。

フレームワークには、シーン上のアイテムの正確な倍精度インタラクション機能を可能にするイベント伝搬アーキテクチャが含まれています。アイテムは、キー・イベント、マウス・プレス、移動、リリース、ダブル・クリック・イベントを扱うことができ、マウスの動きを追跡することもできます。

Graphics Viewは、BSP（Binary Space Partitioning）ツリーを使用して、非常に高速なアイテムの発見を実現し、その結果、数百万のアイテムがあっても、大規模なシーンをリアルタイムで視覚化することができます。

Graphics View は Qt 4.2 で導入され、前身の QCanvas を置き換えた。

グラフィックス・ビューのアーキテクチャ

Graphics Viewは、InterViewの便利なクラスQTableView 、QTreeView 、QListView のように、モデルビュープログラミングにアイテムベースのアプローチを提供します。複数のビューが1つのシーンを観察することができ、シーンには様々な幾何学的形状のアイテムが含まれます。

シーン

QGraphicsScene は、グラフィックスビューのシーンを提供します。シーンは以下の責任を持つ：

• 多数のアイテムを管理するための高速インターフェースを提供する。
• 各アイテムへのイベントの伝搬
• 選択とフォーカスの処理など、アイテムの状態を管理する。
• 非変形レンダリング機能の提供（主に印刷用

シーンは、QGraphicsItem オブジェクトのコンテナとして機能する。アイテムは、QGraphicsScene::addItem() を呼び出すことでシーンに追加され、多くのアイテム発見関数のいずれかを呼び出すことで取得されます。QGraphicsScene::items()とそのオーバーロードは、点、矩形、多角形、または一般的なベクトルパスに含まれる、または交差するすべてのアイテムを返します。QGraphicsScene::itemAt() は、特定の点の最上位の項目を返します。すべてのアイテム検出関数は、アイテムを積み重ね順に返します（つまり、最初に返されたアイテムが最上位で、最後に返されたアイテムが最下位です）。

QGraphicsScene scene;
QGraphicsRectItem *rect = scene.addRect(QRectF(0, 0, 100, 100));

QGraphicsItem *item = scene.itemAt(50, 50, QTransform());

QGraphicsSceneイベントプロパゲーションアーキテクチャは、アイテムに配信するシーンイベントをスケジュールし、アイテム間のプロパゲーションも管理します。シーンがある位置でマウスを押すイベントを受け取ると、シーンはその位置にあるアイテムにイベントを渡す。

QGraphicsScene また、アイテムの選択やフォーカスなど、特定のアイテムの状態も管理します。シーン上のアイテムを選択するには、任意のシェイプを渡して () を呼び出します。この機能は、 のラバーバンド選択の基礎としても使用されます。現在選択されているすべてのアイテムのリストを取得するには、 () を呼び出します。 が扱うもう1つの状態は、アイテムにキーボード入力フォーカスがあるかどうかです。アイテムにフォーカスを設定するには、 () または () を、現在のフォーカス・アイテムを取得するには () を呼び出します。QGraphicsScene::setSelectionArea QGraphicsView QGraphicsScene::selectedItems QGraphicsScene QGraphicsScene::setFocusItem QGraphicsItem::setFocus QGraphicsScene::focusItem

最後に、QGraphicsScene では、QGraphicsScene::render() 関数を使用して、シーンの一部をペイントデバイスにレンダリングできます。これについては、このドキュメントで後述する「印刷」のセクションで詳しく説明します。

ビュー

QGraphicsView は、シーンの内容を視覚化するビューウィジェットを提供します。同じデータセットに複数のビューポートを提供するために、同じシーンに複数のビューをアタッチすることができます。ビュー・ウィジェットはスクロール・エリアであり、大きなシーンをナビゲートするためのスクロール・バーを提供します。OpenGLサポートを有効にするには、 () を呼び出して、 をビューポートとして設定します。QGraphicsView::setViewport QOpenGLWidget

QGraphicsScene scene;
myPopulateScene(&scene);
QGraphicsView view(&scene);
view.show();

ビューは、キーボードとマウスからの入力イベントを受け取り、これらをシーンイベントに変換し（必要に応じて、使用される座標をシーン座標に変換する）、ビジュアライズされたシーンにイベントを送信します。

その変換行列、QGraphicsView::transform()を使用して、ビューはシーンの座標系を変換することができます。これにより、ズームや回転などの高度なナビゲーション機能が可能になります。便利なように、QGraphicsView は、ビューとシーンの座標を変換する関数（QGraphicsView::mapToScene()、QGraphicsView::mapFromScene()）も提供しています。

アイテム

QGraphicsItem は、シーン内のグラフィカルアイテムの基本クラスです。Graphics View は、矩形 ( )、楕円 ( )、テキスト・アイテム ( ) など、典型的な形状のためのいくつかの標準アイテムを提供しますが、最も強力な 機能は、カスタム・アイテムを記述したときに利用できます。特に、 は以下の機能をサポートしています：QGraphicsRectItemQGraphicsEllipseItemQGraphicsTextItem QGraphicsItem QGraphicsItem

• マウスの押下、移動、リリース、ダブルクリックイベント、マウスホバーイベント、ホイールイベント、コンテキストメニューイベント。
• キーボード入力フォーカス、キーイベント
• ドラッグ＆ドロップ
• 親子関係によるグループ化と、親子関係によるグループ化QGraphicsItemGroup
• 衝突検出

アイテムはローカル座標系で生活し、QGraphicsView のように、アイテムとシーン間、アイテムからアイテムへの座標マッピングのための多くの機能も提供します。また、QGraphicsView のように、QGraphicsItem::transform() という行列を使って座標系を変換することもできます。これは、個々のアイテムの回転やスケーリングに便利です。

アイテムは他のアイテム（子）を含むことができます。親アイテムの変換は、すべての子アイテムに継承されます。しかし、アイテムの累積トランスフォームに関係なく、すべての関数（例えば、QGraphicsItem::contains(),QGraphicsItem::boundingRect(), QGraphicsItem::collidesWith() ）はローカル座標で動作します。

QGraphicsItem は、 () 関数と QGraphicsItem::collidesWith() を通して衝突検出をサポートしており、これらはどちらも仮想関数です。アイテムの形状を () からローカル座標 として返すことで、 がすべての衝突検出を処理してくれます。しかし、独自の衝突検出を行いたい場合は、QGraphicsItem::collidesWith()を再実装することができます。QGraphicsItem::shape QGraphicsItem::shape QPainterPath QGraphicsItem

グラフィックス・ビュー・フレームワークのクラス

これらのクラスは、インタラクティブなアプリケーションを作成するためのフレームワークを提供します。

グラフィックス・ビューの座標系

シーン上のアイテムの位置とジオメトリは、x 座標と y 座標の 2 つの数値のセットで表されます。変換されていないビューを使用してシーンを観察する場合、シーン上の1単位は画面上の1ピクセルで表されます。

グラフィックスビューでは、3つの有効な座標系があります：アイテム座標、シーン座標、ビュー座標です。実装を簡単にするために、Graphics View は 3 つの座標系間のマッピングを可能にする便利な関数を提供しています。

レンダリング時、Graphics View のシーン座標はQPainter の論理座標に対応し、ビュー座標はデバイス座標と同じです。座標系の説明では、論理座標とデバイス座標の関係について説明しています。

アイテム座標

アイテムはそれ自身のローカル座標系に属します。その座標は通常、中心点 (0, 0) を中心とし、これはすべての変換の中心でもあります。アイテム座標系の幾何プリミティブは、しばしばアイテム点、アイテム線、アイテム矩形と呼ばれます。

カ ス タ ム ア イ テ ム を作成す る 際に気にす る 必要があ る のは、 ア イ テ ム座標だけです。QGraphicsScene とQGraphicsView が、 すべての変換を実行 し ます。これにより、カスタムアイテムの実装が非常に簡単になります。例えば、マウスが押されたり、ドラッグが入力されたりするイベントを受け取ると、そのイベントの位置がアイテム座標で与えられます。QGraphicsItem::contains() 仮想関数は、あるポイントがアイテムの内側にある場合はtrue を返し、そうでない場合は false を返します。同様に、アイテムの外接矩形と形状はアイテム座標で指定します。

アイテムの位置は、親の座標系におけるアイテムの中心点の座標です。この意味で、シーンはすべての親のないアイテムの「親」とみなされる。トップレベルアイテムの位置はシーン座標である。

子の座標は親の座標からの相対座標である。子座標が変換されていない場合、子座標と親座標の差は、親座標のアイテム間の距離と同じになる。例えば変換されていない子アイテムが親の中心点に正確に位置する場合、2つのアイテムの座標系は同一になります。しかし、子の位置が(10, 0)であれば、子の(0, 10)点は親の(10, 10)点に対応する。

アイテムの位置と変換は親に対する相対的なものなので、子アイテムの座標は親の変換の影響を受けませんが、親の変換は暗黙のうちに子を変換します。上の例では、親が回転、拡大縮小されても、子の (0, 10) ポイントは親の (10, 10) ポイントに対応します。しかし、シーンに対して、子は親の変形と位置に従う。親が(2x, 2x)にスケールされた場合、子の位置はシーン座標(20, 0)になり、その(10, 0)点はシーン上の(40, 0)点に対応します。

QGraphicsItem::pos() は数少ない例外ですが、QGraphicsItem の関数は、アイテムやその親のトランスフォームに関係なく、アイテムの座標で動作します。たとえば、アイテムの外接矩形（つまりQGraphicsItem::boundingRect() ）は、常にアイテム座標で与えられます。

シーン座標

シーンは、そのすべてのアイテムの基本座標系を表します。シーン座標系は、各トップレベルアイテムの位置を記述し、また、ビューからシーンに配信されるすべてのシーンイベントの基礎を形成する。シーン上の各アイテムは、そのローカルアイテムposと外接矩形に加えて、シーン位置と外接矩形 (QGraphicsItem::scenePos(),QGraphicsItem::sceneBoundingRect()) を持つ。シーン位置は、シーン座標におけるアイテムの位置を記述し、そのシーン境界矩形は、QGraphicsScene がシーンのどの領域が変更されたかを決定する方法の基礎を形成します。シーンの変更は、QGraphicsScene::changed （）シグナルを通して伝えられ、引数はシーンの矩形のリストです。

ビュー座標

ビュー座標はウィジェットの座標です。ビュー座標の各単位は1ピクセルに対応します。この座標系が特別なのは、ウィジェット、つまりビューポートからの相対座標であり、観察されるシーンの影響を受けないことです。QGraphicsView'のビューポートの左上隅は常に(0, 0)で、右下隅は常に(ビューポートの幅, ビューポートの高さ)です。すべてのマウスイベントとドラッグ＆ドロップイベントは、もともとビュー座標として受信され、アイテムと対話するために、これらの座標をシーンにマッピングする必要があります。

座標マッピング

シーン内のアイテムを扱うとき、シーンからアイテムへ、アイテムからアイテムへ、またはビューからシーンへ、座標や任意のシェイプをマッピングすると便利なことがよくあります。例えば、QGraphicsView'のビューポートでマウスをクリックすると、QGraphicsView::mapToScene()の後にQGraphicsScene::itemAt()を呼び出すことで、カーソルの下にどのアイテムがあるかをシーンに問い合わせることができます。アイテムがビューポートのどこにあるかを知りたい場合は、アイテムに対してQGraphicsItem::mapToScene() を呼び出し、次にビューに対してQGraphicsView::mapFromScene() を呼び出します。最後に、どのアイテムがビュー楕円の内側にあるかを知りたい場合は、QPainterPath を mapToScene() に渡し、マップされたパスをQGraphicsScene::items() に渡します。

QGraphicsItem::mapToScene() やQGraphicsItem::mapFromScene() を呼び出すことで、アイテムのシーンとの間で座標や図形をマッピングできます。また、QGraphicsItem::mapToParent() とQGraphicsItem::mapFromParent() を呼び出すとアイテムの親アイテムに、QGraphicsItem::mapToItem() とQGraphicsItem::mapFromItem() を呼び出すとアイテム間にマッピングできます。すべてのマッピング関数は、点、矩形、多角形、パスの両方をマッピングできます。

同じマッピング関数がビューでも利用でき、シーンへのマッピングとシーンからのマッピングが可能です。QGraphicsView::mapFromScene(およびQGraphicsView::mapToScene （）。ビューからアイテムにマッピングするには、まずシーンにマッピングし、次にシーンからアイテムにマッピングします。

主な機能

ズームと回転

QGraphicsView QGraphicsView::setMatrix()は、 と同じアフィン変換をサポートしています。ビューに変換を適用することで、ズームや回転などの一般的なナビゲーション機能のサポートを簡単に追加することができます。QPainter

以下は、QGraphicsView のサブクラスにズームと回転スロットを実装する方法の例です：

class View : public QGraphicsView
{
Q_OBJECT
    ...
public slots:
    void zoomIn() { scale(1.2, 1.2); }
    void zoomOut() { scale(1 / 1.2, 1 / 1.2); }
    void rotateLeft() { rotate(-10); }
    void rotateRight() { rotate(10); }
    ...
};

スロットは、autoRepeat を有効にして、QToolButtons に接続することができます。

QGraphicsView は、ビューを変換するときにビューの中心を揃えたままにします。

基本的なズーム機能の実装方法を示すコードについては、Elastic Nodesの例も参照してください。

印刷

Graphics View は、レンダリング関数であるQGraphicsScene::render() とQGraphicsView::render() を使用して、1 行印刷を提供します。これらの関数は同じAPIを提供します：レンダリング関数のどちらかにQPainter を渡すことで、シーンまたはビューに、そのコンテンツの全部または一部を任意のペイントデバイスにレンダリングさせることができます。この例では、QPrinterを使ってシーン全体を1ページに印刷する方法を示しています。

QGraphicsScene scene;
QPrinter printer;
scene.addRect(QRectF(0, 0, 100, 200), QPen(Qt::black), QBrush(Qt::green));

if (QPrintDialog(&printer).exec() == QDialog::Accepted) {
    QPainter painter(&printer);
    painter.setRenderHint(QPainter::Antialiasing);
    scene.render(&painter);
}

シーンとビューのレンダリング関数の違いは、一方はシーン座標で、もう一方はビュー座標で操作することです。QGraphicsScene::render()は、幾何データのプロットやテキストドキュメントの印刷など、シーンのセグメント全体を変換せずに印刷する場合によく使用されます。QGraphicsView::render一方、()はスクリーンショットを撮るのに適しています。そのデフォルトの動作は、提供されたペインターを使ってビューポートの内容を正確にレンダリングすることです。

QGraphicsScene scene;
scene.addRect(QRectF(0, 0, 100, 200), QPen(Qt::black), QBrush(Qt::green));

QPixmap pixmap;
QPainter painter(&pixmap);
painter.setRenderHint(QPainter::Antialiasing);
scene.render(&painter);
painter.end();

pixmap.save("scene.png");

ソース領域とターゲット領域のサイズが一致しない場合、ソースコンテンツはターゲット領域に収まるように引き伸ばされます。使用するレンダリング関数にQt::AspectRatioMode を渡すことで、コンテンツが引き伸ばされるときにシーンの縦横比を維持するか無視するかを選択できます。

ドラッグ＆ドロップ

QGraphicsView はQWidget を間接的に継承しているため、QWidget が提供するのと同じドラッグ＆ドロップ機能をすでに提供しています。さらに、便利な機能として、グラフィックス・ビュー・フレームワークは、シーンと各アイテムのドラッグ・アンド・ドロップをサポートしています。ビューはドラッグを受け取ると、ドラッグ＆ドロップイベントをQGraphicsSceneDragDropEvent に変換し、シーンに転送します。シーンはこのイベントのスケジューリングを引き継ぎ、マウスカーソルの下にあるドロップを受け付ける最初のアイテムにイベントを送ります。

アイテムからドラッグを開始するには、QDrag オブジェクトを作成し、ドラッグを開始するウィジェットにポインタを渡します。アイテムは同時に多くのビューで観察できますが、ドラッグを開始できるビューは1つだけです。ドラッグはほとんどの場合、マウスを押したり動かしたりした結果として開始されるので、mousePressEvent() や mouseMoveEvent() で、イベントから開始するウィジェットのポインタを取得できます。例えば

void CustomItem::mousePressEvent(QGraphicsSceneMouseEvent *event)
{
    QMimeData *data = new QMimeData;
    QDrag *drag = new QDrag(event->widget());
    drag->setMimeData(data);
    drag->exec();
}

シーンのドラッグ・アンド・ドロップ・イベントをインターセプトするには、QGraphicsItem のサブクラスで、QGraphicsScene::dragEnterEvent() と、特定のシーンが必要とするイベント・ハンドラを再実装します。グラフィックスビューのドラッグ＆ドロップについては、QGraphicsScene の各イベントハンドラのドキュメントを参照してください。

アイテムは、QGraphicsItem::setAcceptDrops() を呼び出すことで、ドラッグ＆ドロップのサポートを有効にすることができます。入力されたドラッグを処理するには、QGraphicsItem::dragEnterEvent(),QGraphicsItem::dragMoveEvent(),QGraphicsItem::dragLeaveEvent(),QGraphicsItem::dropEvent() を再実装します。

Graphics Viewのドラッグ・アンド・ドロップ操作のサポートについては、ドラッグ・アンド・ドロップ・ロボットの例も参照してください。

カーソルとツールチップ

QWidget と同様に、QGraphicsItem もカーソル (QGraphicsItem::setCursor()) とツールチップ (QGraphicsItem::setToolTip()) をサポートしています。カーソルとツールチップは、マウスカーソルがアイテムの領域に入るとQGraphicsView によってアクティブになります（QGraphicsItem::contains() を呼び出すことで検出されます）。

また、QGraphicsView::setCursor() を呼び出すことで、ビューに直接デフォルトのカーソルを設定することもできます。

ツールチップとカーソルの形状処理を実装したコードについては、ドラッグ・アンド・ドロップ・ロボットの例も参照してください。

アニメーション

Graphics Viewは、いくつかのレベルでアニメーションをサポートしています。アニメーション・フレームワークを使えば、簡単にアニメーションを組み立てることができます。そのためには、QGraphicsObject を継承し、QPropertyAnimation をアイテムに関連付ける必要があります。QPropertyAnimation では、QObject のプロパティをアニメーション化できます。

もう一つの方法は、QObject とQGraphicsItem を継承したカスタムアイテムを作成することです。このアイテムは、独自のタイマーを設定することができ、QObject::timerEvent() のインクリメンタルステップでアニメーションを制御することができます。

第 3 のオプションは、Qt 3 の QCanvas との互換性のために利用できるもので、QGraphicsScene::advance() を呼び出してシーンを進め、QGraphicsItem::advance() を呼び出します。

OpenGL レンダリング

OpenGLレンダリングを有効にするには、QGraphicsView::setViewport （）を呼び出して、QGraphicsView のビューポートとして新しいQOpenGLWidget を設定します。OpenGLでアンチエイリアスをかけたい場合は、必要なサンプル数を持つQSurfaceFormat （QSurfaceFormat::setSamples （）を参照）を設定する必要があります。

例

QGraphicsView view(&scene);
QOpenGLWidget *gl = new QOpenGLWidget();
QSurfaceFormat format;
format.setSamples(4);
gl->setFormat(format);
view.setViewport(gl);

アイテムグループ

アイテムを別のアイテムの子にすることで、アイテムのグループ化の最も本質的な特徴を達成することができます：アイテムは一緒に移動し、すべての変換は親から子へ伝搬されます。

さらに、QGraphicsItemGroup は、子アイテムのイベント処理と、グループへのアイテムの追加と削除のための便利なインターフェイスを組み合わせた特別なアイテムです。アイテムをQGraphicsItemGroup に追加すると、そのアイテムの元の位置とトランスフォームが維持されます。一方、一般的にアイテムを再ペアレントすると、その子は新しい親に対する相対的な位置を変更します。便宜上、QGraphicsScene::createItemGroup() を呼び出すことで、シーンを通してQGraphicsItemGroupを作成することができます。

ウィジェットとレイアウト

Qt 4.4 では、ジオメトリとレイアウトを意識したアイテムのサポートがQGraphicsWidget から導入されました。この特別な基本アイテムはQWidget に似ていますが、QWidget とは異なり、QPaintDevice から継承するのではなく、QGraphicsItem から継承します。これにより、イベント、シグナル＆スロット、サイズヒント、ポリシーを持つ完全なウィジェットを書くことができます。また、QGraphicsLinearLayout とQGraphicsGridLayout を通して、ウィジェットのジオメトリをレイアウトで管理することもできます。

QGraphicsWidget

QGraphicsItem QGraphicsWidget スタイル、フォント、パレット、レイアウト方向、およびジオメトリなどのQWidget からの追加機能と、QGraphicsItem からの解像度非依存および変換サポートです。 グラフィックスビューは整数ではなく実座標を使用するため、QGraphicsWidget のジオメトリ関数はQRectF およびQPointF でも動作します。これはフレームの矩形、マージン、スペーシングにも適用されます。QGraphicsWidget では、例えばコンテンツの余白を (0.5, 0.5, 0.5, 0.5) と指定することも珍しくありません。サブウィジェットと "トップレベル "ウィンドウの両方を作成することができます。場合によっては、高度なMDIアプリケーションのためにグラフィック・ビューを使用することもできます。

ウィンドウのフラグや属性など、QWidget'のプロパティのいくつかがサポートされていますが、すべてではありません。何がサポートされ、何がサポートされていないかの完全な概要については、QGraphicsWidget'のクラス・ドキュメントを参照してください。たとえば、QGraphicsWidget'のコンストラクタにQt::Window ウィンドウフラグを渡すことで、装飾ウィンドウを作成できますが、Graphics View は現在、macOS で一般的なQt::Sheet およびQt::Drawer フラグをサポートしていません。

QGraphicsLayout

QGraphicsLayout は、 のために特別に設計された第2世代のレイアウト・フレームワークの一部です。その API は の API と非常に似ています。 と のどちらかの内部でウィジェットとサブレイアウトを管理できます。また、 を自分でサブクラス化することで独自のレイアウトを簡単に記述したり、 のアダプタ・サブクラスを記述することで独自の アイテムをレイアウトに追加したりすることもできます。QGraphicsWidget QLayout QGraphicsLinearLayout QGraphicsGridLayout QGraphicsLayout QGraphicsLayoutItem QGraphicsItem

埋め込みウィジェットのサポート

Graphics View は、あらゆるウィジェットをシーンに埋め込むためのシームレスなサポートを提供します。QLineEdit やQPushButton のような単純なウィジェット、QTabWidget のような複雑なウィジェット、さらには完全なメイン・ウィンドウを埋め込むことができます。ウィジェットをシーンに埋め込むには、QGraphicsScene::addWidget() を呼び出すか、QGraphicsProxyWidget のインスタンスを作成して手動でウィジェットを埋め込みます。

QGraphicsProxyWidget を通して、Graphics View は、カーソル、ツールチップ、マウス、タブレット、 キーボードイベント、子ウィジェット、アニメーション、ポップアップ(例:QComboBox やQCompleter)、ウィジェットの入力フォーカスとアクティブ化など、クライアントウィジェットの機能を深く統合することができます。QGraphicsProxyWidget は、埋め込みウィジェットのタブオーダーも統合するので、埋め込みウィジェットのタブインとタブアウトが可能です。シーンに新しいQGraphicsView を埋め込んで、複雑なネストシーンを提供することもできます。

埋め込まれたウィジェットを変換するとき、Graphics View は、ウィジェットが解像度に依存せずに変換されることを確認します。(解像度の独立性の効果は、スタイルに依存することに注意してください)。

パフォーマンス

浮動小数点命令

アイテムに正確かつ迅速に変換と効果を適用するために、Graphics Viewは、ユーザのハードウェアが浮動小数点命令に対して妥当なパフォーマンスを提供できることを前提に構築されています。

多くのワークステーションやデスクトップコンピュータには、この種の計算を高速化する適切なハードウェアが搭載されていますが、組み込みデバイスの中には、数学演算を処理するライブラリしか提供されていないものや、ソフトウェアで浮動小数点命令をエミュレートしているものしかないものもあります。

その結果、ある種の効果は、ある種のデバイスでは予想以上に遅くなるかもしれません。例えば、OpenGL を使ってシーンをレンダリングするなどです。しかし、そのような最適化が浮動小数点ハードウェアの存在に依存している場合、それ自体が性能の低下を引き起こす可能性があります。