もう迷わない！Qt QScrollBarの見た目変更テクニック：initStyleOption()の代替手段

2025-05-27

QScrollBar::initStyleOption() メソッドは、Qtのスクロールバー (QScrollBar) が自身の描画に必要なスタイル情報を QStyleOptionSlider オブジェクトに初期化（設定）するためのプロテクトされた仮想関数です。

主な目的と役割

スタイル情報のカプセル化
Qtでは、ウィジェットの見た目（スタイル）は、その描画を担当する QStyle クラスによって制御されます。QStyle は、ウィジェットの現在の状態（有効/無効、ホバー、押されているなど）、サイズ、値などの情報に基づいて描画を行います。これらの情報を QStyle に渡すために QStyleOption クラスとその派生クラス（この場合は QStyleOptionSlider）が使われます。
QStyleOptionSlider へのデータ設定
QScrollBar::initStyleOption() は、現在の QScrollBar オブジェクトが持つさまざまなプロパティ（例えば、スクロールバーの向き、最小値、最大値、現在の値、ページステップ、シングルステップ、スライダーの有効/無効状態など）を option 引数で渡された QStyleOptionSlider オブジェクトにコピーします。
カスタム描画の支援
このメソッドは主に、QScrollBar を継承してカスタム描画を行うサブクラスで利用されます。カスタム描画を行う場合、paintEvent() メソッド内で QStyle を使ってウィジェットを描画することがよくあります。その際、QStyle に渡す QStyleOptionSlider オブジェクトを自分で完全に設定するのは手間がかかります。initStyleOption() を呼び出すことで、QScrollBar の基本的な情報が自動的に QStyleOptionSlider に設定されるため、開発者はカスタムしたい特定のプロパティだけを変更すればよくなります。
QStyleOption::initFrom() との関連
内部的には、initStyleOption() は QStyleOption::initFrom(this) を呼び出して、基底となる QStyleOption の共通プロパティ（ウィジェットのパレット、レイアウト方向など）を初期化します。その上で、QScrollBar 固有のスライダー関連のプロパティを追加で設定します。

具体的な利用シナリオ

QScrollBar の見た目を大きく変えたい場合（例えば、デフォルトのスクロールバーの代わりに全く異なるデザインのスクロールバーを描画したい場合など）、QScrollBar を継承して paintEvent() をオーバーライドすることが考えられます。その paintEvent() の中で、現在のスクロールバーの状態を反映した QStyleOptionSlider オブジェクトを作成し、それを QStyle の drawComplexControl() などのメソッドに渡して描画させます。

このとき、以下のように initStyleOption() を利用することで、QStyleOptionSlider の多くの設定を自動化できます。

#include <QScrollBar>
#include <QStyleOptionSlider>
#include <QPainter>
#include <QApplication>
#include <QStyle> // QStyle を使用するために必要

class MyCustomScrollBar : public QScrollBar
{
public:
    MyCustomScrollBar(QWidget *parent = nullptr) : QScrollBar(parent) {}

protected:
    void paintEvent(QPaintEvent *event) override
    {
        Q_UNUSED(event);

        QPainter painter(this);
        QStyleOptionSlider opt; // QStyleOptionSlider オブジェクトを作成

        // このQScrollBarの現在の状態をoptに設定
        initStyleOption(&opt);

        // ここでoptのプロパティを必要に応じて変更できます
        // 例：スライダーの色を変える、特定の部分だけ描画しないなど

        // 現在のスタイルを使ってスクロールバーを描画
        style()->drawComplexControl(QStyle::CC_ScrollBar, &opt, &painter, this);
    }
};

`void QScrollBar::initStyleOption(QStyleOptionSlider *option)` に関連する一般的なエラーとトラブルシューティング

QScrollBar::initStyleOption() 自体が直接エラーメッセージを生成することは稀ですが、このメソッドが使用される文脈（主にカスタム描画）において、以下のような問題が発生することがあります。

スクロールバーが全く描画されない、または一部しか描画されない

原因

QPainter が正しく設定されていない（begin() / end()、painter.end() 忘れなど）。
QStyleOptionSlider オブジェクトが適切に初期化されていない。
paintEvent() のオーバーライドが正しくない。

トラブルシューティング

QPainter の初期化と終了
QPainter painter(this); のようにウィジェットを引数に渡して初期化しているか、または painter.begin(this); と painter.end(); が対になっているか確認します。
描画関数の呼び出し
style()->drawComplexControl(QStyle::CC_ScrollBar, &opt, &painter, this); のように、適切な QStyle の描画関数が呼び出されているか確認します。特に、QStyle::CC_ScrollBar が指定されているか、QStyleOptionSlider と QPainter が正しく渡されているか確認します。
initStyleOption() の呼び出し
paintEvent() の中で QStyleOptionSlider opt; initStyleOption(&opt); のように initStyleOption() が呼び出されているか確認します。
paintEvent() の確認
QScrollBar を継承している場合、paintEvent(QPaintEvent *event) を protected でオーバーライドしているか確認してください。

