QGraphicsScene (Qt) の基本: アイテム管理とイベント処理

QGraphicsScene (クラス)

QGraphicsScene クラスは、Qtの Graphics View Framework における**シーン（場面、舞台）**を表すクラスです。これは、2Dグラフィックスアイテムを管理し、それらのインタラクションを処理するための中心的な役割を果たします。

主な役割と機能

1. • QGraphicsScene は、QGraphicsItem クラスを継承した様々なグラフィックスアイテム（矩形、円、テキスト、カスタムアイテムなど）を格納し、管理します。
   • addItem() 関数を使ってシーンにアイテムを追加します。
   • removeItem() 関数を使ってシーンからアイテムを削除します。
   • シーン内のすべてのアイテムや、特定の条件を満たすアイテムを検索する機能を提供します。

2. 座標系の管理
   

   • QGraphicsScene は独自の2D座標系を持っています。シーンに追加されたアイテムはこのシーンの座標系に基づいて配置されます。
   • シーンの境界（bounding rect）を設定することができます。

3. イベント処理
   

   • マウスイベントやキーボードイベントなどの入力イベントを検出し、シーン内の適切なアイテムに配信します。
   • アイテムがこれらのイベントをどのように処理するかを定義できます。

4. 描画の管理
   

   • シーン内のアイテムの描画順序を管理します。
   • QGraphicsView によってシーンが描画される際に、どの部分を再描画する必要があるかを効率的に判断します。

5. 衝突検出
   

   • シーン内のアイテム同士の衝突を検出する機能を提供します。

6. バックグラウンドとフォアグラウンド
   

   • シーンの背景色や背景ブラシ、フォアグラウンドブラシを設定できます。

QGraphicsView との関係

QGraphicsScene は、実際に画面に表示されるわけではありません。シーンの内容を表示し、ユーザーとのインタラクションを可能にするのは QGraphicsView クラスです。

• QGraphicsView は、シーンの表示範囲の拡大縮小（ズーム）、回転、スクロールなどの操作を提供します。
• 一つの QGraphicsScene を複数の QGraphicsView で表示したり、複数のシーンを異なるビューで表示したりすることができます。
• QGraphicsView は、QGraphicsScene の内容を表示するための**ビューポート（表示窓）**のような役割を果たします。

---

QGraphicsScene (クラス) の一般的なエラーとトラブルシューティング

QGraphicsScene を使用する際に遭遇しやすいエラーや問題点、そしてその解決策について解説します。

アイテムがシーンに表示されない

• トラブルシューティング
  

  • addItem() を呼び出しているか確認する。
  • アイテムの pos() メソッドで位置を確認し、シーンの境界内に移動してみる。
  • アイテムの setZValue() を調整して、Z 値を高くしてみる。
  • アイテムの setVisible(true) を明示的に呼び出す。
  • QGraphicsView に正しいシーンが設定されているか確認する。
  • QGraphicsView の fitInView() 関数や setSceneRect() 関数を使って、シーン全体が表示されるように調整する。
• • addItem() でアイテムをシーンに追加していない。
  • アイテムの位置がシーンの可視範囲外にある。アイテムの初期位置がシーンの境界から大きく外れている可能性があります。
  • アイテムの Z 値が他のアイテムの下に隠れている。Z 値はアイテムの重なり順を決定します。
  • アイテムの isVisible() プロパティが false に設定されている。
  • QGraphicsView が正しい QGraphicsScene を表示するように設定されていない (view->setScene(scene) が呼ばれていない)。
  • QGraphicsView の表示範囲が狭く、アイテムが含まれていない。

マウスイベントがアイテムに届かない

• トラブルシューティング
  

  • setAcceptMouseEvents(true) を呼び出しているか確認する。
  • アイテムの Z 値を調整する。
  • シーンの mouseGrabberItem() を確認して、どのアイテムが現在マウスグラブを持っているか調べる。
  • カスタムアイテムの場合、shape() メソッドが意図した形状を返しているか確認する。

• 原因
  

  • アイテムがマウスイベントを受け付けるように設定されていない (item->setAcceptMouseEvents(true) が呼ばれていない)。
  • アイテムが他のアイテムの下に隠れており、手前のアイテムがイベントを横取りしている。Z 値を確認する。
  • シーンのイベント処理が正しく設定されていない。
  • アイテムの形状がマウスカーソルの位置と重なっていない。アイテムの shape() メソッドが適切に定義されているか確認する。

シーンの座標系とアイテムの座標系の混乱

• トラブルシューティング
  

  • 座標を扱う際には、それがシーン座標なのかアイテム座標なのかを常に意識する。
  • アイテムの位置やマウスイベントの位置などをシーン座標で取得したい場合は mapToScene() を使用する。
  • シーン座標をアイテムのローカル座標に変換したい場合は mapFromScene() を使用する。

