QAbstractScrollArea::viewport()だけじゃない！Qtスクロール機能の代替手法と選び方

QAbstractScrollArea::viewport() とは何か

QAbstractScrollArea は、スクロール可能な領域を提供するQtのウィジェットの基底クラスです。このクラスは、その名前が示す通り「抽象的」であり、直接使うというよりは、QScrollArea や QAbstractItemView (例えば QListView, QTableView, QTreeView など) のような具体的なスクロールウィジェットの基礎となっています。

QAbstractScrollArea::viewport() メソッドは、このスクロール可能な領域の中心となるウィジェットへのポインタを返します。この「ビューポート (viewport)」とは、スクロールされるコンテンツが実際に表示される領域を指します。

もっと分かりやすく言うと、以下のようになります。

• QAbstractScrollArea は、ビューポートの他に、垂直・水平スクロールバーを管理します。
• ユーザーがスクロールバーを動かすと、このビューポートを通して見える内容が変化します。
• 大きな内容（コンテンツ）があるが、それを一度に全て表示できない場合、QAbstractScrollArea はその内容の一部を「窓」を通して表示します。この「窓」がビューポートです。

viewport() の役割と重要性

1. 描画のターゲット: スクロールされるコンテンツの実際の描画は、このビューポートウィジェット上で行われます。QAbstractScrollArea のサブクラスでカスタム描画を行う場合、通常は viewport() が返すウィジェットに対して paintEvent() を実装したり、viewport()->update() を呼び出したりします。

2. イベントハンドリング: ビューポート内で発生するマウスイベントやキーイベントなどのほとんどのイベントは、まずビューポートウィジェットに送られます。QAbstractScrollArea のサブクラスでは、これらのビューポートイベントを viewportEvent() メソッドで処理できます。

3. コンテンツの配置: QScrollArea のように、スクロールさせたい QWidget をビューポートの子として設定することで、スクロール領域の管理をQtに任せることができます。例えば、QScrollArea::setWidget() を呼び出すと、内部的にそのウィジェットがビューポートの子として設定されます。これにより、スクロールバーの動きに合わせてウィジェットを移動させるだけで、描画範囲の計算などを自分で行う必要がなくなります。

4. カスタマイズ: setViewport() メソッドを使って、カスタムのウィジェットをビューポートとして設定することも可能です。これは、例えばOpenGLウィジェットをビューポートとして使用したい場合などに役立ちます。

QScrollArea を例にとると、内部的には QAbstractScrollArea を継承しており、あなたが setWidget(myBigWidget) のように大きなウィジェットを設定すると、その myBigWidget が QScrollArea のビューポートの子になります。

QAbstractScrollArea を直接サブクラス化してカスタムスクロールエリアを作成する場合、あなたは以下のことを行う必要があります。

• ビューポートの内容を更新するために、update() ではなく viewport()->update() を使用する。
• ビューポートで受信したイベント（特にリサイズイベント）を viewportEvent() で処理する。
• スクロールバーの値に基づいて、ビューポートにコンテンツを描画する。
• スクロールバーの範囲、値、ページステップなどを設定し、動きを追跡する。

---

QAbstractScrollArea::viewport() に関連する一般的なエラーとトラブルシューティング

QAbstractScrollArea はスクロール可能な領域の基底クラスであり、viewport() メソッドはその描画対象となるウィジェットを返します。このメカニズムを正しく理解していないと、意図しない表示や動作を引き起こすことがあります。

スクロールバーが表示されない、または正しく動作しない

エラー/症状

• スクロールバーの範囲（最大値）が正しく設定されていない。
• スクロールバーが表示されるが、ドラッグしてもコンテンツがスクロールしない。
• コンテンツがビューポートより大きいにもかかわらず、スクロールバーが表示されない。

原因

• ビューポートにレイアウトが適用されていない (特に QScrollArea)
  QScrollArea::setWidget() を使用している場合、設定したウィジェットにレイアウトが適用されていないと、ウィジェットのサイズが正しく計算されず、スクロールバーが表示されないことがあります。
• viewport()->update() の不足
  コンテンツが変更されたときに、ビューポートの再描画をトリガーするために viewport()->update() または viewport()->repaint() を呼び出す必要があります。単に update() を呼び出すだけでは、スクロールエリア全体は更新されますが、ビューポートの内容が適切に描画されないことがあります。