スクロールバーの見た目がデフォルトと変わってしまったり、おかしくなる

原因

カスタムスタイルシートや他のスタイル設定と競合している。
QStyleOptionSlider の一部のプロパティを初期化し忘れている（initStyleOption() を呼び出していない場合）。
initStyleOption() 呼び出し後に QStyleOptionSlider のプロパティを誤って変更している。

トラブルシューティング

デバッグ出力
initStyleOption() を呼び出した直後と、描画関数を呼び出す直前の QStyleOptionSlider の重要なプロパティ（state, rect, orientation, sliderPosition など）をデバッグ出力し、期待通りの値になっているか確認します。
スタイルシートの影響
アプリケーション全体や親ウィジェットに適用されているスタイルシートが、カスタムスクロールバーの描画に影響を与えている可能性があります。一時的にスタイルシートを無効にしてテストしてみてください。
initStyleOption() の後の変更の確認
initStyleOption(&opt); を呼び出した後、意図しない opt のメンバー変数（例: opt.state, opt.rect, opt.subControls など）の変更がないか確認します。基本的な描画をしたい場合は、initStyleOption() を呼び出した後、opt を変更せずにそのまま drawComplexControl() に渡すのが最も安全です。

スクロールバーのインタラクション（クリック、ドラッグなど）が機能しない

原因

QStyleOptionSlider の state フラグ（QStyle::State_Enabled, QStyle::State_MouseOver, QStyle::State_Sunken など）が適切に更新されていない。
paintEvent() だけをオーバーライドし、マウスイベント (mousePressEvent, mouseMoveEvent, mouseReleaseEvent) や wheelEvent を適切に処理していない。

トラブルシューティング

update() の呼び出し
マウスオーバーやクリック時など、スクロールバーの状態が変化したときに update() を呼び出し、再描画をトリガーしているか確認します。initStyleOption() はその時点で QScrollBar の状態を反映しますが、その状態自体がイベントによって更新されないと、見た目も更新されません。
イベントハンドリングの確認
QScrollBar はマウスイベントやホイールイベントを自動的に処理して値を変更しますが、paintEvent() をオーバーライドするだけではインタラクションは回復しません。もし、QScrollBar の基本機能を維持しつつカスタム描画を行いたいのであれば、paintEvent() のみをオーバーライドし、他のイベントは基底クラスの QScrollBar::mousePressEvent(event); などを呼び出すことで委譲するのが一般的です。

パフォーマンスの問題（描画が遅い、CPU使用率が高い）

原因

QStyleOptionSlider を毎回ヒープに確保している（非常に稀なケース）。
不必要な再描画が頻繁に発生している。
paintEvent() 内で高コストな処理を実行している。

トラブルシューティング

QStyleOptionSlider のスタック確保
ほとんどの場合、QStyleOptionSlider opt; のようにスタックにオブジェクトを確保することで十分です。ヒープ (new QStyleOptionSlider()) を使う必要はありません。
不必要な update() の回避
update() の呼び出しが多すぎないか確認します。必要なときにだけ update() を呼び出すようにします。
paintEvent() 内の最適化
paintEvent() は頻繁に呼び出される可能性があるため、可能な限り軽量な処理に留めるべきです。重い計算やファイルI/Oなどはここで行うべきではありません。

Qtバージョンの違いによる互換性問題

原因

新しいQtバージョンでQStyleOptionSliderの構造や挙動が変更されている。
古いQtバージョンでは利用できないQStyleOptionSliderのプロパティを使用している。

トラブルシューティング

条件付きコンパイル
複数のQtバージョンをサポートする場合、#if QT_VERSION >= QT_VERSION_CHECK(X, Y, Z) などのマクロを使用してバージョンごとのコードパスを記述することを検討します。
Qtドキュメントの参照
使用しているQtのバージョンに対応する公式ドキュメントで QStyleOptionSlider および QStyle::drawComplexControl の詳細を確認し、互換性のないプロパティや挙動変更がないか確認します。

デバッグのヒント

シンプルなテストケース
複雑なアプリケーションの一部として問題が発生している場合、QScrollBar を継承した最小限のサンプルアプリケーションを作成し、問題が再現するかどうかを確認します。これにより、問題の範囲を特定しやすくなります。
Qt Creatorのデバッガ
ブレークポイントを設定し、ステップ実行しながら QStyleOptionSlider オブジェクトの中身を詳しく調査します。
qDebug() の活用
paintEvent() 内で QStyleOptionSlider の主要なメンバー変数（rect, state, orientation, sliderPosition など）の値を qDebug() で出力し、期待通りの値が設定されているか確認します。