• 原因
  

  • シーン座標とアイテム座標を混同して使用している。アイテム内の座標はアイテム自身のローカル座標系であり、シーン全体の位置を表すにはシーン座標に変換する必要がある。
  • mapToScene() や mapFromScene() などの座標変換関数を適切に使用していない。

大量のアイテムを追加した際のパフォーマンス低下

• トラブルシューティング
  

  • 本当にすべてのアイテムを同時に表示する必要があるか検討する。必要に応じて、表示範囲外のアイテムを非表示にするなどの最適化を行う。
  • 複雑な形状のアイテムを、より単純な形状の複数のアイテムに分割することを検討する。
  • アイテムの追加や削除を頻繁に行う場合は、効率的なデータ構造を使用したり、必要最小限の更新に留めるようにする。
  • QGraphicsView のキャッシュモード (setCacheMode()) を適切に設定することを検討する。

• 原因
  

  • シーンに非常に多くのアイテムを追加すると、描画やイベント処理の負荷が高くなり、パフォーマンスが低下する。
  • 複雑な形状のアイテムを多数使用している。
  • 頻繁にアイテムの追加や削除を行っている。

カスタムアイテムの描画に関する問題

• トラブルシューティング
  

  • paint() メソッド内で必要な描画処理がすべて行われているか確認する。
  • QPainter の設定（ブラシ、ペンなど）が正しいか確認する。
  • boundingRect() がアイテムの実際の描画範囲を正確に返しているか確認する。boundingRect() が正しくないと、再描画の範囲が誤ったり、アイテムの選択範囲がおかしくなったりする。

• 原因
  

  • カスタムアイテムの paint() メソッドの実装が正しくない。
  • ペインタの状態（ブラシ、ペンなど）が意図したとおりに設定されていない。
  • アイテムの境界矩形 (boundingRect()) が描画内容と一致していない。

シグナルとスロットの接続に関する問題

• トラブルシューティング
  

  • connect() が正しく呼び出されているか確認する。
  • シグナルとスロットのシグネチャが完全に一致しているか確認する。
  • Qt のコンパイラがシグナルとスロットの構文を認識しているか確認する (moc ファイルの生成など)。

• 原因
  

  • アイテムやシーンから発行されるシグナルを期待通りに処理するスロットが接続されていない。
  • シグナルの引数とスロットの引数が一致していない。

アニメーションに関する問題

• トラブルシューティング
  

  • アニメーションの開始、停止、進行などが正しく制御されているか確認する。
  • アニメーションの対象となるプロパティが正しく設定されているか確認する。
  • 複数のアニメーションが競合していないか確認する。

• 原因
  

  • QGraphicsItemAnimation などのアニメーションクラスの使い方が間違っている。
  • アニメーションのタイミングや継続時間が意図したとおりになっていない。

一般的なデバッグのヒント

• 簡単なテストケースの作成
  問題を再現する最小限のコードを作成し、問題を特定しやすくする。
• ドキュメントの参照
  Qt の公式ドキュメントは非常に充実しているので、関連するクラスや関数の詳細を確認する。
• Qt Creator のデバッガ
  ブレークポイントを設定し、ステップ実行でプログラムの動作を詳しく追跡する。
• qDebug() の活用
  問題が発生している箇所で変数の値やプログラムの流れを出力して確認する。

---

例1: 基本的なシーンとビューの作成

この例では、空の QGraphicsScene を作成し、それを QGraphicsView に表示します。

#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    // QGraphicsScene のインスタンスを作成
    QGraphicsScene *scene = new QGraphicsScene();

    // QGraphicsView のインスタンスを作成し、シーンを設定
    QGraphicsView *view = new QGraphicsView(scene);

    // ウィンドウのサイズを設定 (任意)
    view->setFixedSize(400, 300);

    // ビューを表示
    view->show();

    return a.exec();
}

説明

1. #include <QApplication>, #include <QGraphicsScene>, #include <QGraphicsView>: 必要なヘッダファイルをインクルードします。
2. QGraphicsScene *scene = new QGraphicsScene();: QGraphicsScene クラスの新しいインスタンスを作成します。これがグラフィックスアイテムを管理する舞台となります。
3. QGraphicsView *view = new QGraphicsView(scene);: QGraphicsView クラスの新しいインスタンスを作成し、コンストラクタに先ほど作成した scene を渡します。これにより、ビューは指定されたシーンの内容を表示するようになります。
4. view->setFixedSize(400, 300);: ビューのウィンドウサイズを固定します（任意）。
5. view->show();: ビュー（とそれに表示されるシーン）を画面に表示します。

例2: シーンへの基本的なアイテムの追加 (矩形)

