【Qtプログラミング】QTreeViewの枝を美しく描画する：drawBranches()活用ガイド
この関数は、QTreeViewクラスの保護された仮想関数です。その名前が示すように、QTreeViewで表示されるツリー構造の「枝（branch）」を描画する役割を担っています。
役割
QTreeView::drawBranches()は、以下の目的で使用されます。
- ツリーの階層構造を示す枝の描画
QTreeViewは、データを階層的に表示するためのウィジェットです。この階層構造を視覚的に表現するために、親アイテムと子アイテムを結ぶ線（枝）が描画されます。drawBranches()は、この枝の描画を担当します。 - カスタマイズポイントの提供
この関数はvirtualであるため、QTreeViewを継承したカスタムクラスでオーバーライドすることができます。これにより、デフォルトの枝の描画方法を変更したり、独自の描画ロジックを追加したりすることが可能です。例えば、枝の線の色、太さ、スタイルを変更したり、枝の代わりに異なるグラフィックを描画したりすることができます。
引数
const QModelIndex &index: 枝を描画する対象となるモデルのインデックスです。このインデックスは、ツリー内の特定のアイテムを識別します。const QRect &rect: 枝を描画する範囲を示す矩形です。通常、これは特定のアイテムの行の範囲を指します。QPainter *painter: 描画に使用するQPainterオブジェクトです。このオブジェクトを使用して、枝を描画します。
通常、この関数を直接呼び出すことはほとんどありません。QTreeViewは、表示する必要があるときに内部的にこの関数を呼び出します。
しかし、もしツリーの枝の描画をカスタマイズしたい場合は、以下のようにQTreeViewを継承したクラスを作成し、この関数をオーバーライドします。
#include <QTreeView>
#include <QPainter>
class MyCustomTreeView : public QTreeView
{
Q_OBJECT // Q_OBJECT マクロを忘れないように
public:
MyCustomTreeView(QWidget *parent = nullptr) : QTreeView(parent) {}
protected:
void drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const override
{
// まず、基底クラスの実装を呼び出して、デフォルトの枝を描画します。
QTreeView::drawBranches(painter, rect, index);
// ここに独自の描画ロジックを追加します。
// 例えば、特定のインデックスの枝の色を変更するなど。
if (index.isValid() && index.data().toString() == "特別なアイテム") {
painter->setPen(Qt::red); // 赤い枝にする
// ここで独自の線を描画するなどの処理を追加できます
// 例: painter->drawLine(rect.center().x(), rect.top(), rect.center().x(), rect.bottom());
}
}
};
この例では、まず基底クラスのdrawBranches()を呼び出してデフォルトの枝を描画し、その後、特定の条件（アイテムのテキストが「特別なアイテム」の場合）を満たす場合に枝の色を赤に変更しています。
基底クラスの drawBranches() の呼び忘れ
エラー/問題
カスタム描画を追加したにも関わらず、既存の枝（プラス/マイナス記号や接続線）が表示されない、または一部しか表示されない。
原因
drawBranches() をオーバーライドした際に、基底クラスである QTreeView::drawBranches(painter, rect, index); を呼び出していないためです。基底クラスの描画は、基本的な枝の構造（展開/折りたたみのインジケーターなど）を描画する責任があります。これを呼び出さないと、それらの要素が描画されません。
トラブルシューティング
オーバーライドした関数の先頭で、必ず基底クラスの drawBranches() を呼び出してください。
void MyCustomTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
// これを忘れないこと！
QTreeView::drawBranches(painter, rect, index);
// ここに独自の描画ロジックを追加
}
QPainter の状態管理の不備
エラー/問題
描画後に他の要素（アイテムのテキストなど）の色やフォントが変わってしまう、または意図しない描画が他の場所で発生する。
原因
QPainter は状態を持つオブジェクトです。drawBranches() 内で QPainter のペン、ブラシ、フォントなどのプロパティを変更した場合、その変更は drawBranches() の呼び出し後も維持されます。次の描画処理（例えば drawRow() や drawItem()）が意図しないスタイルで描画されてしまう可能性があります。
トラブルシューティング
QPainter の状態を変更する前には painter->save() を呼び出し、変更後に painter->restore() を呼び出して、変更を元に戻すようにしてください。これにより、drawBranches() 内での変更が他の描画に影響を与えなくなります。
void MyCustomTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
QTreeView::drawBranches(painter, rect, index);
painter->save(); // 現在のQPainterの状態を保存
// ここでペンの色を変更したりする
painter->setPen(Qt::blue);
painter->drawLine(rect.center().x(), rect.top(), rect.center().x(), rect.bottom());
painter->restore(); // 保存したQPainterの状態を復元
}
無効な QModelIndex へのアクセス
エラー/問題
アプリケーションがクラッシュする、または不正なデータにアクセスしようとする。
原因
drawBranches() に渡される index は、必ずしも有効なモデルインデックスとは限りません。特に、ツリーの表示領域に空きがある場合など、無効なインデックスが渡されることがあります。無効なインデックスに対して data() や parent() などのメソッドを呼び出すと、未定義の動作を引き起こす可能性があります。
トラブルシューティング
index.isValid() を使って、インデックスが有効であることを確認してから、そのインデックスのデータにアクセスするようにしてください。
void MyCustomTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
QTreeView::drawBranches(painter, rect, index);
if (index.isValid()) { // インデックスが有効か確認
// ここに独自の描画ロジックを追加
// 例: index.data().toString() など
}
}
描画領域（rect）の誤解釈
エラー/問題
枝が正しく配置されない、または他のアイテムと重なって描画される。
原因
rect は、枝を描画する対象となるアイテムの行の矩形を表しますが、これは枝の描画に直接使える座標系ではありません。特に、ツリーのインデントや展開/折りたたみのインジケーターの位置を考慮せずに直接 rect を使用すると、描画位置がずれることがあります。
トラブルシューティング
枝の描画には、QTreeView の indentation() プロパティや、QStyleOptionViewItem を使って得られる情報を利用すると良いでしょう。また、特定の枝の描画位置を厳密に制御したい場合は、QStyledItemDelegate の paint() 関数で枝を描画することを検討してください。drawBranches() はツリー全体の枝構造を描画するものであり、個々のアイテムの細かな調整はQStyledItemDelegateの役割です。
エラー/問題
QStyledItemDelegate でアイテムの描画をカスタマイズしているのに、枝の描画が期待通りにならない。
原因
drawBranches() は QTreeView 自体が呼び出すものであり、QStyledItemDelegate の paint() とは独立して動作します。QStyledItemDelegate でカスタム描画を行う場合、枝の描画もその中で完全に制御したい場合があります。
トラブルシューティング
もし、QStyledItemDelegate でアイテムの描画を包括的に制御したいのであれば、QTreeView::drawBranches() をオーバーライドする代わりに、QStyledItemDelegate の paint() メソッド内で枝も描画するようにします。この場合、QStyle::PE_IndicatorBranch などのスタイル要素を利用して、Qt の標準的な枝の描画ロジックを再利用できます。あるいは、drawBranches() を空の関数としてオーバーライドし、すべての枝描画をデリゲートに任せることも可能です。
// QTreeView::drawBranches() をオーバーライドして枝の描画を抑制する例
void MyCustomTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
// 何も描画しない（描画はデリゲートで行う）
Q_UNUSED(painter);
Q_UNUSED(rect);
Q_UNUSED(index);
}
そして、デリゲートの paint() メソッド内で枝を描画します。
// QStyledItemDelegate::paint() で枝を描画する例
void MyCustomItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
{
QStyleOptionViewItem opt = option;
initStyleOption(&opt, index);
// デフォルトのアイテム描画
QApplication::style()->drawControl(QStyle::CE_ItemViewItem, &opt, painter, option.widget);
// 枝の描画
if (opt.features & QStyleOptionViewItem::HasDisplay) { // 枝を持つアイテムの場合
QStyleOptionViewItemV4 branchOption = opt; // 必要に応じてバージョンを合わせる
branchOption.rect = QRect(option.rect.x(), option.rect.y(), option.decorationSize.width(), option.rect.height()); // 枝の描画領域を調整
// プラス/マイナス記号や接続線を描画
QApplication::style()->drawPrimitive(QStyle::PE_IndicatorBranch, &branchOption, painter, option.widget);
}
}
基本的なオーバーライドと基底クラスの呼び出し
最も基本的な例は、単に drawBranches() をオーバーライドし、基底クラスの描画を呼び出すことです。これだけでは見た目は変わりませんが、カスタム描画を追加するための出発点となります。
// MyTreeView.h
#ifndef MYTREEVIEW_H
#define MYTREEVIEW_H
#include <QTreeView>
#include <QPainter>
class MyTreeView : public QTreeView
{
Q_OBJECT // Q_OBJECT マクロを忘れずに
public:
explicit MyTreeView(QWidget *parent = nullptr);
protected:
// QTreeView::drawBranches() をオーバーライド
void drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const override;
};
#endif // MYTREEVIEW_H
// MyTreeView.cpp
#include "MyTreeView.h"
MyTreeView::MyTreeView(QWidget *parent)
: QTreeView(parent)
{
// 必要に応じてQTreeViewのプロパティを設定
// setRootIsDecorated(true); // ルートアイテムの装飾を表示するかどうか
}
void MyTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
// !!! 重要: 必ず基底クラスの描画を呼び出すこと !!!
QTreeView::drawBranches(painter, rect, index);
// ここに独自の描画ロジックを追加
// 例えば、デバッグのためにrectの領域を描画してみる
// painter->drawRect(rect);
}
枝の色の変更（特定条件の場合）
特定のアイテムの枝の色を変更する例です。QPainter の状態を保存・復元することが重要です。
// MyTreeView.cpp (drawBranches関数の内容のみ)
#include "MyTreeView.h"
#include <QDebug> // デバッグ用
void MyTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
QTreeView::drawBranches(painter, rect, index); // 基底クラスの描画
// インデックスが有効であることを確認
if (index.isValid()) {
// 例: アイテムのデータが "重要" という文字列を含む場合、枝を赤にする
if (index.data(Qt::DisplayRole).toString().contains("重要")) {
painter->save(); // QPainterの状態を保存
QPen oldPen = painter->pen(); // 現在のペンを保存
QPen newPen(Qt::red, 2); // 赤色で太さ2の新しいペン
painter->setPen(newPen);
// ここで枝を再描画したり、既存の枝の上に重ねて描画したりできます。
// デフォルトの枝の描画ロジックを正確に模倣するのは難しいので、
// 既存の枝の上に独自の線を描画する方が現実的です。
// 例: アイテムの行の左端に赤い縦線を描画
painter->drawLine(rect.left() + indentation() / 2, rect.top(),
rect.left() + indentation() / 2, rect.bottom());
painter->setPen(oldPen); // 元のペンに戻す
painter->restore(); // QPainterの状態を復元
}
}
}
解説
rect: 現在描画しているアイテムの行の矩形です。この矩形は、そのアイテムの全体的な領域を示します。枝は通常、この矩形の左端のインデント領域に描画されます。indentation():QTreeViewのインデント幅を取得します。これを使って枝の描画位置を調整できます。index.isValid(): 描画対象のQModelIndexが有効であるかを確認します。無効なインデックスにアクセスするとクラッシュの原因になります。painter->save()とpainter->restore(): これは非常に重要です。drawBranches関数内でQPainterの設定（ペン、ブラシなど）を変更した場合、その変更はdrawBranchesの呼び出し後も持続してしまいます。save()で変更前の状態を保存し、restore()で変更後の描画が完了したら元の状態に戻すことで、他の描画（アイテムのテキストやアイコンなど）に影響を与えないようにします。
枝の代わりにカスタムアイコンを描画する
これは少し複雑になりますが、枝のプラス/マイナス記号の代わりに独自のアイコンを表示したい場合に利用できます。QStyle::PE_IndicatorBranch を直接操作する方法もありますが、ここでは drawBranches() をオーバーライドして、独自の描画を優先させる方法を示します。
// MyTreeView.cpp (drawBranches関数の内容のみ)
#include "MyTreeView.h"
#include <QApplication>
#include <QStyle>
void MyTreeView::drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const
{
// 通常は基底クラスの描画を呼び出しますが、
// 枝の描画を完全に置き換えたい場合は、ここをコメントアウトするか、
// drawBranches() を空の関数として実装することも可能です。
// QTreeView::drawBranches(painter, rect, index);
if (!index.isValid()) {
return;
}
painter->save();
// 展開状態に応じたアイコンを選択
QIcon icon;
if (isExpanded(index)) {
icon = QApplication::style()->standardIcon(QStyle::SP_ArrowDown); // 展開時
} else {
icon = QApplication::style()->standardIcon(QStyle::SP_ArrowRight); // 折りたたみ時
}
// アイコンの描画位置を計算
// 通常、枝のインジケーターはアイテムの行の左端に描画されます
// indentation() を考慮して位置を調整します
int iconSize = 16; // アイコンのサイズ（例）
int x = rect.left() + (indentation() / 2) - (iconSize / 2); // 枝の中心あたりに配置
int y = rect.center().y() - (iconSize / 2); // 行の中央に配置
// アイコンを描画
icon.paint(painter, QRect(x, y, iconSize, iconSize));
painter->restore();
}
解説
indentation()を使って、ツリーのインデントを考慮したアイコンの配置を行っています。QApplication::style()->standardIcon()を使用して、Qt の標準的なアイコンを取得しています。これにより、OS のテーマに合わせたアイコンが表示されます。QTreeView::drawBranches()の呼び出しをコメントアウトすると、デフォルトの枝（線とプラス/マイナス記号）は描画されなくなり、独自のアイコンが優先されます。
QStyleOptionViewItem と連携した複雑な描画
drawBranches() は枝の描画に特化していますが、アイテム全体の描画コンテキスト (QStyleOptionViewItem) をより細かく制御したい場合は、QStyledItemDelegate を使用することを検討すべきです。しかし、もしdrawBranches()内でその情報を利用したい場合、直接アクセスすることはできません。
これは、drawBranches() が QStyleOptionViewItem を引数に取らないためです。もし、アイテムの他の状態（選択されているか、有効かなど）に基づいて枝の描画をカスタマイズしたいのであれば、QTreeView::drawRow() をオーバーライドし、その中で drawBranches() を呼び出す前にQPainterの状態をカスタマイズする方法が考えられます。ただし、これはdrawBranches()を直接オーバーライドするよりも複雑になる可能性があります。
これらのコード例を実行するには、以下のようなメイン関数とモデル・ビューの設定が必要です。
// main.cpp
#include <QApplication>
#include <QStandardItemModel>
#include "MyTreeView.h"
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
// モデルの作成
QStandardItemModel model;
QStandardItem *parentItem = model.invisibleRootItem();
QStandardItem *item1 = new QStandardItem("アイテム1");
QStandardItem *item2 = new QStandardItem("重要: アイテム2"); // 「重要」を含むアイテム
QStandardItem *item3 = new QStandardItem("アイテム3");
parentItem->appendRow(item1);
item1->appendRow(item2); // item2はitem1の子
item2->appendRow(item3); // item3はitem2の子
// MyTreeViewインスタンスの作成
MyTreeView treeView;
treeView.setModel(&model);
treeView.setWindowTitle("カスタムツリービュー");
treeView.expandAll(); // 全て展開して枝が見えるようにする
treeView.show();
return a.exec();
}
QT += core gui widgets
SOURCES += \
main.cpp \
MyTreeView.cpp
HEADERS += \
MyTreeView.h
QStyledItemDelegate を使用する
これは、QTreeView のアイテム描画をカスタマイズするための最も推奨される方法です。QStyledItemDelegate を継承し、paint() メソッドをオーバーライドすることで、アイテム自体の描画だけでなく、枝の描画も制御できます。
利点
- 既存のスタイル要素の利用
QApplication::style()->drawPrimitive(QStyle::PE_IndicatorBranch, ...)を使用して、Qt のデフォルトの枝の描画ロジックを再利用しつつ、色や位置などを微調整できます。 - QStyleOptionViewItem の利用
paint()メソッドに渡されるQStyleOptionViewItemオブジェクトには、アイテムの状態（選択されているか、有効か、展開されているかなど）に関する豊富な情報が含まれており、これに基づいて描画を動的に変更できます。 - モデル/ビューの原則に準拠
描画ロジックをビュー（QTreeView）から分離し、デリゲートにカプセル化することで、よりクリーンなアーキテクチャになります。 - より粒度の高い制御
個々のアイテムとその関連する枝の描画を同時に制御できます。
欠点
- パフォーマンス
非常に多くのアイテムがある場合、デリゲートのpaint()メソッドでの複雑な描画はパフォーマンスに影響を与える可能性があります。 - 複雑さ
枝の描画を完全に手動で行う場合、Qt のスタイルシステムを理解し、QStyleのプリミティブ要素（PE_IndicatorBranchなど）を適切に呼び出す必要があります。
コード例（概念）
// MyItemDelegate.h
#include <QStyledItemDelegate>
#include <QPainter>
#include <QApplication>
#include <QStyle>
class MyItemDelegate : public QStyledItemDelegate
{
Q_OBJECT
public:
explicit MyItemDelegate(QObject *parent = nullptr) : QStyledItemDelegate(parent) {}
void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override
{
// まず、デフォルトのアイテム描画を実行
QStyledItemDelegate::paint(painter, option, index);
// 枝を描画したい場合
// QStyleOptionViewItemV4 (または現在のQtバージョンに合ったもの) を使用
QStyleOptionViewItemV4 opt = option;
initStyleOption(&opt, index); // 最新のオプションで初期化
// 枝のインジケーターを描画するかどうかを判断
if (opt.features & QStyleOptionViewItem::HasChildren && // 子を持つアイテム
opt.features & QStyleOptionViewItem::HasDisplay) { // 展開/折りたたみ可能なアイテム
painter->save();
// 枝の描画に使用する矩形を調整
// これは、通常アイテムの装飾領域の左端に描画されます
QRect branchRect = QRect(opt.rect.left(), opt.rect.top(), opt.decorationSize.width(), opt.rect.height());
// アイテムが展開されているかどうかに応じて、スタイルオプションを調整
QStyleOption branchOption;
branchOption.rect = branchRect;
branchOption.state = opt.state; // アイテムの状態を引き継ぐ
if (opt.state & QStyle::State_Open) {
branchOption.state |= QStyle::State_Open; // 展開状態を追加
}
// 枝（プラス/マイナス記号と接続線）を描画
QApplication::style()->drawPrimitive(QStyle::PE_IndicatorBranch, &branchOption, painter, opt.widget);
painter->restore();
}
// ここに他のカスタム描画ロジックを追加
}
};
// 使用法
// MyTreeView *treeView = new MyTreeView();
// treeView->setItemDelegate(new MyItemDelegate(treeView));
スタイルシート (QSS) を使用する
Qt スタイルシートは、ウィジェットの見た目を CSS のような構文で変更するための強力なメカニズムです。QTreeView::branch サブコントロールを使用して、枝の画像を置き換えたり、背景色を変更したりできます。
利点
- システムスタイルへの影響が少ない
drawBranches()やQStyledItemDelegateと異なり、他のウィジェットの描画に影響を与えにくいです（ただし、影響範囲を理解する必要はあります）。 - テーマの変更が容易
実行時にスタイルシートを切り替えることで、簡単にテーマを変更できます。 - デザイナーとの連携
Qt Designer でプレビューしながら調整しやすい場合があります。 - コードの分離
描画ロジックを C++ コードから分離し、UI ファイルや QSS ファイルに配置できます。
欠点
- パフォーマンス
複雑なスタイルシートはパフォーマンスに影響を与える可能性があります。 - 画像の用意
カスタムの枝の画像を用意する必要があります。 - 柔軟性の限界
drawBranches()やQStyledItemDelegateのように、複雑な条件に基づいた動的な描画（例: 特定のアイテムの枝だけ色を変える）は難しい場合があります。画像を指定する必要があるため、動的な生成には不向きです。
コード例（QSS）
/* QTreeView の枝の背景色を変更 */
QTreeView::branch {
background-color: lightblue;
}
/* 展開された枝のアイコンをカスタム画像に置き換え */
QTreeView::branch:open {
image: url(://images/branch-open.png); /* リソースファイルからの画像 */
}
/* 折りたたまれた枝のアイコンをカスタム画像に置き換え */
QTreeView::branch:closed:has-children {
image: url(://images/branch-closed.png); /* 子を持つが折りたたまれている */
}
/* 子を持たない枝（線のみ） */
QTreeView::branch:has-siblings:!adjoins-item {
image: url(://images/branch-vline.png); /* 縦線 */
}
/* 子を持つ枝の末端 */
QTreeView::branch:has-children:!has-siblings:closed,
QTreeView::branch:closed:has-children:!has-siblings {
image: url(://images/branch-end.png); /* 枝の終端（折りたたまれている）*/
}
使用法
// main.cpp または MyTreeView のコンストラクタで
// QTreeView *treeView = new QTreeView();
treeView->setStyleSheet(
"QTreeView::branch { background-color: lightblue; }"
"QTreeView::branch:open { image: url(://images/branch-open.png); }"
// ... 他のスタイルルール
);
QProxyStyle を使用する
QProxyStyle を継承してカスタムスタイルを作成し、drawPrimitive() や drawControl() などのメソッドをオーバーライドすることで、Qt がウィジェットの各部分を描画する方法を変更できます。枝の描画は通常 QStyle::PE_IndicatorBranch プリミティブを通じて行われるため、このプリミティブの描画をフックしてカスタマイズできます。
利点
- 低レベルな制御
Qt が描画を行う最も低レベルのインターフェースにアクセスできます。 - システム全体への影響
アプリケーション全体のスタイルを変更したい場合に特に強力です。
欠点
- 意図しない副作用
適切に実装しないと、アプリケーション内の他のウィジェットの見た目にも影響を与える可能性があります。 - 最も複雑
Qt のスタイルシステムと描画パイプラインに関する深い知識が必要です。
// MyProxyStyle.h
#include <QProxyStyle>
#include <QApplication>
#include <QPainter>
class MyProxyStyle : public QProxyStyle
{
Q_OBJECT
public:
explicit MyProxyStyle(QStyle *baseStyle = nullptr) : QProxyStyle(baseStyle ? baseStyle : QApplication::style()) {}
void drawPrimitive(PrimitiveElement element, const QStyleOption *option, QPainter *painter, const QWidget *widget) const override
{
if (element == PE_IndicatorBranch) {
// ここで独自の枝の描画ロジックを追加
// 例: 赤い円を描画
painter->save();
painter->setBrush(Qt::red);
painter->drawEllipse(option->rect);
painter->restore();
} else {
// その他のプリミティブ要素は基底クラスに任せる
QProxyStyle::drawPrimitive(element, option, painter, widget);
}
}
};
// 使用法
// main.cpp またはアプリケーションの初期化で
// QApplication::setStyle(new MyProxyStyle());
drawBranches()のオーバーライドは、枝の描画に特化しており、手軽にカスタマイズしたい場合に有用ですが、QStyledItemDelegateの方がより汎用性が高く、モデル/ビューの原則に合致します。- アプリケーション全体の描画ロジックを根本的に変更したい、またはdrawBranches()では不可能な低レベルな制御が必要な場合
QProxyStyleを検討しますが、これは高度な知識と注意が必要です。 - アイテムの状態に基づいた複雑な枝の描画、または枝とアイテムの描画を密接に連携させたい場合
QStyledItemDelegateが最も適切です。 - 簡単な見た目の変更（画像置換、基本的な色変更）
スタイルシート (QSS) が最も簡単で推奨されます。