QGraphicsScene::update()の引数と効果：QtプログラミングTips
2025-04-26
QGraphicsScene::update() とは
QGraphicsScene::update() は、QGraphicsScene クラスのメンバ関数の一つで、シーンの一部分または全体を再描画（リペイント）するようにスケジュールする役割を持ちます。直接的な描画処理を行うのではなく、Qtのイベントループに再描画イベントをポストすることで、後で適切なタイミングで描画が行われるようにします。
主な役割と機能
- 再描画の要求
シーン内のアイテムの状態が変化したり、シーン自体に変更があった場合に、その変更を画面に反映させるためにupdate()を呼び出します。 - イベントループとの連携
update()は、QtのイベントループにQEvent::UpdateRequestイベントをポストします。イベントループがこのイベントを処理する際に、実際にシーンの描画処理（QGraphicsViewのpaintEvent()など）が呼び出されます。 - 指定された領域の更新
update()関数には、更新したい矩形領域を引数として渡すことができます。これにより、シーン全体ではなく、変更があった特定の部分のみを再描画するように指示できます。これはパフォーマンスの向上に繋がります。引数を省略した場合、シーン全体のバウンディング矩形が更新対象となります。
使用する場面
QGraphicsScene::update() は、以下のような場合に一般的に使用されます。
- カスタムアイテムの
paint()関数内で、再描画が必要になったとき（ただし、通常はアイテム自身のupdate()を呼び出すことが多いです）。 - アニメーションやインタラクションによって、アイテムが動的に変化するとき。
- シーンからアイテムが削除されたとき。
- シーンに追加されたアイテムの位置、形状、外観などが変化したとき。
具体的な使い方 (C++)
#include <QGraphicsScene>
#include <QGraphicsRectItem>
#include <QGraphicsView>
#include <QApplication>
#include <QTimer>
class MyRectItem : public QGraphicsRectItem {
public:
MyRectItem(qreal x, qreal y, qreal width, qreal height)
: QGraphicsRectItem(x, y, width, height), color(Qt::blue) {
setBrush(color);
// タイマーを使って定期的に色を変える
QTimer *timer = new QTimer(this);
connect(timer, &QTimer::timeout, this, &MyRectItem::changeColor);
timer->start(1000); // 1秒ごとにタイマーが発火
}
private slots:
void changeColor() {
if (color == Qt::blue) {
color = Qt::red;
} else {
color = Qt::blue;
}
setBrush(color);
// このアイテムが所属するシーンの特定領域を再描画するように要求
scene()->update(boundingRect());
}
private:
QColor color;
};
int main(int argc, char *argv[]) {
QApplication a(argc, argv);
QGraphicsScene scene;
MyRectItem *rect = new MyRectItem(0, 0, 100, 50);
scene.addItem(rect);
QGraphicsView view(&scene);
view.show();
return a.exec();
}
上記の例では、MyRectItem の色が1秒ごとに変わります。changeColor() スロットの中で、アイテムの色を変更した後、scene()->update(boundingRect()); を呼び出すことで、その矩形領域の再描画をシーンに要求しています。
一般的なエラーとトラブルシューティング
QGraphicsScene::update() は再描画をスケジュールする役割を持つため、直接的なエラーは少ないですが、その使い方や関連する処理に誤りがあると、意図しない表示になったり、パフォーマンスの問題を引き起こしたりすることがあります。
以下に、よくあるエラーとトラブルシューティングのポイントを挙げます。
再描画が期待通りに行われない
- ビューの更新
シーンが更新されても、関連付けられたQGraphicsViewが適切に再描画されないことがあります。通常は自動的に再描画されますが、何らかの理由でビューが更新されない場合は、ビュー自身のviewport()->update()を試してみることも有効かもしれません。 - 親アイテムの update()
アイテムの子要素が変更された場合、親アイテムのupdate()を呼び出す必要があるかもしれません。子アイテムの変更が親アイテムの描画範囲に影響を与える場合（例えば、子アイテムが移動して親の境界線を越える場合など）に考慮が必要です。 - アイテムの boundingRect() の誤り
カスタムアイテムの場合、boundingRect()関数がアイテムの実際の描画範囲を正しく返していないと、update(boundingRect())を呼び出しても意図した領域が更新されないことがあります。boundingRect()がアイテムの描画内容を包含する最小の矩形を正しく返すように実装する必要があります。 - 更新領域の指定ミス
update()に更新したい領域を明示的に渡している場合、その領域が実際には変更されていない、または変更された領域を完全にカバーしていない可能性があります。変更された領域を正確に指定するか、引数なしでシーン全体の更新を試してみてください。 - update() の呼び忘れ
アイテムの状態が変化したにもかかわらず、update()を呼び出していない場合、画面が更新されません。アイテムのプロパティ（位置、形状、色など）を変更した後に、必ずupdate()を呼び出すようにしてください。
パフォーマンスの問題
- 複雑な描画処理
paint()関数内の描画処理が重い場合、頻繁なupdate()によってアプリケーションの応答性が悪くなることがあります。paint()関数の処理を見直し、最適化を検討してください。キャッシュなどを利用して、再計算を避けるなどの工夫も有効です。 - シーン全体の頻繁な更新
小さな変更に対しても常にupdate()を引数なしで呼び出し、シーン全体を再描画していると、処理負荷が高くなります。可能な限り、変更された具体的な領域を指定してupdate()を呼び出すようにしましょう。
カスタムアイテム関連
- 状態管理の不備
アイテムの状態（色、形状、アニメーションの状態など）を管理する変数が正しく更新されていないと、update()を呼び出しても古い状態のまま再描画されてしまうことがあります。アイテムの状態変更とupdate()の呼び出しが適切に連携しているかを確認してください。 - paint() 関数の実装ミス
カスタムアイテムのpaint()関数が正しく実装されていないと、update()が呼び出されても期待通りの描画が行われません。描画に必要なペン、ブラシ、フォントなどが正しく設定されているか、座標変換やクリッピングなどが適切に行われているかなどを確認してください。
- Qtのドキュメント参照
QGraphicsScene、QGraphicsItem、QGraphicsViewなどの関連クラスのドキュメントを再度確認し、理解を深めることも重要です。 - シンプルなテスト
問題が複雑な場合に、最小限のコードで再現できるテストケースを作成し、問題を切り分けて考えることが有効です。 - 描画範囲の可視化
デバッグ目的で、アイテムのboundingRect()やupdate()に渡している矩形を一時的に描画してみることで、意図した範囲が更新されているかを確認できます。 - デバッグ出力
qDebug()などを使って、update()がいつ、どの領域に対して呼び出されているかを出力してみると、問題の原因を特定しやすくなることがあります。
例1: 基本的な矩形の移動と再描画
この例では、シーンに矩形アイテムを追加し、タイマーを使って定期的に矩形を少しずつ移動させ、そのたびに update() を呼び出して再描画します。
#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsRectItem>
#include <QTimer>
class MovingRect : public QGraphicsRectItem {
public:
MovingRect(qreal x, qreal y, qreal width, qreal height)
: QGraphicsRectItem(x, y, width, height), dx(1), dy(1) {
setBrush(Qt::blue);
}
void advance(int phase) override {
if (!phase) return;
// 現在の位置を取得
QRectF rect = this->rect();
qreal x = rect.x();
qreal y = rect.y();
// 移動量を加算
x += dx;
y += dy;
// 境界チェック (簡易的な例)
if (x > 200 || x < 0) dx *= -1;
if (y > 200 || y < 0) dy *= -1;
// 新しい位置を設定
setRect(x, y, rect.width(), rect.height());
// このアイテムが所属するシーンの、このアイテムの領域を再描画するように要求
scene()->update(boundingRect());
}
private:
qreal dx;
qreal dy;
};
int main(int argc, char *argv[]) {
QApplication a(argc, argv);
QGraphicsScene scene;
MovingRect *rect = new MovingRect(0, 0, 50, 50);
scene.addItem(rect);
scene.setSceneRect(-50, -50, 300, 300); // シーンの範囲を設定
QGraphicsView view(&scene);
view.show();
QTimer timer;
QObject::connect(&timer, &QTimer::timeout, &scene, &QGraphicsScene::advance);
timer.start(30); // 30ミリ秒ごとに advance を呼び出す
return a.exec();
}
説明
QTimerを使用して、定期的にシーンのadvance()スロットを呼び出すことで、アニメーションを実現しています。setRect()で矩形の新しい位置を設定した後、scene()->update(boundingRect());を呼び出すことで、変更された矩形の領域のみを再描画するようにシーンに指示しています。これにより、効率的な再描画が行われます。advance()関数は、Qtのアニメーションフレームワークの一部として定期的に呼び出されます。ここでは、矩形の位置を少しずつ変更し、境界に達したら移動方向を反転させています。MovingRectクラスはQGraphicsRectItemを継承し、移動する矩形を表します。
例2: マウスインタラクションによるアイテムの色の変更と再描画
この例では、マウスボタンがクリックされたときに、クリックされた場所にあるアイテムの色を変更し、そのアイテムの領域を update() します。
#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsRectItem>
#include <QMouseEvent>
#include <QColorDialog>
class ColorChangeRect : public QGraphicsRectItem {
public:
ColorChangeRect(qreal x, qreal y, qreal width, qreal height, QGraphicsItem *parent = nullptr)
: QGraphicsRectItem(x, y, width, height, parent), color(Qt::green) {
setBrush(color);
setAcceptHoverEvents(true); // ホバーイベントを有効にする (ここでは未使用)
setFlag(QGraphicsItem::ItemIsSelectable);
}
protected:
void mousePressEvent(QGraphicsSceneMouseEvent *event) override {
if (event->button() == Qt::LeftButton) {
QColor newColor = QColorDialog::getColor(color, nullptr, tr("Select Color"));
if (newColor.isValid()) {
color = newColor;
setBrush(color);
// このアイテムの領域を再描画するように要求
scene()->update(boundingRect());
}
}
QGraphicsRectItem::mousePressEvent(event);
}
private:
QColor color;
};
int main(int argc, char *argv[]) {
QApplication a(argc, argv);
QGraphicsScene scene;
ColorChangeRect *rect1 = new ColorChangeRect(0, 0, 100, 50);
ColorChangeRect *rect2 = new ColorChangeRect(150, 50, 80, 120);
scene.addItem(rect1);
scene.addItem(rect2);
scene.setSceneRect(-50, -50, 300, 300);
QGraphicsView view(&scene);
view.show();
return a.exec();
}
説明
setFlag(QGraphicsItem::ItemIsSelectable);は、アイテムを選択可能にするためのフラグです（この例では直接的な機能とは関係ありませんが、インタラクティブなアイテムの例として示しています）。- 新しい色が選択されたら、
setBrush()でアイテムのブラシの色を更新し、scene()->update(boundingRect());を呼び出して、色が変わった矩形の領域のみを再描画します。 mousePressEvent()関数をオーバーライドし、左マウスボタンがクリックされたときにQColorDialogを表示して新しい色を選択させます。ColorChangeRectクラスはQGraphicsRectItemを継承し、マウスでクリックされると色が変わる矩形を表します。
例3: カスタムアイテムでの paint() 関数と update() の連携
この例では、円を描画するカスタムアイテムを作成し、タイマーを使って円の半径を徐々に大きくし、そのたびにアイテム自身の update() を呼び出して再描画します。
#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsItem>
#include <QPainter>
#include <QTimer>
#include <QRectF>
class GrowingCircle : public QGraphicsItem {
public:
GrowingCircle(qreal initialRadius) : radius(initialRadius) {
timer = new QTimer(this);
connect(timer, &QTimer::timeout, this, &GrowingCircle::grow);
timer->start(50); // 50ミリ秒ごとに grow を呼び出す
}
QRectF boundingRect() const override {
return QRectF(-radius, -radius, 2 * radius, 2 * radius);
}
protected:
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override {
Q_UNUSED(option);
Q_UNUSED(widget);
painter->setBrush(Qt::red);
painter->drawEllipse(boundingRect());
}
private slots:
void grow() {
radius += 1;
// アイテム自身の領域を再描画するように要求
update();
}
private:
qreal radius;
QTimer *timer;
};
int main(int argc, char *argv[]) {
QApplication a(argc, argv);
QGraphicsScene scene;
GrowingCircle *circle = new GrowingCircle(10);
scene.addItem(circle);
scene.setSceneRect(-50, -50, 200, 200);
QGraphicsView view(&scene);
view.show();
return a.exec();
}
grow()スロットは、タイマーによって定期的に呼び出され、円の半径を増やし、その後update()を呼び出します。QGraphicsItem::update()は、アイテム自身のboundingRect()で定義された領域を再描画するようにシーンに要求します。paint()関数は、実際にアイテムを描画する役割を持ちます。ここでは、現在の半径に基づいて赤い円を描画しています。boundingRect()関数は、アイテムの描画範囲を定義します。半径が変化するため、この関数は常に現在の半径に基づいて正しい矩形を返す必要があります。GrowingCircleクラスはQGraphicsItemを継承し、半径が徐々に大きくなる円を表します。
QGraphicsItem::update()
- 使用場面
特定のアイテムの状態が変化した場合（位置、形状、外観など）、そのアイテム自身のupdate()を呼び出すのが一般的です。 - 利点
変更があったアイテムのみを再描画するため、シーン全体を更新するよりも効率的です。特に多くのアイテムが存在するシーンでは、パフォーマンスの向上が期待できます。 - 説明
QGraphicsScene::update()がシーン全体または指定された領域の再描画をスケジュールするのに対し、QGraphicsItem::update()は、そのアイテム自身のバウンディング矩形（boundingRect()で定義される領域）の再描画をスケジュールします。
例
class MyItem : public QGraphicsItem {
// ...
private slots:
void changeState() {
// アイテムの状態を変更
// ...
update(); // このアイテム自身の再描画をスケジュール
}
};
QGraphicsItem::setPos(), setTransform(), setScale(), setRotation() などの変換関数
- 使用場面
アイテムを移動、回転、拡大縮小させるアニメーションやインタラクションを実装する場合。 - 利点
直接プロパティを操作するよりも、Qtのグラフィックスパイプラインに最適化された方法で変更を通知できます。 - 説明
アイテムの位置、変形（回転、拡大縮小）を変更する場合、これらの専用の関数を使用すると、Qtは内部的に効率的な再描画処理を行います。これらの関数は、アイテムの変換マトリックスを更新し、必要に応じて再描画をスケジュールします。
例
QGraphicsItem *item = scene->addRect(0, 0, 50, 50);
QPropertyAnimation *animation = new QPropertyAnimation(item, "pos");
animation->setDuration(1000);
animation->setStartValue(QPointF(0, 0));
animation->setEndValue(QPointF(100, 100));
animation->start(); // アニメーション開始 (内部で再描画が管理される)
QPropertyAnimation
- 使用場面
視覚的な効果や、状態の変化をアニメーションで表現したい場合。 - 利点
滑らかで複雑なアニメーションを比較的簡単に実装でき、再描画のタイミングを自分で管理する必要がありません。 - 説明
Qtのアニメーションフレームワークを利用することで、アイテムの様々なプロパティ（位置、不透明度、カスタムプロパティなど）を時間経過とともに滑らかに変化させることができます。QPropertyAnimationは、アニメーションの各ステップで自動的に再描画をスケジュールします。
例
上記の setPos() の例は QPropertyAnimation を使用しています。
QPainter::begin() と QPainter::end() の手動管理 (高度な使用)
- 使用場面
特殊な背景描画や、シーンに統合されない一時的なオーバーレイ表示など。 - 注意点
この方法は、QGraphicsSceneの通常のアイテム管理や描画パイプラインから外れるため、アイテムのZ値、イベント処理などが期待通りに動作しない可能性があります。慎重に使用する必要があります。 - 利点
より細かな描画制御が可能になります。 - 説明
通常、QGraphicsItem::paint()関数内でQPainterが自動的に設定されますが、特定の高度な描画ニーズがある場合、QGraphicsViewのviewport()上で直接QPainterを操作することができます。この場合、QPainter::begin()とQPainter::end()を手動で呼び出し、描画後にviewport()->update()を呼び出して変更を反映させる必要があります。
例
void MyGraphicsView::drawBackground(QPainter *painter, const QRectF &rect) {
QGraphicsView::drawBackground(painter, rect);
painter->begin(viewport());
// カスタムの背景描画処理
painter->setBrush(Qt::yellow);
painter->drawRect(rect.adjusted(10, 10, -10, -10));
painter->end();
viewport()->update(); // 手動でビューポートの更新を要求
}
QGraphicsView::render()
- 使用場面
シーンの内容を画像ファイルに保存したり、印刷プレビューを表示したりする場合。 - 利点
シーンのスナップショットを撮ったり、印刷したりするのに便利です。 - 説明
QGraphicsView::render()関数を使用すると、シーンの内容をQPainterが描画できる任意のデバイス（例えばQImage、QPdfWriterなど）にレンダリングできます。これは、画面表示の更新というよりは、シーンの内容を別の形式で出力する目的で使用されます。
例
QImage image(scene->sceneRect().size().toSize(), QImage::Format_ARGB32);
image.fill(Qt::transparent);
QPainter painter(&image);
scene->render(&painter);
painter.end();
image.save("scene_snapshot.png");
QPainterPath のキャッシュ
- 使用場面
静的で複雑な形状を頻繁に描画するカスタムアイテム。 - 利点
特に複雑なベクターグラフィックスの描画において、CPU負荷を軽減できます。 - 説明
複雑な形状を繰り返し描画する場合、QPainterPathを一度作成してキャッシュしておき、paint()関数内で再利用することで、描画パフォーマンスを向上させることができます。update()は、キャッシュされたパスが変更された場合に呼び出す必要があります。
class MyComplexItem : public QGraphicsItem {
public:
MyComplexItem() {
path = new QPainterPath();
// 複雑なパスの作成
path->addEllipse(-50, -50, 100, 100);
path->addRect(0, 0, 80, 30);
}
~MyComplexItem() override { delete path; }
QRectF boundingRect() const override { return path->boundingRect(); }
protected:
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override {
Q_UNUSED(option);
Q_UNUSED(widget);
painter->setBrush(Qt::blue);
painter->drawPath(*path);
}
private:
QPainterPath *path;
};