この例では、シーンに QGraphicsRectItem（矩形）を追加します。

#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsRectItem>
#include <QRectF>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    QGraphicsScene *scene = new QGraphicsScene();
    QGraphicsView *view = new QGraphicsView(scene);
    view->setFixedSize(400, 300);

    // 矩形アイテムを作成 (x, y, width, height)
    QRectF rect(50, 50, 100, 80);
    QGraphicsRectItem *rectItem = new QGraphicsRectItem(rect);

    // シーンにアイテムを追加
    scene->addItem(rectItem);

    view->show();

    return a.exec();
}

説明

1. #include <QGraphicsRectItem> と #include <QRectF> を追加します。
2. QRectF rect(50, 50, 100, 80);: 矩形の左上の座標 (50, 50)、幅 100、高さ 80 を持つ QRectF オブジェクトを作成します。
3. QGraphicsRectItem *rectItem = new QGraphicsRectItem(rect);: 作成した QRectF を基に QGraphicsRectItem のインスタンスを作成します。
4. scene->addItem(rectItem);: 作成した矩形アイテムをシーンに追加します。これで、ビューに矩形が表示されるようになります。

例3: マウスイベントの処理 (アイテムの移動)

この例では、シーンに追加した矩形アイテムがマウスでドラッグできるようになります。

#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsRectItem>
#include <QGraphicsItem>
#include <QRectF>

// マウスイベントを処理するカスタムアイテム
class MovableRectItem : public QGraphicsRectItem
{
public:
    MovableRectItem(const QRectF &rect, QGraphicsItem *parent = nullptr)
        : QGraphicsRectItem(rect, parent)
    {
        // マウスイベントを受け付けるように設定
        setAcceptMouseEvents(true);
        // アイテムをマウスで移動可能にするフラグを設定
        setFlag(ItemIsMovable);
        // マウスカーソルがアイテム上にあるときに形状を変更 (任意)
        setCursor(Qt::PointingHandCursor);
    }
};

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    QGraphicsScene *scene = new QGraphicsScene();
    QGraphicsView *view = new QGraphicsView(scene);
    view->setFixedSize(400, 300);

    // カスタム矩形アイテムを作成
    QRectF rect(50, 50, 100, 80);
    MovableRectItem *rectItem = new MovableRectItem(rect);

    // シーンにアイテムを追加
    scene->addItem(rectItem);

    view->show();

    return a.exec();
}

説明

1. MovableRectItem クラスは QGraphicsRectItem を継承しています。
2. setAcceptMouseEvents(true);: この設定により、アイテムはマウスイベントを受け取ることができるようになります。ただし、ドラッグ操作に必要なのは次のフラグです。
3. setFlag(ItemIsMovable);: このフラグを設定することで、Qt は自動的にアイテムのドラッグ操作を処理してくれます。ユーザーがアイテム上でマウスボタンを押したまま移動すると、アイテムの位置が更新されます。
4. setCursor(Qt::PointingHandCursor);: マウスカーソルがアイテム上にあるときに手の形に変更します（視覚的なフィードバック）。

例4: シーン全体へのカスタムイベント処理

この例では、シーン全体でマウスクリックイベントを捕捉し、クリックした位置に円を追加します。

#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsEllipseItem>
#include <QGraphicsSceneMouseEvent>
#include <QPointF>

class MyScene : public QGraphicsScene
{
public:
    MyScene(QObject *parent = nullptr) : QGraphicsScene(parent) {}

protected:
    // マウスプレスイベントをオーバーライド
    void mousePressEvent(QGraphicsSceneMouseEvent *event) override
    {
        if (event->button() == Qt::LeftButton) {
            // クリックされたシーンの座標を取得
            QPointF clickPos = event->scenePos();
            // その位置に半径 10 の円を作成
            QGraphicsEllipseItem *circle = new QGraphicsEllipseItem(clickPos.x() - 10, clickPos.y() - 10, 20, 20);
            // シーンに円を追加
            addItem(circle);
        }
        // 親クラスのイベント処理も呼び出す (必要に応じて)
        QGraphicsScene::mousePressEvent(event);
    }
};

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    MyScene *scene = new MyScene();
    QGraphicsView *view = new QGraphicsView(scene);
    view->setFixedSize(400, 300);

    view->show();

    return a.exec();
}

説明

1. MyScene クラスは QGraphicsScene を継承しています。
2. mousePressEvent(QGraphicsSceneMouseEvent *event) override: この関数をオーバーライドすることで、シーン内で発生したマウスプレスイベントを捕捉できます。
3. event->button() == Qt::LeftButton: 左マウスボタンが押されたかどうかを確認します。
4. event->scenePos(): マウスプレスが発生したシーンの座標を取得します。
5. QGraphicsEllipseItem *circle = new QGraphicsEllipseItem(...): クリックされた位置を中心とする半径 10 の円の QGraphicsEllipseItem を作成します。
6. addItem(circle);: 作成した円をシーンに追加します。