QScrollBar::initStyleOption() はウィジェットの描画パイプラインの重要な一部であり、その使い方を理解することで、カスタムウィジェットの描画に関する問題を効率的に解決できます。 Qtプログラミングにおける void QScrollBar::initStyleOption(QStyleOptionSlider *option) の使用に関連する一般的なエラーとそのトラブルシューティングについて解説します。

initStyleOption() は主にカスタムスタイルの描画を支援するための関数であり、直接的な「エラー」というよりも、意図しない描画結果やスタイル適用に関する問題が発生することが多いです。

QStyleOptionSlider の初期化忘れ、または不適切な使用

問題
paintEvent() などでカスタム描画を行う際に、QStyleOptionSlider オブジェクトを初期化せずに使用したり、initStyleOption() を呼び出さずに自分で全てのプロパティを設定しようとして、スクロールバーの描画が正しく行われないことがあります。

症状

スクロールバーのクリックやドラッグが機能しない（描画はされているがインタラクションがない）。
スクロールバーの向き（縦/横）が正しくない。
スクロールバーの範囲や現在値が反映されない。
スクロールバーのハンドル（つまみ）が表示されない。

トラブルシューティング

QStyle の適切なメソッドの使用
QStyle クラスには、drawPrimitive(), drawControl(), drawComplexControl() などの描画メソッドがあります。スクロールバー全体を描画する場合は drawComplexControl(QStyle::CC_ScrollBar, ...) を使用するのが一般的です。特定の部分だけを描画する場合は、subControlRect() でその部分の矩形を取得し、drawPrimitive() や drawControl() を適切に使用する必要があります。
QStyleOptionSlider の型確認
QStyleOptionSlider は QStyleOptionComplex を継承しており、スライダー固有のプロパティ（minimum, maximum, sliderPosition, singleStep, pageStep, orientation など）を持っています。これらのプロパティが正しく設定されていることを確認してください。
initStyleOption() の呼び出し確認
paintEvent() の冒頭で、必ず initStyleOption(&opt); のように呼び出しているか確認してください。これにより、QScrollBar の現在の状態が opt に正確に反映されます。

スタイルシート (QSS) との競合

問題
initStyleOption() を使ってカスタム描画を行っているにも関わらず、ウィジェットにスタイルシートが適用されていると、意図しない描画結果になることがあります。Qtのスタイルシートは強力であり、カスタム描画ロジックと競合する可能性があります。

症状

一部の要素はカスタム描画が適用され、別の要素はスタイルシートが適用されるなど、一貫性のない見た目になる。
スタイルシートで定義された見た目が優先されてしまう。
initStyleOption() で設定したはずのプロパティ（色、サイズなど）が反映されない。

トラブルシューティング

カスタムスタイルクラスの検討
スタイルシートと共存させつつ、より深いカスタマイズを行いたい場合は、QProxyStyle または QStyle を継承した独自のスタイルクラスを作成し、QApplication::setStyle() や QWidget::setStyle() で適用することを検討してください。initStyleOption() は QStyle の中で使用されることを前提としており、このアプローチがより堅牢です。
スタイルシートの無効化/確認
QScrollBar に直接、または親ウィジェットから継承されているスタイルシートがないか確認してください。一時的にスタイルシートを無効にして、問題が解決するかどうかを試すのが有効です。
```
myScrollBar->setStyleSheet(""); // スタイルシートをクリアする
```

QStyleOptionSlider のプロパティの誤った変更

問題
initStyleOption() を呼び出した後に、QStyleOptionSlider のプロパティを誤って変更してしまうことで、描画が崩れることがあります。

症状

ページステップやシングルステップが機能しない。
スライダーの表示位置が常に同じ、または予期せぬ位置にある。
スライダーの範囲がおかしい（Min/Maxが逆転している、範囲が極端に狭い/広い）。

トラブルシューティング

プロパティのデバッグ出力
QStyleOptionSlider の主要なプロパティ（minimum, maximum, sliderPosition, orientation, rect など）を qDebug() で出力し、期待通りの値になっているかを確認してください。
変更の確認
initStyleOption() の呼び出し後に、QStyleOptionSlider のどのプロパティを変更しているかを慎重に確認してください。必要最小限の変更に留めるべきです。

QStyle::subControlRect() との連携の問題

問題
カスタム描画でスクロールバーの個々の部品（ハンドル、ページ、矢印など）を細かく制御する場合、QStyle::subControlRect() を使用して各部品の領域を取得します。この際、initStyleOption() で設定された QStyleOptionSlider を正しく渡さないと、不正な矩形が返されることがあります。