• scrollContentsBy() の未実装/誤実装
  QAbstractScrollArea を直接サブクラス化している場合、スクロールバーの値を変更したときにビューポートの内容を移動させるための scrollContentsBy() メソッドをオーバーライドする必要があります。
• スクロールバーのポリシーが Qt::ScrollBarAlwaysOff に設定されている
  明示的にスクロールバーを非表示にする設定になっている可能性があります。
• コンテンツのサイズが未設定または不適切
  QAbstractScrollArea は、ビューポートに表示されるコンテンツのサイズに基づいてスクロールバーの範囲を決定します。コンテンツのサイズが設定されていない、またはビューポートのサイズ以下である場合、スクロールバーは不要と判断され表示されません。

トラブルシューティング

• QScrollArea の場合、setWidget() の使用とレイアウトの適用
  QScrollArea を使う場合は、スクロールしたいウィジェットを setWidget() で設定し、そのウィジェットに適切なレイアウト（QVBoxLayout や QGridLayout など）を適用してください。
• コンテンツ変更時の viewport()->update()
  コンテンツが変更されたり、スクロール位置をプログラムで変更したりした場合は、必ず viewport()->update() を呼び出します。
• scrollContentsBy() の実装 (カスタム QAbstractScrollArea)
  

  void MyScrollArea::scrollContentsBy(int dx, int dy) {
      // ビューポートのコンテンツを移動させる
      // QPainter::setWindow() などで座標系を調整するか、
      // ビューポートの子ウィジェットの位置を調整する
      viewport()->scroll(dx, dy); // シンプルな例
      // 必要に応じて、ビューポートの再描画をトリガー
      viewport()->update();
  }
  

• スクロールバーポリシーの確認
  setHorizontalScrollBarPolicy() や setVerticalScrollBarPolicy() を Qt::ScrollBarAsNeeded (デフォルト) または Qt::ScrollBarAlwaysOn に設定します。
• コンテンツの sizeHint() または minimumSizeHint() を正しく実装する
  ビューポートに表示されるカスタムウィジェットの場合、そのコンテンツの推奨サイズまたは最小サイズを正確に返すように sizeHint() や minimumSizeHint() をオーバーライドします。

描画がおかしい、または内容が更新されない

エラー/症状

• 背景色が透明になってしまう、または意図しない色になる。
• コンテンツの一部が描画されない。
• 描画がちらつく。
• スクロールしても内容が残像のように見える。

原因

• QSS の適用ミス
  QScrollArea やそのビューポートにQSSを適用する際に、QScrollArea { background: transparent; } のようにすると、子ウィジェットにも影響が出て描画がおかしくなることがあります。
• autoFillBackground の問題
  QAbstractScrollArea のビューポートはデフォルトで autoFillBackground が true に設定され、QPalette::Base ロールで背景を塗りつぶします。これにより、ウィジェットが背景を自分で描画しない場合に適切な背景色を提供しますが、QSS (Qt Style Sheets) やカスタム描画で透明度を扱いたい場合に問題を引き起こすことがあります。
• paintEvent() の誤った実装
  QAbstractScrollArea をサブクラス化してカスタム描画を行う場合、paintEvent() はビューポートウィジェットに対して行われるべきです。QPainter を this (つまり QAbstractScrollArea 自身) に対して作成してしまうと、ビューポートではなくスクロールエリア全体の描画になってしまいます。

トラブルシューティング

• QSS の適用範囲
  QSSを適用する際は、それが意図したウィジェット（QScrollArea 自体か、QScrollArea::viewport か、その中の特定のウィジェットか）にのみ適用されるようにセレクタを正確に指定します。
• autoFillBackground の調整
  
  • カスタム描画で完全に背景を制御したい場合は、viewport()->setAutoFillBackground(false); を設定し、paintEvent() 内で背景を自分で描画します。
  • QSSで背景を設定したい場合は、viewport() に直接QSSを適用するか、QScrollArea::viewport { background-color: transparent; } のようにセレクタを明示的に指定します。ただし、Qtのスタイルによっては、QPalette::Base の背景描画とQSSが干渉することがあるので注意が必要です。
• viewport()->update() の使用
  描画内容に変更があった場合は、必ず viewport()->update() を呼び出してビューポートの再描画をトリガーします。
