このページでは

QScrollBar Class

QScrollBar ウィジェットは、垂直または水平のスクロールバーを提供します。詳細...

ヘッダー: #include <QScrollBar>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
継承元: QAbstractSlider

パブリック関数

QScrollBar(QWidget *parent = nullptr)
QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)
virtual ~QScrollBar()
(since 6.10) QMenu *createStandardContextMenu(QPoint position)

再実装されたパブリック関数

virtual bool event(QEvent *event) override
virtual QSize sizeHint() const override

プロテクトされた関数

virtual void initStyleOption(QStyleOptionSlider *option) const

再実装された保護関数

virtual void contextMenuEvent(QContextMenuEvent *event) override
virtual void hideEvent(QHideEvent *) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *) override
virtual void sliderChange(QAbstractSlider::SliderChange change) override
virtual void wheelEvent(QWheelEvent *event) override

詳細な説明

スクロールバーは、表示に用いられるウィジェットよりも大きなドキュメントの一部にユーザーがアクセスできるようにするコントロールです。ドキュメント内でのユーザーの現在の位置や、表示されているドキュメントの範囲を視覚的に示します。 スクロールバーには通常、より正確なナビゲーションを可能にする他のコントロールが組み込まれています。Qt は、各プラットフォームに適した方法でスクロールバーを表示します。

別のウィジェット上にスクロール可能なビューを提供する必要がある場合は、QScrollArea クラスを使用すると便利です。このクラスは、ビューポートウィジェットとスクロールバーを提供します。 QScrollBarは、QAbstractScrollArea を使用して特殊なウィジェットに同様の機能を実装する必要がある場合に役立ちます。たとえば、QAbstractItemView をサブクラス化する場合などです。スライダーコントロールを使用して、所定の範囲内の値を取得するその他のほとんどの場合には、QSlider クラスの方がニーズに適している可能性があります。

スクロールバーの構成要素(スライダー、スクロール矢印、ページコントロールなど)

スクロールバーには通常、スライダー、スクロール矢印、ページ制御の4つの独立したコントロールが含まれます。
  • a. スライダーは、ドキュメントの任意の場所に素早く移動する手段を提供しますが、大規模なドキュメント内での正確なナビゲーションには対応していません。
  • b. スクロール矢印は、ドキュメント内の特定の場所に正確に移動するために使用できるプッシュボタンです。テキストエディタに接続された垂直スクロールバーの場合、これらは通常、現在の位置を 1 「行」分上下に移動させ、スライダーの位置をわずかに調整します。 エディタやリストボックスでは、「1行」はテキストの1行を意味する場合もありますが、画像ビューアでは20ピクセルを意味する場合もあります。
  • c. ページコントロールとは、スライダーがドラッグされる領域(スクロールバーの背景)のことです。ここをクリックすると、スクロールバーがクリック位置に向かって1「ページ」分移動します。この値は通常、スライダーの長さと同じです。

各スクロールバーには、スライダーがスクロールバーの先頭からどれだけ離れているかを示す値があります。これはvalue()で取得し、setValue()で設定します。この値は常に、minimum()からmaximum()までの範囲内(両端を含む)に収まります。 許容値の範囲は、setMinimum() およびsetMaximum() を使用して設定できます。最小値の場合、スライダーの上端(垂直スクロールバーの場合)または左端(水平スクロールバーの場合)は、スクロールバーの上端(または左端)に位置します。 最大値では、スライダーの下端(または右端)がスクロールバーの下端(または右端)に位置します。

スライダーの長さは通常、ページステップの値に関連しており、一般的に、スクロールビューに表示されるドキュメント領域の割合を表します。 ページステップは、ユーザーがPage Up キーおよびPage Down キーを押したときに値が変化する量であり、setPageStep() で設定されます。行ステップで定義された値に対するより小さな変更は、カーソルキーを使用して行われ、この量はsetSingleStep() で設定されます。

なお、使用される値の範囲は、スクロールバーウィジェットの実際のサイズとは無関係であることに注意してください。範囲やページステップの値を選択する際、この点を考慮する必要はありません。

スクロールバーに指定される値の範囲は、スライダーの長さを考慮する必要があるため、QSlider の場合とは異なる方法で決定されることがよくあります。 100 行のドキュメントがあり、ウィジェットに 20 行しか表示できない場合、ページステップを 20、最小値を 0、最大値を 80 としてスクロールバーを構築するとよいでしょう。これにより、5 つの「ページ」を持つスクロールバーが得られます。

スクロールバーのドキュメント長、スクロール範囲、およびページステップ文書の長さ、スクロールバーで使用される値の範囲、およびページステップの関係は、多くの一般的な状況において単純です。 スクロールバーの値の範囲は、ドキュメントの長さを表す値から選択したページステップを引くことで決定されます。このような場合、次の式が役立ちます:ドキュメントの長さ=maximum() -minimum() +pageStep()。

QScrollBar は整数の範囲のみを提供します。QScrollBar は非常に大きな数値を扱うことができますが、現在の画面上のスクロールバーでは、約 100,000 ピクセルを超える範囲を実用的に表現することはできない点に注意してください。それ以上になると、ユーザーがキーボードやマウスを使ってスライダーを操作することが困難になり、スクロール矢印の有用性も限られてしまいます。