症状

ドラッグ可能な領域と実際のハンドルの描画が一致しない。
部品が重なって表示される、または一部が表示されない。
各部品の描画位置がずれる。

トラブルシューティング

スタイルごとの違いへの対応
QStyle::subControlRect() の挙動は、使用している QStyle (例: Fusion, Windows, macOS スタイルなど) によって微妙に異なる場合があります。特定のスタイルでのみ問題が発生する場合は、そのスタイルの実装を考慮する必要があるかもしれません。

Qtバージョンの違い

問題
Qtのバージョンアップに伴い、QStyleOptionSlider の構造や initStyleOption() の挙動がごく稀に変わることがあります。古いコードを新しいQtバージョンでコンパイル・実行した際に問題が発生する可能性があります。

症状

コンパイル時に非推奨警告やエラーが出る。
以前のバージョンでは正しく動いていたカスタムスクロールバーが、新しいバージョンで表示がおかしくなる。

変更履歴の確認
Qtの変更ログや移行ガイドを確認し、関連する変更点がないか調べます。
公式ドキュメントの確認
使用しているQtバージョンの公式ドキュメントで、QScrollBar::initStyleOption() や QStyleOptionSlider に変更がないか確認してください。

例1: スクロールバーのハンドル（つまみ）の色をカスタマイズする

この例では、QScrollBar を継承したカスタムクラスを作成し、paintEvent() をオーバーライドしてスクロールバーのハンドル（スライダー）の色を標準とは異なる色で描画します。

MyCustomScrollBar.h

#ifndef MYCUSTOMSCROLLBAR_H
#define MYCUSTOMSCROLLBAR_H

#include <QScrollBar>
#include <QStyleOptionSlider> // QStyleOptionSlider を使用するために必要
#include <QPainter>
#include <QApplication> // QApplication::style() を使用するために必要

class MyCustomScrollBar : public QScrollBar
{
    Q_OBJECT
public:
    explicit MyCustomScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr);
    explicit MyCustomScrollBar(QWidget *parent = nullptr);

protected:
    void paintEvent(QPaintEvent *event) override;
};

#endif // MYCUSTOMSCROLLBAR_H

MyCustomScrollBar.cpp

#include "MyCustomScrollBar.h"

MyCustomScrollBar::MyCustomScrollBar(Qt::Orientation orientation, QWidget *parent)
    : QScrollBar(orientation, parent)
{
}

MyCustomScrollBar::MyCustomScrollBar(QWidget *parent)
    : QScrollBar(parent)
{
}

void MyCustomScrollBar::paintEvent(QPaintEvent *event)
{
    Q_UNUSED(event);

    QPainter painter(this);
    QStyleOptionSlider opt;

    // (1) QScrollBar の現在の状態を QStyleOptionSlider に初期化
    //     これにより、最小値、最大値、現在値、向き、サイズなどの
    //     基本的なスクロールバー情報が opt に設定されます。
    initStyleOption(&opt);

    // (2) ここで QStyleOptionSlider のプロパティを変更して、
    //     描画をカスタマイズします。
    //     ここではハンドルの色を変える例を示します。
    //     ハンドルの色を変更するには、パレットの QPalette::Highlight ロールを変更します。
    opt.palette.setColor(QPalette::Highlight, Qt::blue); // ハンドルを青にする
    opt.palette.setColor(QPalette::AlternateBase, Qt::lightGray); // スクロールバーの背景色（溝の部分）


    // (3) QStyle を使ってスクロールバーの各部分を描画します。
    //     CC_ScrollBar はスクロールバー全体を構成する複雑なコントロールであることを示します。
    //     オプションの rect にはウィジェット全体の領域が設定されているので、
    //     subControlRect を使って各部品の領域を取得し、個別に描画することも可能です。

    // スタイルシートが適用されている場合、このカスタム描画が上書きされる可能性があります。
    // スタイルシートと共存させたい場合は、QProxyStyleなどを検討する必要があります。
    style()->drawComplexControl(QStyle::CC_ScrollBar, &opt, &painter, this);

    // 例: ハンドルだけを異なる色で描画する場合（より細かい制御）
    // ハンドルの矩形を取得
    // QRect handleRect = style()->subControlRect(QStyle::CC_ScrollBar, &opt, QStyle::SC_ScrollBarSlider, this);
    //
    // // ハンドルを赤で塗りつぶす（これはデフォルトの描画後に実行されるため、上書きされます）
    // painter.fillRect(handleRect, Qt::red);
}

main.cpp (テスト用)