• paintEvent() は viewport() に対して行う
  

  void MyCustomScrollArea::paintEvent(QPaintEvent *event) {
      // QAbstractScrollArea::paintEvent(event); // 必要に応じて基底クラスを呼び出す
      QPainter painter(viewport()); // ここが重要: ビューポートに対して描画する
      // ... ここでカスタム描画コードを書く ...
  }
  

  カスタム描画をする場合、通常は QAbstractScrollArea の paintEvent() ではなく、viewport() を継承したカスタムウィジェットの paintEvent() で描画を行います。

イベントハンドリングの問題

エラー/症状

• ビューポート全体に対するマウスイベントをキャッチしたいが、うまくいかない。
• ビューポート内のウィジェットがマウスイベントやキーイベントを受け取らない。

原因

• viewportEvent() の誤解
  QAbstractScrollArea::viewportEvent() は、ビューポートに対する様々なイベント（サイズ変更、移動など）を処理するために使用されますが、一般的なマウスイベントやキーイベントは通常、直接ビューポートウィジェットに送信されます。
• イベントの伝播
  QAbstractScrollArea はイベントを処理する前に、まずビューポートにイベントを渡します。ビューポート内の特定のウィジェットにイベントハンドリングが必要な場合、そのウィジェットにイベントフィルターをインストールするか、サブクラス化してイベントをオーバーライドする必要があります。

トラブルシューティング

• viewportEvent() の適切な使用
  viewportEvent() は、主にビューポート自体の状態変化（サイズ変更、移動など）に対応するために使用します。例えば、ビューポートのサイズ変更に応じてコンテンツのレイアウトを調整する場合などです。
• ビューポート内のウィジェットのイベント処理
  
  • ビューポート内の個々のウィジェットでイベントを処理したい場合、そのウィジェットをサブクラス化して mousePressEvent() などをオーバーライドするか、イベントフィルターを使用します。
  • もしカスタムのビューポートウィジェットを使っているなら、そのウィジェットでイベントをオーバーライドします。

メモリリーク/クラッシュ

エラー/症状

• メモリ使用量が増加する。
• アプリケーションがクラッシュする。

原因

• 無効なポインタへのアクセス
  viewport() が返すポインタが nullptr の状態であるにもかかわらず、そのメソッドを呼び出そうとする。これは、QAbstractScrollArea のコンストラクタが完了する前に viewport() にアクセスしようとした場合や、setViewport(nullptr) を呼び出した後などに起こりえます。
• setViewport() で設定したウィジェットのライフサイクル管理ミス
  setViewport() を呼び出すと、Qtは通常、設定されたウィジェットの所有権を引き受け、親ウィジェットが破棄されるときにそのウィジェットも自動的に破棄します。しかし、自分でウィジェットを作成し、そのライフサイクルを誤って管理すると、二重解放やメモリリークの原因になることがあります。

• デストラクタでのクリーンアップ
  QAbstractScrollArea をサブクラス化していて、自分で動的に確保したリソースがある場合は、デストラクタで適切に解放します。
• nullptr チェック
  viewport() を呼び出した結果が nullptr でないことを確認してから、そのポインタを使用します。特に、コンストラクタ内で viewport() にアクセスする場合は注意が必要です。
• 所有権の理解
  QScrollArea::setWidget() や QAbstractScrollArea::setViewport() を使用する場合、Qtが自動的にウィジェットの所有権を引き継ぐことを覚えておきましょう。自分で delete する必要はありません。

• イベントフィルターの利用
  複雑なイベント処理が必要な場合、installEventFilter() を使用して、ビューポートやその中のウィジェットのイベントを監視し、デバッグすることができます。
• Qt Designer で試す
  シンプルなケースであれば、Qt Designer で QScrollArea を配置し、その中にウィジェットやレイアウトを追加して、スクロールバーが正常に動作するかどうかを確認できます。これにより、コード側の問題なのか、UI設定の問題なのかを切り分けられます。
• qDebug() を活用する
  viewport()->size() や horizontalScrollBar()->value() などの値を qDebug() で出力し、期待通りの値になっているか確認します。
• Qtのドキュメントを参照する
  QAbstractScrollArea や QScrollArea の公式ドキュメントには、多くの情報と例が記載されています。特に、各メソッドの具体的な動作や所有権に関する記述を確認してください。
