Qtで魅力的なUIを！スクロールエリアのマージン設定とベストプラクティス
2025-05-27
この関数は、スクロール領域の「ビューポート（viewport）」の周囲に余白（マージン）を設定するために使用されます。
ビューポートとは？
QAbstractScrollAreaは、その名前が示す通り、スクロール可能な領域を提供するウィジェットです。この領域の中心には、「ビューポート」と呼ばれるウィジェットがあります。ビューポートは、実際にスクロールされるコンテンツ（データや他のウィジェットなど）が表示される部分です。
setViewportMargins()の役割
setViewportMargins(int left, int top, int right, int bottom)、またはsetViewportMargins(const QMargins &margins)として定義されており、左右上下の各辺にピクセル単位の余白を指定できます。
この余白は、ビューポートの外側に確保される空間です。つまり、ビューポート自体がこれらのマージンの分だけ内側に縮小され、その縮小された領域にコンテンツが表示されます。
どのような時に使うのか？
この機能は、主に以下のようなケースで役立ちます。
- ビューポートの特定の部分を予約
ビューポートの特定の領域を、スクロールされるコンテンツ以外の目的（例えば、オーバーレイウィジェットの表示など）のために予約したい場合にも使えます。 - 「固定された」行や列の実装
スプレッドシートアプリケーションのように、一部の行や列をスクロールしないように固定したい場合に、このマージンを利用して固定部分を配置し、残りの部分をスクロール可能にするという実装が考えられます（ただし、これはQTableViewなどの高レベルなウィジェットで既にサポートされている場合があります）。 - ヘッダーやフッターの配置
スクロールするコンテンツの上に常に表示されるヘッダーや、下に表示されるフッター（例えば、QHeaderViewのようなウィジェット）を配置したい場合に、そのための空間を確保するために使用されます。これにより、ヘッダーやフッターはスクロールの影響を受けずに固定して表示され、コンテンツのみがスクロールします。
- 設定されたマージンは、スクロールバーの表示・非表示には影響しません。スクロールバーは、ビューポートのコンテンツがビューポートのサイズを超えた場合に表示されます。マージンは、そのスクロールバーの隣に空間を確保します。
QAbstractScrollAreaのサブクラス（例:QScrollArea,QTreeView,QTableViewなど）でこの関数を使用する場合、そのサブクラスがマージンの実装を正しく処理しているかを確認する必要があります。特にQTreeViewやQTableViewのようなアイテムビューでは、内部でこの関数が頻繁に呼び出されるため、直接この関数を呼び出すべきではない場合があります。
-
- 原因
QAbstractScrollAreaの直接のサブクラス（例:QScrollArea）で使用する場合は問題ありませんが、QTreeViewやQTableViewのような、Qtが内部でビューポートのマージンを管理している高レベルなウィジェットのサブクラスでsetViewportMargins()を呼び出すと、期待通りに動作しないことがあります。これらのビューは、ヘッダーなどの要素を配置するために独自のロジックでマージンを計算・設定しているため、手動での設定が上書きされてしまう可能性があります。 - トラブルシューティング
- QScrollAreaを使用する
もし単純にスクロール可能な領域に固定のヘッダーやフッターを配置したいだけであれば、QScrollAreaを使用し、そのsetWidget()で設定したウィジェットに対してマージンを設定する代わりに、QScrollArea自体に対してsetViewportMargins()を呼び出すのが適切です。 - QTreeViewやQTableViewの場合
これらのウィジェットで固定された行や列を実装したい場合は、通常、setViewportMargins()を直接呼び出すのではなく、Qtが提供するより高レベルな機能（例:QTableViewのfrozen rows/columnsのサンプルや、独自にカスタムビューを実装する）を検討すべきです。setViewportMargins()は、これらのビューが内部でヘッダーなどを配置するために使われることが多く、ユーザーが直接制御すべきではない場合が多いです。 - resizeEventでの設定
一部のフォーラムの議論では、resizeEvent()をオーバーライドしてその中でsetViewportMargins()を呼び出すことで動作するケースが報告されています。しかし、これも高レベルなビューでは予期せぬ動作を招く可能性があります。 - QAbstractScrollAreaのサブクラスでマージンを使用する
自分でQAbstractScrollAreaをサブクラス化して、カスタムのスクロールエリアを作成する場合、resizeEvent()やscrollContentsBy()などのイベントハンドラ内でビューポートのレイアウトとマージンを適切に管理する必要があります。
- QScrollAreaを使用する
- 原因
-
マージン領域にウィジェットを配置できない、または配置が難しい
- 原因
setViewportMargins()は、ビューポートの周囲に空白領域を確保するだけの機能です。この関数自体が、その空白領域に何かウィジェットを自動的に配置する機能を提供するわけではありません。 - トラブルシューティング
- 手動での配置
マージンで確保された領域にウィジェットを配置するには、そのウィジェットをQAbstractScrollAreaの親ウィジェット（または適切なコンテナ）の子として追加し、move()やsetGeometry()を使って手動で位置を調整する必要があります。 - レイアウトの使用
マージン領域とビューポート領域の両方を適切に管理するために、親ウィジェットのレイアウト（例:QVBoxLayout,QHBoxLayout,QGridLayout）をうまく活用することを検討してください。例えば、垂直スクロールエリアの場合、QVBoxLayoutを使用して上部に固定ヘッダー、中央にQScrollAreaのビューポート、下部に固定フッターを配置するといった方法が考えられます。
- 手動での配置
- 原因
-
パフォーマンスの問題（再描画の過多）
- 原因
QAbstractScrollAreaの設計上、スクロールイベントが発生するとビューポート全体が再描画されることがあります。特にカスタム描画を行っている場合、最適化されていないとパフォーマンスの低下につながります。setViewportMargins()自体が直接の原因ではありませんが、マージンによってコンテンツの表示領域が変わることで、再描画のロジックが複雑になる可能性があります。 - トラブルシューティング
- scrollContentsBy()の最適化
QAbstractScrollAreaのサブクラスでカスタム描画を行っている場合、scrollContentsBy()関数をオーバーライドして、スクロールによって影響を受ける領域のみを再描画するように最適化することが重要です。 - update()とrepaint()の適切な使用
通常はrepaint()よりもupdate()を使用し、Qtのイベントループに再描画のタイミングを任せるのが良いプラクティスです。 - QGraphicsViewの検討
大量のカスタムアイテムをスクロールする必要がある場合、QGraphicsViewフレームワークは、より高度な描画とスクロールの最適化を提供します。場合によっては、QAbstractScrollAreaを直接使うよりも適していることがあります。
- scrollContentsBy()の最適化
- 原因
-
スクロールバーの表示位置との関係性の誤解
- 原因
setViewportMargins()はビューポートの余白を設定しますが、スクロールバー自体の位置や表示に直接影響を与えるものではありません。スクロールバーは、コンテンツがビューポートのサイズを超えた場合に、ビューポートの「隣」に表示されます。 - トラブルシューティング
- スクロールバーの表示ポリシー（
horizontalScrollBarPolicy(),verticalScrollBarPolicy()）や、スクロールバーのウィジェットを追加する（addScrollBarWidget()）など、スクロールバーに関する他のQAbstractScrollAreaの機能と混同しないように注意してください。
- スクロールバーの表示ポリシー（
- 原因
基本的な考え方
QAbstractScrollArea::setViewportMargins()は、スクロール可能なコンテンツが表示される「ビューポート」の周りに、空白の領域（マージン）を設定します。このマージンによって作られた空間に、スクロールしない固定のウィジェットを配置することができます。
例1: QScrollAreaを使った簡単なヘッダーとフッターの例
この例では、QScrollAreaを使用して、常に表示されるヘッダーとフッターをスクロール可能なコンテンツの上下に配置します。
#include <QApplication>
#include <QScrollArea>
#include <QLabel>
#include <QVBoxLayout>
#include <QWidget>
#include <QPushButton>
class CustomScrollArea : public QWidget
{
public:
CustomScrollArea(QWidget *parent = nullptr) : QWidget(parent)
{
QVBoxLayout *mainLayout = new QVBoxLayout(this);
mainLayout->setContentsMargins(0, 0, 0, 0); // 全体のレイアウトのマージンを0に
// ヘッダーウィジェット
QLabel *headerLabel = new QLabel("これは固定ヘッダーです", this);
headerLabel->setAlignment(Qt::AlignCenter);
headerLabel->setStyleSheet("background-color: lightblue; padding: 5px; font-weight: bold;");
headerLabel->setFixedHeight(30); // ヘッダーの高さ
// スクロールエリア
QScrollArea *scrollArea = new QScrollArea(this);
scrollArea->setWidgetResizable(true); // ウィジェットのサイズ変更を許可
// スクロールコンテンツを作成
QWidget *scrollContent = new QWidget(scrollArea);
QVBoxLayout *contentLayout = new QVBoxLayout(scrollContent);
contentLayout->setAlignment(Qt::AlignTop | Qt::AlignHCenter); // コンテンツを上揃え中央に
for (int i = 0; i < 50; ++i) {
contentLayout->addWidget(new QLabel(QString("スクロール可能なコンテンツ行 %1").arg(i + 1)));
}
scrollContent->setLayout(contentLayout);
scrollArea->setWidget(scrollContent);
// ビューポートのマージンを設定
// ヘッダーとフッターの高さ分だけマージンを確保
// ここが `setViewportMargins()` の重要なポイントです
scrollArea->setViewportMargins(0, headerLabel->height(), 0, 30); // 左, 上 (ヘッダーの高さ), 右, 下 (フッターの高さ)
// フッターウィジェット
QPushButton *footerButton = new QPushButton("フッターボタン", this);
footerButton->setFixedHeight(30); // フッターの高さ
// ヘッダー、スクロールエリア、フッターをメインレイアウトに追加
mainLayout->addWidget(headerLabel);
mainLayout->addWidget(scrollArea);
mainLayout->addWidget(footerButton);
// 各ウィジェットの位置を調整（マージンによって空けられたスペースに配置）
// ヘッダーはスクロールエリアのビューポートの上マージンの位置に配置されます
// フッターはスクロールエリアのビューポートの下マージンの位置に配置されます
// これはメインレイアウトが自動的に行いますが、概念的に理解が重要です。
// ビューポートのマージンがビューポートの表示領域を内側に縮め、
// その縮められた領域の上下にヘッダーとフッターが配置されるイメージです。
}
};
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
CustomScrollArea window;
window.setWindowTitle("QAbstractScrollArea::setViewportMargins 例");
window.resize(300, 400);
window.show();
return a.exec();
}
解説
- CustomScrollArea
全体的なウィンドウを管理するカスタムウィジェットです。 - mainLayout
CustomScrollAreaのメインレイアウトで、ヘッダー、スクロールエリア、フッターを垂直に配置します。 - headerLabel
固定ヘッダーとして機能するQLabelです。これはmainLayoutの一番上に配置されます。 - scrollArea
メインのスクロール可能な領域です。 - scrollContent
scrollAreaにセットされる、実際にスクロールされるコンテンツを含むウィジェットです。ここではたくさんのQLabelを追加して、スクロールが必要になるようにしています。 scrollArea->setViewportMargins(0, headerLabel->height(), 0, 30);:- これが
setViewportMargins()の肝となる部分です。 headerLabel->height()は、ヘッダーラベルの高さ分だけビューポートの上部にマージンを確保します。30は、フッターの高さ分だけビューポートの下部にマージンを確保します。- これにより、
scrollAreaの内部にあるビューポートの描画領域が、上下方向に縮小されます。
- これが
- footerButton
固定フッターとして機能するQPushButtonです。これはmainLayoutの一番下に配置されます。
このコードを実行すると、"これは固定ヘッダーです"というラベルと"フッターボタン"というボタンは常に表示されたままで、その間の「スクロール可能なコンテンツ行」だけがスクロールするようになります。
例2: QTreeViewやQTableViewでの適用について（注意点）
前述の通り、QTreeViewやQTableViewのような高レベルなアイテムビューは、内部でヘッダー（QHeaderView）などを管理するためにsetViewportMargins()を独自に使用しています。そのため、これらのウィジェットで直接setViewportMargins()を呼び出すと、意図しない動作になったり、Qtの内部的なレイアウトと衝突したりする可能性が高いです。
QTreeViewやQTableViewで「固定された」ヘッダーやフッターのようなものを実現したい場合は、通常以下のいずれかの方法を検討します。
-
親レイアウトの利用
QTreeViewやQTableViewを、ヘッダーやフッターとなるウィジェットと一緒に親ウィジェットのレイアウトに追加する方法です。この場合、setViewportMargins()は使用しません。#include <QApplication> #include <QTableView> #include <QStandardItemModel> #include <QVBoxLayout> #include <QLabel> #include <QPushButton> #include <QWidget> int main(int argc, char *argv[]) { QApplication a(argc, argv); QWidget window; QVBoxLayout *mainLayout = new QVBoxLayout(&window); // 固定ヘッダー QLabel *headerLabel = new QLabel("テーブルの固定ヘッダー", &window); headerLabel->setAlignment(Qt::AlignCenter); headerLabel->setStyleSheet("background-color: lightgreen; padding: 5px;"); mainLayout->addWidget(headerLabel); // QTableView QTableView *tableView = new QTableView(&window); QStandardItemModel *model = new QStandardItemModel(10, 3, &window); for (int row = 0; row < 10; ++row) { for (int col = 0; col < 3; ++col) { model->setItem(row, col, new QStandardItem(QString("データ %1,%2").arg(row).arg(col))); } } tableView->setModel(model); // QTableViewに直接 setViewportMargins() は適用しない // tableView->setViewportMargins(0, headerLabel->height(), 0, 0); // やらない方が良い mainLayout->addWidget(tableView); // 固定フッター QPushButton *footerButton = new QPushButton("テーブルの固定フッター", &window); mainLayout->addWidget(footerButton); window.setWindowTitle("QTableView + レイアウト例 (setViewportMarginsなし)"); window.resize(400, 300); window.show(); return a.exec(); }この例では、
QTableView自体にはsetViewportMargins()を適用していません。代わりに、QVBoxLayoutを使ってQLabel、QTableView、QPushButtonを配置することで、視覚的に固定されたヘッダーとフッターを実現しています。これがQTreeViewやQTableViewで固定要素を配置する際の一般的なアプローチです。 -
QHeaderViewのカスタマイズ
行/列ヘッダーの表示方法を変更したい場合は、QHeaderViewのサブクラス化を検討します。
QAbstractScrollArea::setViewportMargins()は、主にQScrollAreaのような単純なスクロールウィジェットに対して、そのビューポートの周囲に固定要素を配置するための空間を確保するのに非常に有効です。しかし、Qtの高レベルなアイテムビュー（QTreeView, QTableViewなど）では、Qtが内部で複雑なレイアウト管理を行っているため、直接この関数を呼び出すのは避けるべきです。それらの場合は、より高レベルなAPIや、親ウィジェットのレイアウトを工夫して固定要素を配置するのが正しいアプローチとなります。
QtのQAbstractScrollArea::setViewportMargins()は、スクロールエリアのビューポート周囲に余白（マージン）を設定するための関数です。これは、特にスクロールするコンテンツとは別に、固定されたヘッダーやフッター、サイドバーなどを表示したい場合に役立ちます。
QScrollAreaを使った基本的な例
QScrollAreaはQAbstractScrollAreaの最も一般的なサブクラスであり、任意のウィジェットをスクロール可能にするために使われます。setViewportMargins()を使って、ビューポートの上部に固定されたスペースを確保し、そこに別のウィジェットを配置する例です。
目的
QScrollAreaのコンテンツの上に、常に表示されるヘッダーを配置する。
// mainwindow.h
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
#include <QMainWindow>
#include <QScrollArea>
#include <QLabel>
#include <QVBoxLayout>
#include <QPushButton> // 例として追加するボタン
class CustomScrollArea : public QScrollArea
{
Q_OBJECT
public:
explicit CustomScrollArea(QWidget *parent = nullptr);
protected:
// ビューポートのマージンが変更されたときに、ヘッダーウィジェットの位置を調整するため
void resizeEvent(QResizeEvent *event) override;
private:
QLabel *headerLabel; // 固定ヘッダーとして使うラベル
QWidget *contentWidget; // スクロールされるコンテンツ
};
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget *parent = nullptr);
~MainWindow();
};
#endif // MAINWINDOW_H
// mainwindow.cpp
#include "mainwindow.h"
CustomScrollArea::CustomScrollArea(QWidget *parent)
: QScrollArea(parent)
{
// ヘッダーラベルの作成とスタイル設定
headerLabel = new QLabel("これは固定ヘッダーです", this);
headerLabel->setStyleSheet("background-color: lightblue; padding: 10px; font-weight: bold;");
headerLabel->setAlignment(Qt::AlignCenter);
headerLabel->setFixedHeight(50); // ヘッダーの高さ
// スクロールされるコンテンツの作成
contentWidget = new QWidget(this);
QVBoxLayout *contentLayout = new QVBoxLayout(contentWidget);
for (int i = 0; i < 50; ++i) {
contentLayout->addWidget(new QLabel(QString("スクロールされるアイテム %1").arg(i + 1)));
}
contentLayout->addStretch(); // コンテンツが少ない場合に余白を埋める
// QScrollAreaにコンテンツウィジェットを設定
setWidget(contentWidget);
setWidgetResizable(true); // コンテンツウィジェットのサイズをスクロールエリアに合わせて自動調整
// ビューポートの上部にヘッダー分のマージンを設定
// ここで setViewportMargins() を呼び出すのがポイント
setViewportMargins(0, headerLabel->height(), 0, 0); // 左, 上, 右, 下
}
void CustomScrollArea::resizeEvent(QResizeEvent *event)
{
QScrollArea::resizeEvent(event); // 親クラスのresizeEventを呼び出す
// ヘッダーラベルの位置をビューポートの左上隅に合わせる
// contentsRect() はスクロールエリアのクライアント領域（スクロールバーを除く）
// その最上部にヘッダーを配置する
headerLabel->setGeometry(contentsRect().left(), contentsRect().top(), contentsRect().width(), headerLabel->height());
}
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
{
CustomScrollArea *scrollArea = new CustomScrollArea(this);
setCentralWidget(scrollArea);
setWindowTitle("Viewport Margins Example");
resize(400, 500);
}
MainWindow::~MainWindow()
{
}
解説
CustomScrollAreaをQScrollAreaから継承します。- コンストラクタで
headerLabelを作成し、固定ヘッダーとして使います。 - スクロールされるコンテンツとして
contentWidgetを作成し、複数のQLabelを追加します。 setWidget(contentWidget)でQScrollAreaにコンテンツを設定します。setViewportMargins(0, headerLabel->height(), 0, 0);が肝です。これにより、ビューポートの上部にheaderLabelの高さ分の余白が確保されます。この余白はスクロールの影響を受けません。resizeEvent()をオーバーライドし、headerLabel->setGeometry(...)を使って、常にQScrollAreaのクライアント領域の最上部にheaderLabelを配置します。contentsRect()はスクロールバーを除いた、ウィジェットが利用可能な領域を返します。これにより、ヘッダーはスクロールバーの隣に配置され、スクロールバーによって隠れることはありません。
この例は、QAbstractScrollAreaを直接サブクラス化し、ビューポートとマージン領域にコンテンツをどのように描画するかを制御する、より高度なシナリオを示します。これは、スプレッドシートの「固定行/列」のような動作を独自に実装する場合に類似しています。
ここでは、ビューポートの左側に固定の行番号エリアを、ビューポートにスクロール可能なテキストコンテンツを描画する簡単なテキストエディタのようなものを作成することを想定します。
// customtextscrollarea.h
#ifndef CUSTOMTEXTSCROLLAREA_H
#define CUSTOMTEXTSCROLLAREA_H
#include <QAbstractScrollArea>
#include <QTextEdit>
#include <QVBoxLayout>
#include <QLabel>
#include <QPainter>
#include <QScrollBar>
class LineNumberArea : public QWidget
{
Q_OBJECT
public:
explicit LineNumberArea(QAbstractScrollArea *parent = nullptr);
QSize sizeHint() const override;
protected:
void paintEvent(QPaintEvent *event) override;
private:
QAbstractScrollArea *scrollArea;
};
class CustomTextScrollArea : public QAbstractScrollArea
{
Q_OBJECT
public:
explicit CustomTextScrollArea(QWidget *parent = nullptr);
// スクロール可能なテキストコンテンツを公開
QTextEdit *textEdit() const { return m_textEdit; }
protected:
// ビューポートのコンテンツがスクロールされたときに呼ばれる
void scrollContentsBy(int dx, int dy) override;
// サイズ変更時にマージンと行番号エリアを更新
void resizeEvent(QResizeEvent *event) override;
// ビューポートイベントを処理
bool viewportEvent(QEvent *event) override;
private slots:
void updateLineNumberAreaWidth();
void updateLineNumberArea(const QRect &rect, int dy);
private:
LineNumberArea *m_lineNumberArea;
QTextEdit *m_textEdit;
int lineNumberAreaWidth();
};
#endif // CUSTOMTEXTSCROLLAREA_H
// customtextscrollarea.cpp
#include "customtextscrollarea.h"
LineNumberArea::LineNumberArea(QAbstractScrollArea *parent)
: QWidget(parent)
, scrollArea(parent)
{
// 背景色を設定して、視覚的に区別しやすくする
setAutoFillBackground(true);
QPalette p = palette();
p.setColor(QPalette::Window, Qt::lightGray);
setPalette(p);
}
QSize LineNumberArea::sizeHint() const
{
// 行番号エリアの推奨サイズ（幅）
// 実際には CustomTextScrollArea の lineNumberAreaWidth() を使う
return QSize(scrollArea->fontMetrics().horizontalAdvance(QLatin1Char('9')) * 5, 0); // 仮の幅
}
void LineNumberArea::paintEvent(QPaintEvent *event)
{
QPainter painter(this);
painter.fillRect(event->rect(), palette().window()); // 背景を描画
// ここでは単純な行番号を描画する例（実際のTextEditの行と同期させるには、より複雑なロジックが必要）
int yOffset = 0; // スクロールによって調整されるオフセット
if (auto *textScrollArea = qobject_cast<CustomTextScrollArea*>(scrollArea)) {
// QTextEdit のスクロール位置を取得してオフセットを計算する
// これはあくまで概念的な例であり、正確な同期には QTextEdit の内部構造をより深く理解する必要がある
yOffset = -textScrollArea->textEdit()->verticalScrollBar()->value();
}
// 可視範囲内の行番号を描画
// この例では単純な描画なので、実際のTextEditの行と正確に同期しない可能性あり
QFontMetrics fm = painter.fontMetrics();
int fontHeight = fm.height();
for (int i = 1; ; ++i) {
QRect lineRect(0, yOffset + (i - 1) * fontHeight, width(), fontHeight);
if (lineRect.top() > event->rect().bottom()) break; // 描画範囲外になったら終了
if (lineRect.bottom() >= event->rect().top()) { // 描画範囲内なら描画
painter.setPen(Qt::darkGray);
painter.drawText(lineRect.adjusted(0, 0, -5, 0), Qt::AlignRight | Qt::AlignVCenter, QString::number(i));
}
}
}
CustomTextScrollArea::CustomTextScrollArea(QWidget *parent)
: QAbstractScrollArea(parent)
{
m_lineNumberArea = new LineNumberArea(this); // 行番号エリアウィジェット
m_textEdit = new QTextEdit(viewport()); // ビューポートにテキストエディタを設定
// QTextEdit をビューポートの子として設定（setViewport() は QAbstractScrollArea には無い）
// QScrollArea では setWidget() が内部で setViewport() と同様の処理を行う
// QAbstractScrollArea を直接使う場合、ビューポートの子ウィジェットの管理は開発者側で行う
// ここでは単に viewport() を親として QTextEdit を作成している
// そして、QTextEdit のサイズと位置を resizeEvent で管理する
// setViewportMargins() を使用して、行番号エリア分のマージンを左側に確保
setViewportMargins(lineNumberAreaWidth(), 0, 0, 0);
// シグナルとスロットの接続
// QTextEdit のスクロールや内容変更に応じて行番号エリアを更新
connect(m_textEdit->verticalScrollBar(), &QScrollBar::valueChanged, this, &CustomTextScrollArea::updateLineNumberArea);
connect(m_textEdit, &QTextEdit::textChanged, this, &CustomTextScrollArea::updateLineNumberAreaWidth);
connect(m_textEdit, &QTextEdit::cursorPositionChanged, this, &CustomTextScrollArea::updateLineNumberArea);
// QAbstractScrollArea のスクロールバーを QTextEdit のスクロールバーに接続
setVerticalScrollBar(m_textEdit->verticalScrollBar());
setHorizontalScrollBar(m_textEdit->horizontalScrollBar());
}
int CustomTextScrollArea::lineNumberAreaWidth()
{
// テキストエディタの行数に基づいて行番号エリアの幅を計算
int digits = 1;
int maxBlock = qMax(1, m_textEdit->document()->blockCount());
while (maxBlock >= 10) {
maxBlock /= 10;
++digits;
}
int space = 3 + fontMetrics().horizontalAdvance(QLatin1Char('9')) * digits;
return space;
}
void CustomTextScrollArea::updateLineNumberAreaWidth()
{
// 行番号エリアの幅を再計算し、ビューポートのマージンを更新
setViewportMargins(lineNumberAreaWidth(), 0, 0, 0);
// マージン変更後、レイアウトを更新するために再描画を要求
m_lineNumberArea->update();
}
void CustomTextScrollArea::updateLineNumberArea(const QRect &rect, int dy)
{
// 行番号エリアをスクロールさせる、または再描画する
if (dy) {
m_lineNumberArea->scroll(0, dy); // 垂直スクロール
} else {
m_lineNumberArea->update(0, rect.y(), m_lineNumberArea->width(), rect.height());
}
}
void CustomTextScrollArea::scrollContentsBy(int dx, int dy)
{
// この関数は QAbstractScrollArea のコンテンツがスクロールされたときに呼ばれます。
// ビューポートの子ウィジェット（m_textEdit）を移動させます。
m_textEdit->scroll(dx, dy);
// 行番号エリアも垂直方向に同期してスクロール
m_lineNumberArea->scroll(0, dy);
}
void CustomTextScrollArea::resizeEvent(QResizeEvent *event)
{
QAbstractScrollArea::resizeEvent(event);
// 行番号エリアのジオメトリを設定
QRect cr = contentsRect(); // スクロールバーを除く、このウィジェットが利用可能な領域
// 行番号エリアは左端、スクロールバーの上端から、計算された幅と高さ
m_lineNumberArea->setGeometry(cr.left(), cr.top(), lineNumberAreaWidth(), cr.height());
// QTextEdit のジオメトリは、ビューポートのサイズに合わせる
// viewport()->rect() はビューポート自体の現在の領域
// setViewportMargins() によって、この領域は既にマージン分縮小されている
m_textEdit->setGeometry(viewport()->rect());
}
bool CustomTextScrollArea::viewportEvent(QEvent *event)
{
// ビューポートからのイベントを処理
// 例えば、ビューポートのサイズ変更イベントなどを処理
if (event->type() == QEvent::Resize) {
// QTextEdit のサイズがビューポートのサイズに合うように調整
m_textEdit->setGeometry(viewport()->rect());
}
return QAbstractScrollArea::viewportEvent(event);
}
// main.cpp
#include <QApplication>
#include "customtextscrollarea.h"
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
CustomTextScrollArea scrollArea;
scrollArea.textEdit()->setPlainText("これは複数行のテキストです。\n"
"各行に行番号が表示されます。\n"
"もっと多くの行を追加して、スクロールを試してみてください。\n"
"----------------------------------------\n"
"Line 5\nLine 6\nLine 7\nLine 8\nLine 9\nLine 10\n"
"Line 11\nLine 12\nLine 13\nLine 14\nLine 15\n"
"Line 16\nLine 17\nLine 18\nLine 19\nLine 20\n"
"Line 21\nLine 22\nLine 23\nLine 24\nLine 25\n"
"Line 26\nLine 27\nLine 28\nLine 29\nLine 30\n"
"Line 31\nLine 32\nLine 33\nLine 34\nLine 35\n"
"Line 36\nLine 37\nLine 38\nLine 39\nLine 40\n"
"Line 41\nLine 42\nLine 43\nLine 44\nLine 45\n"
"Line 46\nLine 47\nLine 48\nLine 49\nLine 50\n");
scrollArea.setWindowTitle("Custom Text Scroll Area with Line Numbers");
scrollArea.resize(600, 400);
scrollArea.show();
return a.exec();
}
解説
- LineNumberAreaウィジェット
行番号を描画するためのカスタムウィジェットです。これはQAbstractScrollAreaの子として作成され、paintEventで描画を行います。 - CustomTextScrollAreaクラス
QAbstractScrollAreaを直接継承します。 - m_textEditの作成
QTextEditをビューポートの子として作成します。QAbstractScrollAreaではQScrollArea::setWidget()のような便利なメソッドがないため、ビューポート内のコンテンツの管理は開発者自身が行う必要があります。 - setViewportMargins(lineNumberAreaWidth(), 0, 0, 0);
ここで行番号エリアの幅分、左側にマージンを設定しています。 - resizeEvent()
m_lineNumberArea->setGeometry(...)で行番号エリアの位置とサイズを、QAbstractScrollAreaの左側のマージン領域に合わせて設定します。contentsRect()を使って、スクロールバーの領域を考慮した位置を計算します。m_textEdit->setGeometry(viewport()->rect());でQTextEditのサイズと位置をビューポートの領域に合わせます。viewport()->rect()は、setViewportMargins()で設定されたマージンを考慮した、実際にコンテンツが表示される領域です。
- scrollContentsBy(int dx, int dy)
この重要なオーバーライド関数は、スクロールイベントが発生したときに呼ばれます。ここで、ビューポート内のコンテンツ（m_textEdit）とマージン領域の固定コンテンツ（m_lineNumberArea、垂直スクロールのみ同期）をどのように移動させるかを制御します。m_textEdit->scroll(dx, dy)でQTextEdit自体をスクロールさせ、m_lineNumberArea->scroll(0, dy)で行番号エリアを垂直方向にのみ同期させています。 - スクロールバーの接続
setVerticalScrollBar(m_textEdit->verticalScrollBar());とsetHorizontalScrollBar(m_textEdit->horizontalScrollBar());を呼び出すことで、QAbstractScrollAreaのスクロールバーがQTextEditのスクロール状態と同期するようにします。 - updateLineNumberAreaWidth()とupdateLineNumberArea()
QTextEditのコンテンツが変更されたり、カーソルの位置が変わったりしたときに、行番号エリアの幅を更新したり、再描画を促したりします。
setViewportMargins() は「ビューポートの内側にスペースを確保する」というアプローチですが、代替手法は「スクロールエリアの外側に固定要素を配置する」というアプローチになります。
QLayout を使用して固定要素とスクロールエリアを組み合わせる
これは最も一般的で推奨される方法であり、Qt の強力なレイアウトシステムを活用します。スクロールエリアと、固定したいウィジェットを別のレイアウトに配置し、そのレイアウトをメインのウィジェットに設定します。
メリット
setViewportMargins()を使って手動で位置を調整する必要がない。- 異なる画面サイズや解像度に対して、レイアウトが柔軟に調整される。
- Qt のレイアウトシステムが自動的にウィジェットの配置とサイズを管理するため、コードが簡潔で保守しやすい。
例
ヘッダーとフッターを持つスクロールエリア
// mainwindow.h
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
#include <QMainWindow>
#include <QScrollArea>
#include <QLabel>
#include <QVBoxLayout>
#include <QWidget>
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget *parent = nullptr);
~MainWindow();
};
#endif // MAINWINDOW_H
// mainwindow.cpp
#include "mainwindow.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
{
// メインのコンテナウィジェットと垂直レイアウト
QWidget *mainWidget = new QWidget(this);
QVBoxLayout *mainLayout = new QVBoxLayout(mainWidget);
// 1. 固定ヘッダーの作成
QLabel *headerLabel = new QLabel("これは固定ヘッダーです", this);
headerLabel->setStyleSheet("background-color: lightblue; padding: 10px; font-weight: bold;");
headerLabel->setAlignment(Qt::AlignCenter);
headerLabel->setFixedHeight(50);
mainLayout->addWidget(headerLabel); // レイアウトの最上部にヘッダーを追加
// 2. スクロールエリアの作成
QScrollArea *scrollArea = new QScrollArea(this);
scrollArea->setWidgetResizable(true); // コンテンツウィジェットのサイズをスクロールエリアに合わせて調整
// スクロールされるコンテンツウィジェットの作成
QWidget *contentWidget = new QWidget(scrollArea);
QVBoxLayout *contentLayout = new QVBoxLayout(contentWidget);
for (int i = 0; i < 50; ++i) {
contentLayout->addWidget(new QLabel(QString("スクロールされるアイテム %1").arg(i + 1)));
}
contentLayout->addStretch(); // コンテンツが少ない場合に余白を埋める
scrollArea->setWidget(contentWidget); // スクロールエリアにコンテンツを設定
mainLayout->addWidget(scrollArea); // レイアウトの中央にスクロールエリアを追加
// 3. 固定フッターの作成 (オプション)
QLabel *footerLabel = new QLabel("これは固定フッターです", this);
footerLabel->setStyleSheet("background-color: lightgreen; padding: 10px; font-weight: bold;");
footerLabel->setAlignment(Qt::AlignCenter);
footerLabel->setFixedHeight(40);
mainLayout->addWidget(footerLabel); // レイアウトの最下部にフッターを追加
setCentralWidget(mainWidget); // メインウィンドウの中央ウィジェットに設定
setWindowTitle("Layout with Fixed Header/Footer");
resize(400, 500);
}
MainWindow::~MainWindow()
{
}
この方法の利点
- 柔軟性
ヘッダー、フッター、サイドバーなど、複数の固定要素を簡単に追加できます。 - 堅牢性
Qt のレイアウトシステムがウィジェットの配置を自動的に処理するため、異なるフォントサイズ、スタイル、画面解像度などにも対応しやすいです。 - シンプルさ
setViewportMargins()とresizeEvent()のオーバーライドといった複雑な処理が不要になります。
QGraphicsView フレームワークの利用
より複雑なカスタム描画やインタラクションが必要な場合、QGraphicsView は強力な代替手段となります。QGraphicsView は QGraphicsScene の内容を表示するためのウィジェットであり、シーン内のアイテムを自由に配置、移動、変換、インタラクションさせることができます。
メリット
- 固定要素とスクロール要素を同じシーン内で管理し、ビューポートに対して相対的に配置できる。
- カスタム描画とインタラクションを高度に制御できる。
- ズーム、パン、回転などの高度なビュー操作が容易。
- 多数のアイテムを扱う際のパフォーマンスが優れている。
QGraphicsSceneを作成し、スクロールされるコンテンツ（例:QGraphicsTextItem、カスタムのQGraphicsItemなど）を追加します。- 固定したいヘッダーやフッターの要素も
QGraphicsItemとしてシーンに追加しますが、これらをビューの座標系に固定するようにロジックを記述します。QGraphicsItem::ItemIgnoresTransformationsフラグを使用して、アイテムがビューの変換（ズーム、パン）の影響を受けないようにすることができます。QGraphicsView::mapToScene()およびQGraphicsView::mapFromScene()を使用して、ビュー座標とシーン座標間の変換を行います。QGraphicsViewのscrollContentsBy()をオーバーライドし、スクロールイベントが行われたときに固定要素の位置を調整することもできます。
QGraphicsViewを作成し、setScene()でシーンを設定します。
カスタムペインティングによる直接描画
QAbstractScrollArea をサブクラス化し、その paintEvent() で直接描画を行う方法です。この場合、固定要素とスクロール要素を同じ paintEvent() 内で描画しますが、スクロールバーの値に基づいてスクロール要素の位置をオフセットする必要があります。
メリット
- 非常に軽量な描画を実現できる。
- 最も低レベルな制御が可能。
デメリット
- QGraphicsViewの方が多くの場合、性能や機能面で優れる。
- ウィジェットを直接配置するよりも柔軟性が低い。
- 複雑な描画やインタラクションの実装が非常に手間がかかる。
例
（概念的なコード）
// MyCustomPainterScrollArea.h
class MyCustomPainterScrollArea : public QAbstractScrollArea
{
Q_OBJECT
public:
explicit MyCustomPainterScrollArea(QWidget *parent = nullptr);
protected:
void paintEvent(QPaintEvent *event) override;
void scrollContentsBy(int dx, int dy) override;
// 必要に応じて resizeEvent などもオーバーライド
private:
// 固定ヘッダーのテキストなど
QString fixedHeaderText;
// スクロールされるコンテンツデータ（例: QList<QString>）
QList<QString> scrollableContent;
int headerHeight = 50;
};
// MyCustomPainterScrollArea.cpp
#include "MyCustomPainterScrollArea.h"
#include <QPainter>
MyCustomPainterScrollArea::MyCustomPainterScrollArea(QWidget *parent)
: QAbstractScrollArea(parent)
{
fixedHeaderText = "カスタム描画ヘッダー";
for (int i = 0; i < 100; ++i) {
scrollableContent << QString("スクロール可能なデータ行 %1").arg(i + 1);
}
// スクロールバーの範囲を設定
// 例: 垂直方向の全コンテンツの高さに基づいて設定
verticalScrollBar()->setRange(0, fontMetrics().height() * scrollableContent.size() - (viewport()->height() - headerHeight));
}
void MyCustomPainterScrollArea::paintEvent(QPaintEvent *event)
{
QPainter painter(viewport()); // ビューポートに描画
// 1. 固定ヘッダーの描画
// ビューポートの原点 (0,0) を基準に描画
painter.fillRect(0, 0, viewport()->width(), headerHeight, Qt::blue);
painter.setPen(Qt::white);
painter.drawText(QRect(0, 0, viewport()->width(), headerHeight), Qt::AlignCenter, fixedHeaderText);
// 2. スクロールされるコンテンツの描画
// 現在のスクロール位置を考慮してコンテンツを描画
int currentScrollY = verticalScrollBar()->value(); // 垂直スクロールバーの値
QFontMetrics fm = painter.fontMetrics();
int lineHeight = fm.height();
// ヘッダーの下から描画を開始
int yOffset = headerHeight - currentScrollY;
for (int i = 0; i < scrollableContent.size(); ++i) {
QRect lineRect(0, yOffset + i * lineHeight, viewport()->width(), lineHeight);
// 可視領域内の行のみを描画する最適化
if (event->rect().intersects(lineRect)) {
painter.setPen(Qt::black);
painter.drawText(lineRect.adjusted(5, 0, -5, 0), Qt::AlignLeft | Qt::AlignVCenter, scrollableContent[i]);
}
}
}
void MyCustomPainterScrollArea::scrollContentsBy(int dx, int dy)
{
// ビューポートをスクロール
// QAbstractScrollArea はこの関数を呼び出すことで、ビューポートのコンテンツを移動させる
// 実際には viewport()->scroll(dx, dy); を呼び出すか、
// paintEventでスクロールバーの値を参照して描画を調整する
viewport()->scroll(dx, dy); // これで描画が再要求される
// マージン部分の再描画は必要ない（固定されているため）
// paintEvent が呼ばれる際にスクロール値に応じてコンテンツ描画を調整する
}
注意
このカスタム描画のアプローチは、非常にパフォーマンスが求められる特定のグラフィカルアプリケーションや、Qt の既存ウィジェットで実現できない独自の描画が必要な場合に限定して検討すべきです。ほとんどのユースケースでは、QLayout を使用する方法がはるかに簡単で堅牢です。
QAbstractScrollArea::setViewportMargins() は特定のニッチな用途で有用ですが、多くの場合、Qt の強力なレイアウトシステムを使用したり、より高度な描画が必要な場合は QGraphicsView フレームワークを利用したりする方が、より良い設計と実装につながります。
- 非常に低レベルな描画制御と最適化
QAbstractScrollAreaのサブクラス化とpaintEvent()での直接描画（ただし、これは最後の手段と考えるべきです）。 - 高度なカスタム描画/インタラクション
QGraphicsView/QGraphicsSceneフレームワーク。 - 一般的なUI
QLayout(QVBoxLayout, QHBoxLayout, QGridLayout) とQScrollAreaの組み合わせが最も推奨されます。