#include <QApplication>
#include <QTextEdit>
#include <QVBoxLayout>
#include <QWidget>
#include "MyCustomScrollBar.h" // 作成したカスタムスクロールバーをインクルード

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

    QWidget window;
    QVBoxLayout *layout = new QVBoxLayout(&window);

    QTextEdit *textEdit = new QTextEdit("これは長いテキストの例です。スクロールバーの動作を確認するために、たくさんの行を追加してください。\n"
                                        "A long text example to test scroll bar behavior. Please add many more lines to observe scrolling.\n");
    textEdit->setMinimumHeight(200);

    // デフォルトのスクロールバーを取得し、カスタムスクロールバーをセットする
    // QTextEditはQAbstractScrollAreaを継承しているので、そのスクロールバーにアクセスできます。
    MyCustomScrollBar *vScrollBar = new MyCustomScrollBar(Qt::Vertical);
    MyCustomScrollBar *hScrollBar = new MyCustomScrollBar(Qt::Horizontal);

    textEdit->setVerticalScrollBar(vScrollBar);
    textEdit->setHorizontalScrollBar(hScrollBar);

    layout->addWidget(textEdit);
    window.setLayout(layout);
    window.setWindowTitle("カスタムスクロールバーの例");
    window.resize(400, 300);
    window.show();

    return a.exec();
}

解説

MyCustomScrollBar クラスは QScrollBar を継承しています。
paintEvent(QPaintEvent *event) をオーバーライドします。これはウィジェットの再描画が必要なときにQtフレームワークによって呼び出されます。
QPainter painter(this); を使用して、このウィジェット上に描画するための QPainter オブジェクトを作成します。
QStyleOptionSlider opt; でスタイルオプションオブジェクトを作成します。
opt.palette.setColor(QPalette::Highlight, Qt::blue); のように、opt のプロパティを変更します。この例では、スクロールバーのハイライト色（通常はハンドルの色やクリックされた部分の色に影響します）を青に設定しています。QStyleOptionSlider は QStyleOption を継承しているため、palette などの共通のプロパティにアクセスできます。
style()->drawComplexControl(QStyle::CC_ScrollBar, &opt, &painter, this); を呼び出すことで、現在のアプリケーションスタイル (QApplication::style()) を使って、opt で指定された情報に基づいてスクロールバーが描画されます。CC_ScrollBar は複合コントロールとしてのスクロールバーを示します。

この例では、initStyleOption() が QScrollBar の現在の状態を QStyleOptionSlider に効率的に転送し、その上で必要な部分だけをカスタマイズして描画できることを示しています。

今度は、スクロールバーの矢印の色をカスタマイズする例です。これは、subControlRect() を使って特定のサブコントロールの領域を取得し、その部分だけを独自に描画するアプローチのヒントになります。

// MyCustomScrollBar.h は例1と同じ
// MyCustomScrollBar.cpp (paintEvent のみ変更)

#include "MyCustomScrollBar.h"

// ... (コンストラクタは例1と同じ)

void MyCustomScrollBar::paintEvent(QPaintEvent *event)
{
    Q_UNUSED(event);

    QPainter painter(this);
    QStyleOptionSlider opt;
    initStyleOption(&opt); // 基本情報を初期化

    // まずはデフォルトのスタイルでスクロールバー全体を描画する
    // これにより、溝やハンドルなどの基本的な形状が描かれます。
    style()->drawComplexControl(QStyle::CC_ScrollBar, &opt, &painter, this);

    // ここから矢印部分のカスタム描画
    // スクロールバーの上下（または左右）の矢印ボタンの矩形を取得
    QRect rectUpArrow = style()->subControlRect(QStyle::CC_ScrollBar, &opt, QStyle::SC_ScrollBarSubLine, this); // "SubLine" は上/左の矢印
    QRect rectDownArrow = style()->subControlRect(QStyle::CC_ScrollBar, &opt, QStyle::SC_ScrollBarAddLine, this); // "AddLine" は下/右の矢印

    // 矢印ボタンの背景を塗る（例: 赤）
    painter.fillRect(rectUpArrow, Qt::red);
    painter.fillRect(rectDownArrow, Qt::red);

    // 矢印そのものを描画
    // QStyle::PE_IndicatorArrowUp, QStyle::PE_IndicatorArrowDown などを使用
    // 矢印の色を白にする
    opt.palette.setColor(QPalette::ButtonText, Qt::white); // 矢印の色は通常ButtonTextで制御される

    // 矢印アイコンの描画（背景の上に重ねて描画）
    // QStyleOption ボタンのオプションを使用
    QStyleOptionButton buttonOpt;
    buttonOpt.initFrom(this); // ウィジェットから基本情報を初期化
    buttonOpt.rect = rectUpArrow;
    buttonOpt.palette = opt.palette; // スクロールバーのパレットから色を継承

    // 上/左矢印の描画
    style()->drawPrimitive(opt.orientation == Qt::Vertical ? QStyle::PE_IndicatorArrowUp : QStyle::PE_IndicatorArrowLeft, &buttonOpt, &painter, this);

    buttonOpt.rect = rectDownArrow;
    // 下/右矢印の描画
    style()->drawPrimitive(opt.orientation == Qt::Vertical ? QStyle::PE_IndicatorArrowDown : QStyle::PE_IndicatorArrowRight, &buttonOpt, &painter, this);
}