• 最小限の再現コードを作成する
  問題が発生したときに、その問題を再現できる最小限のコードスニペットを作成します。これにより、原因の特定が容易になります。

---

QAbstractScrollArea は抽象クラスなので、直接インスタンス化して使うことは稀です。通常は QScrollArea のようにすでに実装されているサブクラスを使うか、独自のカスタムスクロール可能なウィジェットを作成するために QAbstractScrollArea を継承します。

ここでは、両方のシナリオで viewport() の概念がどのように関わるかを示す例を挙げます。

例1: QScrollArea の使用（最も一般的）

QScrollArea は、任意の QWidget をビューポートとして表示し、そのコンテンツがビューポートより大きい場合に自動的にスクロールバーを提供する、最も一般的なスクロールウィジェットです。

// main.cpp
#include <QApplication>
#include <QMainWindow>
#include <QScrollArea>
#include <QLabel>
#include <QVBoxLayout>
#include <QPushButton>

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

    QMainWindow window;
    window.setWindowTitle("QScrollArea Viewport Example");
    window.resize(400, 300);

    // スクロールされるコンテンツとなるウィジェット
    // ここでは単純なQLabelを使用しますが、任意の複雑なウィジェットで構いません。
    QLabel *longTextLabel = new QLabel("これは非常に長いテキストです。\n"
                                       "たくさんの行があります。\n"
                                       "スクロールしないと全て見えません。\n"
                                       "スクロールバーの動作を確認してください。\n"
                                       "...\n" // 多くの行をシミュレート
                                       "行 1\n行 2\n行 3\n行 4\n行 5\n行 6\n行 7\n行 8\n行 9\n行 10\n"
                                       "行 11\n行 12\n行 13\n行 14\n行 15\n行 16\n行 17\n行 18\n行 19\n行 20\n"
                                       "行 21\n行 22\n行 23\n行 24\n行 25\n行 26\n行 27\n行 28\n行 29\n行 30\n"
                                       "行 31\n行 32\n行 33\n行 34\n行 35\n行 36\n行 37\n行 38\n行 39\n行 40\n"
                                       "行 41\n行 42\n行 43\n行 44\n行 45\n行 46\n行 47\n行 48\n行 49\n行 50\n", &window);
    longTextLabel->setWordWrap(true); // 長い行を自動で折り返す

    // QScrollArea を作成
    QScrollArea *scrollArea = new QScrollArea(&window);

    // スクロールされるウィジェットを QScrollArea に設定
    // これにより、longTextLabel が scrollArea の viewport の子になります。
    scrollArea->setWidget(longTextLabel);

    // setWidget() を使用すると、longTextLabel のサイズに合わせて
    // viewport のサイズを調整するかどうかを設定できます。
    // true にすると、longTextLabel がビューポートに収まるように自動調整されます。
    // しかし、スクロールエリアの目的はコンテンツがビューポートより大きい場合にスクロールすることなので、
    // ここでは false のままにするか、明示的に longTextLabel の最小サイズを設定して、
    // viewport のサイズより大きくします。
    scrollArea->setWidgetResizable(true); // ウィジェットのサイズに合わせてビューポートもリサイズされる

    // スクロールバーのポリシーを設定 (デフォルトは AsNeeded)
    scrollArea->setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);
    scrollArea->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);

    // メインウィンドウの中央ウィジェットとして設定
    window.setCentralWidget(scrollArea);

    window.show();

    // デバッグ目的で、viewport へのポインタを取得して情報を表示
    // この viewport は QScrollArea が内部的に作成した QWidget です。
    QWidget *viewportWidget = scrollArea->viewport();
    if (viewportWidget) {
        qDebug() << "Viewport widget class name:" << viewportWidget->metaObject()->className();
        qDebug() << "Viewport widget size:" << viewportWidget->size();
    }

    return app.exec();
}

解説
この例では、QScrollArea を使用しています。QScrollArea::setWidget(longTextLabel) を呼び出すと、longTextLabel が QScrollArea の内部で作成されたビューポートウィジェットの子になります。開発者は通常、ビューポートウィジェット自体を直接操作することはあまりありませんが、scrollArea->viewport() を通じてそのポインタを取得し、イベントフィルターをインストールしたり、カスタム描画のターゲットにしたりすることが可能です。