これらの例は QGraphicsScene の基本的な使い方を示しています。QGraphicsScene は、さらに多くの機能を提供しており、複雑なグラフィカルアプリケーションを構築するための強力なツールとなります。例えば、アイテムのグループ化、衝突検出、アニメーション、カスタムアイテムの作成など、様々な機能を利用することができます。

---

カスタムアイテムによる描画とロジックの実装

• 例
  例3の「マウスイベントの処理 (アイテムの移動)」で示した MovableRectItem は、カスタムアイテムの一例です。paint() メソッドをオーバーライドすることで、矩形の描画方法をカスタマイズすることも可能です。

• • 再利用性
    カスタムアイテムは複数のシーンやビューで再利用できます。
  • 組織化
    描画とロジックがアイテムごとにカプセル化され、コードが整理されます。
  • 保守性
    機能が分離されているため、変更やデバッグが容易になります。
  • 柔軟性
    アイテムごとに独自の振る舞いや外観を定義できます。

複数のシーンとビューの連携

1つのアプリケーション内で複数の QGraphicsScene と QGraphicsView を使用し、それぞれ異なるコンテンツや視点を提供する方法です。

• 例
  

  • メインのシーンでオブジェクトを配置し、別の小さなビューでそのオブジェクトのプロパティを編集するインターフェースを作成する。
  • 複数のマップを異なるビューで表示し、あるビューでの操作を他のビューに反映させる。

• 利点
  

  • 複雑なUIの構築
    異なる情報を異なるビューで同時に表示したり、特定の操作に応じてビューを切り替えたりできます。
  • モジュール化
    各シーンが独立した役割を持つため、アプリケーションの構造が明確になります。

シグナルとスロットによるインタラクション

QGraphicsScene や QGraphicsItem が発行するシグナルと、アプリケーション内の他のオブジェクトのスロットを接続することで、アイテム間のインタラクションや、シーンとアプリケーションロジックの連携を実現する方法です。

• 例
  

  • カスタムアイテムがクリックされたときにシグナルを発行し、メインウィンドウのスロットでその情報を処理する。
  • シーン内のアイテムの位置が変更されたときにシグナルを発行し、別のアイテムの状態を更新する。

• 利点
  

  • 疎結合
    アイテムやシーンは、接続されたスロットを持つオブジェクトの詳細を知る必要がありません。
  • 柔軟性
    実行時にシグナルとスロットの接続を変更できます。
  • イベント駆動型
    イベントが発生したときにのみ処理が実行されるため、効率的です。

アニメーションフレームワークの活用

QGraphicsItemAnimation クラスや Qt のアニメーションフレームワークを利用して、シーン内のアイテムのプロパティ（位置、回転、透明度など）を時間経過とともに変化させる方法です。

• 例
  

  • アイテムがフェードイン・アウトするアニメーション。
  • アイテムがパスに沿って移動するアニメーション。
  • マウスオーバー時にアイテムが拡大・縮小するアニメーション。

• 利点
  

  • 視覚的な効果
    動きのある滑らかなユーザーインターフェースを作成できます。
  • 複雑なアニメーション
    キーフレームやイージングカーブなどを利用して、高度なアニメーションを実装できます。

グラフィックエフェクトの適用

QGraphicsEffect を継承したクラス（QGraphicsBlurEffect, QGraphicsDropShadowEffect など）をアイテムに適用することで、ぼかし、影、色調整などの視覚効果を手軽に追加する方法です。

• 例
  

  • 選択されたアイテムに影を付ける。
  • 無効化されたアイテムをぼかす。
  • マウスオーバー時にアイテムの色を変化させる。

• 利点
  

  • 表現力の向上
    より魅力的で分かりやすいユーザーインターフェースを作成できます。
  • 簡単な適用
    既存のアイテムにエフェクトを適用するだけで、特別な描画処理は不要です。

Qt Quick (QML) との連携

Qt Quick (QML) のシーンを QGraphicsView にロードしたり、QGraphicsProxyWidget を使用して QML のアイテムを QGraphicsScene に埋め込んだりすることで、QML の宣言的な記述と QGraphicsScene の柔軟性を組み合わせる方法です。

• 例
  

  • 複雑なアニメーションやカスタムUI要素を QML で作成し、QGraphicsScene ベースのアプリケーションに統合する。

• 利点
  

  • UIデザインの容易さ
    QML はUIのデザインとアニメーションに特化しており、効率的な開発が可能です。
  • C++との統合
    バックエンドのロジックは C++ で記述し、UI を QML で作成できます。