矢印アイコン自体は QStyle::drawPrimitive() を使って描画されます。この際、矢印の色を制御するために QStyleOptionButton を使用し、そのパレットの QPalette::ButtonText ロールを白に設定しています。
取得した領域に対して、カスタムの背景色を塗りつぶします (painter.fillRect())。
その後、style()->subControlRect() を使って、特定のサブコントロール（SC_ScrollBarSubLine と SC_ScrollBarAddLine、つまり矢印ボタン）の描画領域を取得します。
この例では、まず style()->drawComplexControl() でスクロールバー全体を標準的に描画します。

initStyleOption() を直接使わない、またはそれとは異なるレベルでカスタマイズを行う代替手段をいくつか説明します。

Qt Style Sheets (QSS) の利用

これは、Qtでウィジェットの見た目をカスタマイズする最も一般的で推奨される方法です。CSS (Cascading Style Sheets) に似た構文を使用し、プログラムコードをほとんど書くことなく、柔軟にウィジェットの見た目を変更できます。

特徴

制限
initStyleOption() や QStyle を使ったカスタム描画ほど、ピクセル単位での細かい制御はできません。例えば、複雑なグラデーションや形状の変更には限界があります。
保守性
UIの見た目とロジックを分離できるため、コードの保守が容易になります。
柔軟性
特定のウィジェット、クラス、オブジェクト名、擬似状態（ホバー、プレスなど）に基づいてスタイルを適用できます。
宣言的
外観をコードではなく、テキストファイル（.qss）や文字列として記述します。

QScrollBar の QSS 例

/* スクロールバー全体の背景色と幅 */
QScrollBar:vertical {
    border: none;
    background: #202020; /* 暗い背景 */
    width: 12px;
    margin: 15px 0 15px 0; /* 上下の矢印ボタンのスペース */
    border-radius: 6px; /* 角を丸くする */
}

/* スクロールバーのハンドル（つまみ） */
QScrollBar::handle:vertical {
    background: #505050; /* ハンドルの色 */
    min-height: 20px; /* ハンドルの最小高さ */
    border-radius: 5px; /* ハンドルの角を丸くする */
}

QScrollBar::handle:vertical:hover {
    background: #707070; /* ホバー時のハンドルの色 */
}

QScrollBar::handle:vertical:pressed {
    background: #909090; /* プレス時のハンドルの色 */
}

/* 上の矢印ボタン */
QScrollBar::add-line:vertical {
    border: none;
    background: #303030; /* ボタンの背景色 */
    height: 15px; /* ボタンの高さ */
    subcontrol-position: top; /* 上に配置 */
    subcontrol-origin: margin;
    border-top-left-radius: 6px; /* 角を丸くする */
    border-top-right-radius: 6px;
}

/* 下の矢印ボタン */
QScrollBar::sub-line:vertical {
    border: none;
    background: #303030; /* ボタンの背景色 */
    height: 15px; /* ボタンの高さ */
    subcontrol-position: bottom; /* 下に配置 */
    subcontrol-origin: margin;
    border-bottom-left-radius: 6px; /* 角を丸くする */
    border-bottom-right-radius: 6px;
}

/* 上の矢印アイコン */
QScrollBar::up-arrow:vertical {
    image: url(:/icons/arrow_up_white.png); /* カスタム矢印アイコン */
    width: 10px;
    height: 10px;
}

/* 下の矢印アイコン */
QScrollBar::down-arrow:vertical {
    image: url(:/icons/arrow_down_white.png); /* カスタム矢印アイコン */
    width: 10px;
    height: 10px;
}

/* スクロールバーの「ページ」部分（ハンドルと矢印の間） */
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {
    background: none; /* 透明 */
}

適用方法

// アプリケーション全体に適用
qApp->setStyleSheet(myQssString);

// 特定のウィジェットに適用
myTextEdit->verticalScrollBar()->setStyleSheet(myQssString);

QStyle のサブクラス化（カスタムスタイル）

QStyle はQtウィジェットの描画ロジック全体をカプセル化する抽象クラスです。QStyle をサブクラス化することで、Qtアプリケーション全体の見た目や特定のウィジェットの描画方法を根本的に変更できます。