これは、QAbstractScrollArea を直接継承して、カスタムの描画ロジックを持つスクロールエリアを作成する例です。ここでは、非常に大きな仮想的なグリッドを描画し、スクロールバーでその表示領域を制御します。

// MyCustomScrollArea.h
#ifndef MYCUSTOMSCROLLAREA_H
#define MYCUSTOMSCROLLAREA_H

#include <QAbstractScrollArea>
#include <QPainter>
#include <QScrollBar> // スクロールバーを直接操作するため

class MyCustomScrollArea : public QAbstractScrollArea
{
    Q_OBJECT

public:
    explicit MyCustomScrollArea(QWidget *parent = nullptr);

    // 仮想コンテンツのサイズを設定
    void setContentSize(const QSize &size);

protected:
    // ビューポートのイベントハンドリング (特にリサイズイベント)
    bool viewportEvent(QEvent *event) override;

    // スクロールバーの移動に応じてコンテンツをスクロールさせる
    void scrollContentsBy(int dx, int dy) override;

    // ビューポートに描画するためのイベントハンドラ
    // 注意: これは MyCustomScrollArea の paintEvent() ではなく、
    // ビューポートウィジェットの paintEvent() になります。
    // 通常は、viewport() が返すカスタムウィジェットの paintEvent() をオーバーライドします。
    // しかし、QAbstractScrollArea は viewportEvent() で paint イベントを処理するよう
    // 再マッピングできるため、ここでは描画ロジックをここに記述します。
    // より良い設計は、CustomViewportWidget クラスを作成し、それを setViewport() で設定することです。
    // 今回は簡略化のため、この方法を採用します。
    void paintEvent(QPaintEvent *event) override; // これは QAbstractScrollArea の paintEvent

private:
    QSize m_contentSize; // 仮想コンテンツ全体のサイズ

    void updateScrollBars();
};

#endif // MYCUSTOMSCROLLAREA_H

// MyCustomScrollArea.cpp
#include "MyCustomScrollArea.h"
#include <QDebug>
#include <QResizeEvent>

MyCustomScrollArea::MyCustomScrollArea(QWidget *parent)
    : QAbstractScrollArea(parent),
      m_contentSize(2000, 1500) // デフォルトの仮想コンテンツサイズ
{
    // ビューポートの背景を自動で塗りつぶす設定（デフォルトはtrue）
    // カスタム描画で全体を塗りつぶす場合はfalseにしても良い
    viewport()->setAutoFillBackground(true);

    // スクロールバーのポリシー設定 (デフォルトは Qt::ScrollBarAsNeeded)
    setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);
    setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);

    // スクロールバーの範囲を初期化
    updateScrollBars();
}

void MyCustomScrollArea::setContentSize(const QSize &size)
{
    if (m_contentSize != size) {
        m_contentSize = size;
        updateScrollBars(); // コンテンツサイズが変わったらスクロールバーを更新
        viewport()->update(); // ビューポートの再描画を要求
    }
}

bool MyCustomScrollArea::viewportEvent(QEvent *event)
{
    if (event->type() == QEvent::Resize) {
        // ビューポートがリサイズされたら、スクロールバーの範囲を更新
        updateScrollBars();
    }
    return QAbstractScrollArea::viewportEvent(event); // 基底クラスのハンドラを呼び出す
}

void MyCustomScrollArea::scrollContentsBy(int dx, int dy)
{
    // スクロールバーの値の変更に応じて、ビューポートの内容を移動させる
    // QPainter のオフセットを計算する
    viewport()->scroll(dx, dy); // これは QWidget::scroll() を呼び出すもので、ビューポートを移動させる
                               // 自前の描画では、このオフセットを paintEvent で考慮する必要がある
    viewport()->update(); // スクロールに伴ってビューポートの再描画を要求
}

