Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

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 ` 클래스를 사용하는 것이 더 편리할 수 있습니다. QAbstractScrollArea 를 사용하여 특수한 위젯에 유사한 기능을 구현해야 하는 경우, 예를 들어 QAbstractItemView 의 서브클래스를 만들기로 결정한 경우, QScrollBar가 유용합니다. 주어진 범위 내에서 값을 얻기 위해 슬라이더 컨트롤이 사용되는 대부분의 다른 상황에서는 QSlider 클래스가 필요에 더 적합할 수 있습니다.

슬라이더, 스크롤 화살표, 페이지 컨트롤 등 스크롤 바의 구성 요소들

스크롤 바에는 일반적으로 슬라이더, 스크롤 화살표, 페이지 컨트롤 등 네 가지 별개의 컨트롤이 포함됩니다.
  • a. 슬라이더는 문서의 어느 부분으로든 빠르게 이동할 수 있는 방법을 제공하지만, 대용량 문서 내에서 정확한 탐색은 지원하지 않습니다.
  • b. 스크롤 화살표는 문서 내의 특정 위치로 정확하게 이동하는 데 사용할 수 있는 푸시 버튼입니다. 텍스트 편집기에 연결된 수직 스크롤 막대의 경우, 이 버튼은 일반적으로 현재 위치를 한 “줄” 위나 아래로 이동시키고 슬라이더의 위치를 약간 조정합니다. 편집기나 목록 상자에서 “줄”은 텍스트 한 줄을 의미할 수 있으며, 이미지 뷰어에서는 20픽셀을 의미할 수도 있습니다.
  • c. 페이지 컨트롤은 슬라이더가 드래그되는 영역(스크롤 바의 배경)입니다. 이곳을 클릭하면 스크롤 바가 클릭 지점 쪽으로 “한 페이지”만큼 이동합니다. 이 값은 대개 슬라이더의 길이와 동일합니다.

각 스크롤 바에는 슬라이더가 스크롤 바의 시작점에서 얼마나 떨어져 있는지를 나타내는 값이 있으며, 이 값은 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()를 사용하여 스크롤 바에 대한 키보드 상호작용을 활성화하십시오:

  • 좌/우: 수평 스크롤 막대를 한 단계씩 이동합니다.
  • 위/아래 키는 수직 스크롤바를 한 칸씩 이동시킵니다.
  • PageUp 키를 누르면 한 페이지 위로 이동합니다.
  • PageDown 키를 누르면 한 페이지 아래로 이동합니다.
  • 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.