特徴

initStyleOption() との連携
QStyle の drawComplexControl() などのメソッドは、内部で initStyleOption() に相当する処理（ウィジェットから QStyleOption への情報転送）を行います。したがって、この方法を使う場合でも、QStyleOptionSlider は描画のための重要なデータ構造として使用されます。
複雑性
非常に強力ですが、実装は最も複雑になります。すべてのウィジェットのすべての状態を考慮して描画ロジックを記述する必要があります。
一貫性
アプリケーション全体にわたって統一された見た目を実現するのに適しています。
完全な制御
initStyleOption() が提供する情報を使って、すべての描画プリミティブ（線、矩形、テキスト、アイコンなど）を自分で描画できます。

QStyle サブクラスの簡単な例（QProxyStyle の利用）

QStyle 全体をスクラッチから実装するのは大変なので、既存のスタイルを継承して特定の部分だけを変更できる QProxyStyle がよく使われます。

#include <QProxyStyle>
#include <QPainter>
#include <QStyleOption>
#include <QStyleOptionSlider>

class MyCustomStyle : public QProxyStyle
{
public:
    MyCustomStyle(QStyle *baseStyle = nullptr) : QProxyStyle(baseStyle) {}

    // スクロールバーのハンドルを描画する部分をオーバーライド
    void drawComplexControl(ComplexControl control, const QStyleOptionComplex *option,
                            QPainter *painter, const QWidget *widget = nullptr) const override
    {
        if (control == CC_ScrollBar) {
            const QStyleOptionSlider *sliderOption = qstyleoption_cast<const QStyleOptionSlider *>(option);
            if (sliderOption) {
                // デフォルトのスクロールバー描画ロジックを呼び出す
                QProxyStyle::drawComplexControl(control, option, painter, widget);

                // ハンドルの矩形を取得
                QRect handleRect = subControlRect(control, option, SC_ScrollBarSlider, widget);

                // ハンドルを上書きする形でカスタム描画を行う
                painter->setBrush(Qt::green); // ハンドルを緑に塗る
                painter->setPen(Qt::NoPen);
                painter->drawRect(handleRect); // 四角いハンドルで上書き
                return;
            }
        }
        // その他のコントロールは基本スタイルに任せる
        QProxyStyle::drawComplexControl(control, option, painter, widget);
    }

    // 必要に応じて、他の drawXXX メソッドや pixelMetric などもオーバーライド可能
};

// 使用例 (main.cpp など)
int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    // アプリケーション全体にカスタムスタイルを適用
    a.setStyle(new MyCustomStyle(a.style())); // 現在のスタイルをベースにする

    // ... (通常のQtウィジェットの作成と表示) ...

    return a.exec();
}

解説

subControlRect() を使って、描画するサブコントロール（SC_ScrollBarSlider はハンドル）の矩形を取得します。
QProxyStyle::drawComplexControl(control, option, painter, widget); を呼び出すことで、既存のスタイルによるデフォルトの描画を実行させます。その後、その上にカスタムの描画（この場合は緑のハンドルを上書き）を行います。
qstyleoption_cast<const QStyleOptionSlider *>(option) を使用して、汎用的な QStyleOptionComplex を QStyleOptionSlider にキャストします。これにより、スクロールバー固有のオプションにアクセスできます。
drawComplexControl() をオーバーライドし、control が CC_ScrollBar の場合にカスタム描画を行います。
MyCustomStyle は QProxyStyle を継承しています。これにより、変更したい部分だけをオーバーライドし、それ以外の部分は元のスタイル (baseStyle) の動作を維持できます。

このアプローチは、より深いレベルでのカスタマイズが必要な場合に適していますが、QSS よりも学習コストと実装の労力がかかります。

QPainter を使った完全なカスタム描画（paintEvent のみ）

これは、initStyleOption() の説明の例で示したように、QScrollBar を継承して paintEvent() をオーバーライドし、その中で QStyleOption を使わずに QPainter ですべての描画を自力で行う方法です。

特徴

initStyleOption() との関連
この方法でも、スクロールバーの現在値や範囲といった「状態」は QScrollBar のプロパティ（value(), minimum(), maximum(), orientation() など）から直接取得できます。initStyleOption() はこれらのプロパティを QStyleOptionSlider に集約するヘルパーですが、直接これらのプロパティを使っても描画は可能です。
インタラクションの考慮
見た目だけでなく、mousePressEvent(), mouseMoveEvent(), mouseReleaseEvent() などをオーバーライドして、スクロールバーのインタラクション（ドラッグ、クリック）も自分で実装する必要がある場合があります。この点が最も複雑で、通常は QStyle の hitTestComplexControl() などを利用して部分的に簡素化します。
手間
スクロールバーのすべての部分（溝、ハンドル、矢印ボタン、ページ領域など）と、それぞれの状態（ホバー、プレス、無効など）を自分で描画する必要があります。
最大限の自由度
完全に独自の見た目を実装できます。