void MyCustomScrollArea::paintEvent(QPaintEvent *event)
{
    // QAbstractScrollArea の paintEvent を呼び出すことで、フレームなどが描画される
    QAbstractScrollArea::paintEvent(event);

    QPainter painter(viewport()); // ここが重要: ビューポートに対して描画する

    // 現在のスクロールオフセットを取得
    int hOffset = horizontalScrollBar()->value();
    int vOffset = verticalScrollBar()->value();

    // 描画するグリッドのセルサイズ
    const int cellSize = 50;

    // ビューポートの表示範囲
    QRect visibleRect = viewport()->rect();

    // グリッドの描画
    painter.setPen(Qt::lightGray);

    // 垂直線
    for (int x = -hOffset % cellSize; x < visibleRect.width(); x += cellSize) {
        painter.drawLine(x, 0, x, visibleRect.height());
    }

    // 水平線
    for (int y = -vOffset % cellSize; y < visibleRect.height(); y += cellSize) {
        painter.drawLine(0, y, visibleRect.width(), y);
    }

    // デバッグ表示：現在のスクロール位置
    painter.setPen(Qt::red);
    painter.drawText(10, 20, QString("Scroll X: %1, Y: %2").arg(hOffset).arg(vOffset));
    painter.drawText(10, 40, QString("Content Size: %1x%2").arg(m_contentSize.width()).arg(m_contentSize.height()));
    painter.drawText(10, 60, QString("Viewport Size: %1x%2").arg(visibleRect.width()).arg(visibleRect.height()));
}

void MyCustomScrollArea::updateScrollBars()
{
    // 水平スクロールバーの範囲を設定
    int hRange = m_contentSize.width() - viewport()->width();
    if (hRange < 0) hRange = 0;
    horizontalScrollBar()->setRange(0, hRange);
    horizontalScrollBar()->setPageStep(viewport()->width());

    // 垂直スクロールバーの範囲を設定
    int vRange = m_contentSize.height() - viewport()->height();
    if (vRange < 0) vRange = 0;
    verticalScrollBar()->setRange(0, vRange);
    verticalScrollBar()->setPageStep(viewport()->height());

    // 変更があった場合は、ビューポートの再描画を要求
    viewport()->update();
}

// main.cpp (MyCustomScrollArea を使用)
#include <QApplication>
#include <QMainWindow>
#include "MyCustomScrollArea.h" // 作成したカスタムスクロールエリア

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

    QMainWindow window;
    window.setWindowTitle("Custom QAbstractScrollArea Viewport Example");
    window.resize(600, 400);

    MyCustomScrollArea *customScrollArea = new MyCustomScrollArea(&window);
    // 仮想コンテンツのサイズを設定
    customScrollArea->setContentSize(QSize(3000, 2000));

    window.setCentralWidget(customScrollArea);
    window.show();

    return app.exec();
}

解説
この例では、MyCustomScrollArea は QAbstractScrollArea を継承しています。

• updateScrollBars()
  ビューポートのサイズやコンテンツのサイズが変わったときに、スクロールバーの range と pageStep を適切に設定することで、スクロールバーが正しく動作するようにします。
• scrollContentsBy() のオーバーライド
  スクロールバーが動かされたときに、コンテンツをどのように「スクロール」させるかを定義します。この例では viewport()->scroll(dx, dy) を使って、ビューポートの描画オフセットを調整しています。カスタム描画では、paintEvent 内でスクロールバーの値を考慮して描画オフセットを計算する必要があります。
• viewportEvent() のオーバーライド
  ビューポートがリサイズされたときに、スクロールバーの範囲を再計算するために viewportEvent() をオーバーライドしています。
• viewport() の使用
  paintEvent() の中で QPainter painter(viewport()); としている点が重要です。これにより、描画操作が QAbstractScrollArea 自体ではなく、その内部のビューポートウィジェット上で行われるようになります。updateScrollBars() でも viewport()->width() や viewport()->height() を使って、ビューポートの現在の表示サイズを取得しています。

この例は、QAbstractScrollArea が提供する viewport() メカニズムを使って、独自のスクロール可能な描画領域をどのように作成できるかを示しています。QScrollArea とは異なり、コンテンツウィジェットを直接配置するのではなく、paintEvent() 内で現在のスクロール位置に基づいてコンテンツを「描画」する責任があります。

---

QAbstractScrollArea::viewport() は、スクロール可能な領域の中心となるウィジェットへのポインタを返し、その上で描画やイベント処理を行うのがQtの標準的なアプローチです。しかし、特定の状況や目的によっては、以下のような代替方法や関連する考慮事項があります。

QScrollArea を使用する（最も一般的で推奨される代替策）

これは「代替」というよりも、「最も一般的な利用方法」ですが、カスタムで QAbstractScrollArea をサブクラス化して viewport() に直接描画する代わりに、既存の QScrollArea を利用して任意のウィジェットをスクロールさせるのが最もシンプルで推奨されるアプローチです。