ScrollBarは、QAbstractSlider から包括的なシグナルセットを継承しています:

  • valueChanged() は、スクロールバーの値が変更されたときに発火します。tracking プロパティは、ユーザーの操作中にこのシグナルが発火するかどうかを決定します。
  • rangeChanged() は、スクロールバーの値の範囲が変更されたときに発火します。
  • sliderPressed() は、ユーザーがスライダーのドラッグを開始したときに発火します。
  • sliderMoved() は、ユーザーがスライダーをドラッグしたときに発火します。
  • sliderReleased() は、ユーザーがスライダーを離したときに発火します。
  • actionTriggered() は、ユーザーの操作または `triggerAction()` 関数によってスクロールバーが変更されたときに発火します。

スクロールバーはキーボードで操作できますが、デフォルトのfocusPolicy()はQt::NoFocus です。setFocusPolicy()を使用して、スクロールバーとのキーボード操作を有効にします:

  • 左/右:水平スクロールバーを1ステップずつ移動させます。
  • 上/下キー:垂直スクロールバーを1ステップずつ移動します。
  • PageUp キーを押すと、1ページ分上に移動します。
  • PageDown:1ページ分下に移動します。
  • Home:先頭(最小値)に移動します。
  • End:末尾(最大)に移動します。

スライダー自体は、triggerAction() 関数を使用して、スクロールバーコントロールに対するユーザーの操作をシミュレートすることで制御できます。これは、共通の値の範囲を使用するさまざまなウィジェットが多数ある場合に役立ちます。

ほとんどの GUI スタイルでは、pageStep() の値を使用してスライダーのサイズを計算します。

QScrollArea 、QSlider 、QDial 、QSpinBox 、および「スライダーの例」も参照してください 。

メンバ関数のドキュメント

[explicit] QScrollBar::QScrollBar(QWidget *parent = nullptr)

垂直スクロールバーを作成します。

parent 引数は、QWidget コンストラクタに渡されます。

minimum のデフォルト値は0、maximum のデフォルト値は99、singleStep のサイズは1、pageStep のサイズは10、初期のvalue は0に設定されます。

[explicit] QScrollBar::QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)

指定されたorientation を使用してスクロールバーを作成します。

parent 引数は、QWidget のコンストラクタに渡されます。

minimum のデフォルト値は0、maximum のデフォルト値は99、singleStep のサイズは1、pageStep のサイズは10、初期のvalue は0となります。

[virtual noexcept] QScrollBar::~QScrollBar()

スクロールバーを非表示にします。

[override virtual protected] void QScrollBar::contextMenuEvent(QContextMenuEvent *event)

QWidget::contextMenuEvent(QContextMenuEvent *event) を再実装します。

createStandardContextMenu() で作成された標準のコンテキストメニューを表示します。

スクロールバーにコンテキストメニューを表示させたくない場合は、そのcontextMenuPolicy をQt::NoContextMenu に設定できます。また、SH_ScrollBar_ContextMenuヒントを使用して、スタイルでこの動作を制御することも可能です。

コンテキストメニューをカスタマイズしたい場合は、この関数を再実装してください。標準のコンテキストメニューを拡張したい場合は、この関数を再実装し、createStandardContextMenu() を呼び出して、返されたメニューを拡張してください。返されたQMenu は、後で再利用するために保存するか、WA_DeleteOnClose 属性を設定してください。

イベントに関する情報は、event オブジェクトを通じて渡されます。

[since 6.10] QMenu *QScrollBar::createStandardContextMenu(QPoint position)

ユーザーがスクロールバーをマウスの右ボタンでクリックした際に表示される標準のコンテキストメニューを作成します。この関数は、デフォルトのcontextMenuEvent()ハンドラから呼び出され、このウィジェットのローカル座標系におけるマウスクリックの位置を表すposition を受け取ります。ポップアップメニューの所有権は呼び出し元に引き継がれます。

この関数は Qt 6.10 で導入されました。

[override virtual] bool QScrollBar::event(QEvent *event)

QAbstractSlider::event(QEvent *e) を再実装します。

[override virtual protected] void QScrollBar::hideEvent(QHideEvent *)

QWidget::hideEvent(QHideEvent *event) の再実装です。

[virtual protected] void QScrollBar::initStyleOption(QStyleOptionSlider *option) const

option を、QScrollBar の値を用いて初期化します。このメソッドは、QStyleOptionSlider が必要であるものの、すべての情報を自分で入力したくないサブクラスにとって便利です。

QStyleOption::initFrom()も参照してください 。

[override virtual protected] void QScrollBar::mouseMoveEvent(QMouseEvent *e)

QWidget::mouseMoveEvent(QMouseEvent *event) を再実装します。

[override virtual protected] void QScrollBar::mousePressEvent(QMouseEvent *e)

QWidget::mousePressEvent(QMouseEvent *event) を再実装します。

[override virtual protected] void QScrollBar::mouseReleaseEvent(QMouseEvent *e)

QWidget::mouseReleaseEvent(QMouseEvent *event) の再実装です。

[override virtual protected] void QScrollBar::paintEvent(QPaintEvent *)

QWidget::paintEvent(QPaintEvent *event) を再実装しています。

[override virtual] QSize QScrollBar::sizeHint() const

プロパティ「QWidget::sizeHint 」のアクセス関数を再実装します。

[override virtual protected] void QScrollBar::sliderChange(QAbstractSlider::SliderChange change)

QAbstractSlider::sliderChange (QAbstractSlider::SliderChange change)を再実装します。

[override virtual protected] void QScrollBar::wheelEvent(QWheelEvent *event)

QAbstractSlider::wheelEvent(QWheelEvent *e) を再実装します。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.