例 (概念的)

#include <QScrollBar>
#include <QPainter>

class MyFullCustomScrollBar : public QScrollBar
{
    Q_OBJECT
public:
    explicit MyFullCustomScrollBar(QWidget *parent = nullptr) : QScrollBar(parent) {}

protected:
    void paintEvent(QPaintEvent *event) override
    {
        Q_UNUSED(event);
        QPainter painter(this);
        painter.setRenderHint(QPainter::Antialiasing);

        // (1) スクロールバーの背景（溝）を描画
        painter.setBrush(Qt::darkGray);
        painter.setPen(Qt::NoPen);
        painter.drawRoundedRect(rect(), 5, 5); // ウィジェット全体の矩形を丸角で描画

        // (2) ハンドルの位置とサイズを計算
        // これは非常に複雑で、QScrollBarのvalue(), minimum(), maximum(), orientation(),
        // およびウィジェットのサイズに基づいて計算する必要があります。
        // 例: 垂直スクロールバーの場合のハンドルの高さと位置
        int handleHeight = (qreal(pageStep()) / (maximum() - minimum() + pageStep())) * height();
        if (handleHeight < 20) handleHeight = 20; // 最小の高さ
        int handlePos = (qreal(value() - minimum()) / (maximum() - minimum())) * (height() - handleHeight);
        if (orientation() == Qt::Vertical) {
            QRect handleRect(0, handlePos, width(), handleHeight);
            painter.setBrush(Qt::red); // ハンドルを赤で描画
            painter.drawRoundedRect(handleRect, 4, 4);
        } else {
            // 水平スクロールバーの計算も同様に必要
        }

        // (3) 矢印ボタンを描画
        // ここでも、ボタンの矩形と矢印の描画ロジックをすべて自分で実装
        // ...
    }

    // マウスイベントをオーバーライドして、ドラッグなどのインタラクションを実装する必要がある
    // void mousePressEvent(QMouseEvent *event) override;
    // void mouseMoveEvent(QMouseEvent *event) override;
    // void mouseReleaseEvent(QMouseEvent *event) override;
};

解説

この方法は最も柔軟ですが、Qtの既存の描画ロジック（QStyle や QStyleOption が提供するもの）を完全に捨てることになります。したがって、スクロールバーのすべての視覚的な要素とインタラクションを自分で実装する大きな負担が伴います。ほとんどの場合、QSS か QProxyStyle の利用が推奨されます。

void QScrollBar::initStyleOption() は、QStyle の描画メカニズム（特に QStyle::drawComplexControl など）と連携してカスタム描画を行う際に非常に役立ちます。しかし、Qtでウィジェットの見た目をカスタマイズする方法は、以下の選択肢があります。

Qt Style Sheets (QSS): 最も簡単で、多くのカスタマイズ要件を満たします。コード量が少なく、UIとロジックの分離が可能です。
QStyle のサブクラス化（特に QProxyStyle）: QSS では対応できないような深いレベルでの見た目の変更や、特定の描画ロジックのオーバーライドに適しています。initStyleOption() が提供する情報が内部的に利用されます。
paintEvent() での完全なカスタム描画: 非常に特殊な描画が必要な場合にのみ使用します。実装が最も複雑で、ウィジェットのインタラクションも自分で管理する必要がある場合が多いです。

もう迷わない！Qt QScrollBarの見た目変更テクニック：initStyleOption()の代替手段

void QScrollBar::initStyleOption(QStyleOptionSlider *option) に関連する一般的なエラーとトラブルシューティング

スクロールバーが全く描画されない、または一部しか描画されない

スクロールバーの見た目がデフォルトと変わってしまったり、おかしくなる

スクロールバーのインタラクション（クリック、ドラッグなど）が機能しない

パフォーマンスの問題（描画が遅い、CPU使用率が高い）

Qtバージョンの違いによる互換性問題

QStyleOptionSlider の初期化忘れ、または不適切な使用

スタイルシート (QSS) との競合

QStyleOptionSlider のプロパティの誤った変更

QStyle::subControlRect() との連携の問題

Qtバージョンの違い

例1: スクロールバーのハンドル（つまみ）の色をカスタマイズする

Qt Style Sheets (QSS) の利用

QStyle のサブクラス化（カスタムスタイル）

QPainter を使った完全なカスタム描画（paintEvent のみ）

`void QScrollBar::initStyleOption(QStyleOptionSlider *option)` に関連する一般的なエラーとトラブルシューティング