• viewport() との関係
  QScrollArea::setWidget() を呼び出すと、内部的に QScrollArea がビューポートウィジェットを作成し、その子として設定されたウィジェット（上記の例では contentWidget）が配置されます。したがって、開発者が直接 viewport() を操作することは稀になりますが、裏側では viewport() の仕組みが使われています。
• 使用方法
  

  #include <QScrollArea>
  #include <QWidget>
  #include <QVBoxLayout>
  #include <QLabel>
  
  // ...
  QScrollArea *scrollArea = new QScrollArea(this);
  QWidget *contentWidget = new QWidget(scrollArea); // スクロールさせたいコンテンツの親ウィジェット
  QVBoxLayout *layout = new QVBoxLayout(contentWidget);
  
  for (int i = 0; i < 50; ++i) {
      layout->addWidget(new QLabel(QString("Item %1").arg(i), contentWidget));
  }
  contentWidget->setLayout(layout); // コンテンツウィジェットにレイアウトを設定
  
  scrollArea->setWidget(contentWidget); // これで contentWidget が scrollArea の viewport の子になる
  scrollArea->setWidgetResizable(true); // contentWidget のサイズに合わせて viewport をリサイズするかどうか
  

• 利点
  
  • Qtがスクロールロジック（スクロールバーの表示/非表示、範囲、ページステップ、イベント処理など）のほとんどを自動的に管理してくれるため、開発コストが大幅に削減されます。
  • カスタム描画ではなく、既存のウィジェットやカスタムウィジェットをそのままスクロールさせたい場合に最適です。

QGraphicsView を使用する（2Dグラフィックス特化）

非常に複雑な2Dグラフィックスや多数のアイテムをスクロールさせたい場合、QGraphicsView と QGraphicsScene フレームワークが強力な代替手段となります。

• viewport() との関係
  QGraphicsView は QAbstractScrollArea を継承しているため、内部にビューポートを持っています。QGraphicsView のビューポートは、QGraphicsScene の一部をユーザーに見せる「窓」として機能します。しかし、QGraphicsView の場合は、描画を QGraphicsScene のアイテムを通じて行い、ビューポートの paintEvent を直接オーバーライドすることは通常ありません。QGraphicsView::viewport() は、そのビューポートがどのようなウィジェット（通常は QWidget または QGLWidget/QOpenGLWidget のカスタムサブクラス）であるかを返します。
• 使用方法
  

  #include <QGraphicsView>
  #include <QGraphicsScene>
  #include <QGraphicsRectItem>
  
  // ...
  QGraphicsScene *scene = new QGraphicsScene(this);
  scene->setSceneRect(0, 0, 1000, 800); // シーン全体のサイズを設定
  
  // シーンにアイテムを追加
  scene->addRect(10, 10, 50, 50, QPen(Qt::black), QBrush(Qt::red));
  scene->addText("Hello Graphics View!", QFont("Arial", 20));
  
  QGraphicsView *view = new QGraphicsView(scene, this);
  // view は QAbstractScrollArea を継承しているため、スクロール機能を持つ
  view->setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);
  view->setVerticalScrollBarPolicy(Qt::ScrollBarAsNeeded);
  

• 利点
  
  • 何百万ものアイテムを効率的にレンダリング・管理できます。
  • 衝突検出、アイテムのグループ化、変形（回転、拡大縮小）などの高度な機能が組み込まれています。
  • 描画の最適化（カリング、LODなど）が自動的に行われます。
  • ビューポート変換（ズーム、パン）を簡単に実装できます。

QListView, QTableView, QTreeView (モデル/ビューベースのデータ表示)

リスト、テーブル、ツリー形式のデータをスクロール可能な形で表示したい場合は、これらの専用ビューが最適です。これらは QAbstractItemView を継承しており、さらに QAbstractScrollArea を継承しています。

• viewport() との関係
  これらのビューも内部的にビューポートを持っています。ビューポートは、モデルから取得したデータを描画し、スクロールに応じて表示範囲を更新します。ここでも、開発者が直接 viewport() を操作することは稀で、主にモデルとビューのインタラクションを通じてコンテンツを管理します。
• 使用方法
  

  #include <QListView>
  #include <QStringListModel>
  
  // ...
  QStringListModel *model = new QStringListModel(this);
  QStringList data;
  for (int i = 0; i < 100; ++i) {
      data << QString("Item %1").arg(i);
  }
  model->setStringList(data);
  
  QListView *listView = new QListView(this);
  listView->setModel(model);
  // listView は QAbstractScrollArea を継承しているので、スクロール機能を持つ
  

• 利点
  
  • 大量のデータを効率的に表示できます（遅延レンダリング）。
  • モデル/ビューアーキテクチャに基づいており、データと表示を分離できます。
  • ソート、フィルタリング、選択などの機能が組み込まれています。

QOpenGLWidget または QQuickWidget をカスタムビューポートとして設定する

非常に特殊なケースとして、QAbstractScrollArea::setViewport() を使用して、カスタムの QWidget サブクラスをビューポートとして設定することができます。これは、例えばOpenGLで独自の3Dシーンをレンダリングし、それをスクロールさせたい場合などに有効です。

• viewport() との関係
  この場合、QAbstractScrollArea::setViewport() を使って、開発者自身が作成したカスタムウィジェットをビューポートとして明示的に設定します。これにより、QAbstractScrollArea のスクロールバー管理と、カスタムウィジェットの特殊な描画（例: OpenGL）を組み合わせることが可能になります。scrollContentsBy() でスクロールオフセットを計算し、カスタムビューポートの paintGL() (または paintEvent) でこのオフセットを考慮して描画する必要があります。
• 使用方法
  

  // MyGLViewport.h (カスタムOpenGLビューポートウィジェット)
  #include <QOpenGLWidget>
  #include <QOpenGLFunctions> // 必要に応じて
  
  class MyGLViewport : public QOpenGLWidget, protected QOpenGLFunctions
  {
      Q_OBJECT
  public:
      MyGLViewport(QWidget *parent = nullptr) : QOpenGLWidget(parent) {}
  protected:
      void initializeGL() override {
          initializeOpenGLFunctions();
          glClearColor(0.2f, 0.2f, 0.2f, 1.0f);
      }
      void paintGL() override {
          glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
          // ここにカスタムOpenGL描画コードを記述
          // スクロールオフセットは QAbstractScrollArea から取得して考慮する必要がある
          qDebug() << "Painting OpenGL viewport...";
      }
      void resizeGL(int w, int h) override {
          glViewport(0, 0, w, h);
      }
  };
  
  // MyCustomGLScrollArea.h
  #include <QAbstractScrollArea>
  #include "MyGLViewport.h"
  
  class MyCustomGLScrollArea : public QAbstractScrollArea
  {
      Q_OBJECT
  public:
      MyCustomGLScrollArea(QWidget *parent = nullptr) : QAbstractScrollArea(parent) {
          setViewport(new MyGLViewport(this)); // ここでカスタムビューポートを設定
          setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOn);
          setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOn);
          // 必要に応じてスクロールバーの範囲などを設定
          horizontalScrollBar()->setRange(0, 1000);
          verticalScrollBar()->setRange(0, 1000);
      }
  protected:
      void scrollContentsBy(int dx, int dy) override {
          // スクロールバーの値に基づいてOpenGLシーンを調整するロジックをここに記述
          qDebug() << "Scrolling by" << dx << dy;
          viewport()->update(); // ビューポートの再描画を要求
      }
  };
  
  // main.cpp
  #include <QApplication>
  #include <QMainWindow>
  // ...
  QMainWindow window;
  MyCustomGLScrollArea *glScrollArea = new MyCustomGLScrollArea(&window);
  window.setCentralWidget(glScrollArea);
  window.show();
  

• 利点
  
  • QAbstractScrollArea のスクロールバー管理と、独自の描画テクノロジーを組み合わせることができます。

QAbstractScrollArea::viewport() は、Qtが提供するスクロール機能の基盤となるメカニズムです。

• そして、非常に特殊な描画要件（例: OpenGL描画）があり、Qtのスクロールバーと連携させたい場合にのみ、QAbstractScrollArea を直接サブクラス化して、setViewport() でカスタムウィジェットを設定するという高度なアプローチを検討することになります。
• リストやテーブル、ツリーデータを扱う場合は QListView などのモデル/ビュークラス。
• 2Dグラフィックスに特化した場合は QGraphicsView。
• ほとんどのアプリケーションでは、QScrollArea を使用して、既存のウィジェットをスクロールさせるのが最も簡単で効率的です。