Класс QScrollBar

Виджет QScrollBar предоставляет вертикальную или горизонтальную полосу прокрутки. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Переопределённые открытые функции

Защищённые функции

Переопределённые защищённые функции

Подробное описание

Полоса прокрутки — это элемент управления, позволяющий пользователю получить доступ к частям документа, которые больше, чем видет, используемый для его отображения. Она визуально показывает текущее положение пользователя в документе и объём отображаемой части документа. Полосы прокрутки обычно оснащены другими элементами управления, которые позволяют более точно перемещаться.

Если вам нужно предоставить прокручиваемый вид на другой виджет, удобнее использовать класс QScrollArea, поскольку он предоставляет виджет представления и полосы прокрутки. QScrollBar полезен, если вам нужно реализовать аналогичную функциональность для специализированных виджетов с использованием QAbstractScrollArea; например, если вы решили наследовать от QAbstractItemView. В большинстве других ситуаций, где используется ползунок для получения значения в заданном диапазоне, класс QSlider может быть более подходящим.

Каждая полоса прокрутки имеет значение, которое указывает, насколько ползунок удалён от начала полосы прокрутки; это значение получается с помощью value() и устанавливается с помощью setValue(). Это значение всегда находится в пределах диапазона значений, определённых для полосы прокрутки, от minimum() до maximum() включительно. Диапазон допустимых значений можно задать с помощью setMinimum() и setMaximum(). При минимальном значении верхний край ползунка (для вертикальной полосы прокрутки) или левый край (для горизонтальной полосы прокрутки) будет вверху (или слева) полосы прокрутки. При максимальном значении нижний (или правый) край ползунка будет внизу (или справа) полосы прокрутки.

Длина ползунка обычно связана со значением шага страницы и обычно представляет собой пропорцию области документа, отображаемой в прокручиваемом представлении. Шаг страницы — это величина изменения значения при нажатии клавиш «Страница вверх» и «Страница вниз» и устанавливается с помощью setPageStep(). Более мелкие изменения значения, определённые шагом строки, выполняются с помощью клавиш курсора, и это значение устанавливается с помощью setSingleStep().

Обратите внимание, что диапазон значений независим от фактического размера виджета полосы прокрутки. Вам не нужно учитывать это при выборе значений для диапазона и шага страницы.

Диапазон значений, указанных для полосы прокрутки, часто определяется по-другому, чем для QSlider, поскольку необходимо учитывать длину ползунка. Если у нас есть документ с 100 строками, и мы можем отобразить только 20 строк в виджете, мы можем создать полосу прокрутки с шагом страницы 20, минимальным значением 0 и максимальным значением 80. Это даст нам полосу прокрутки с пятью «страницами».

Взаимосвязь между длиной документа, диапазоном значений, используемых в полосе прокрутки, и шагом страницы проста во многих распространённых ситуациях. Диапазон значений полосы прокрутки определяется путём вычитания выбранного шага страницы из некоторого значения, представляющего длину документа. В таких случаях полезна следующая формула: длина документа = maximum() - minimum() + pageStep().

QScrollBar поддерживает только целочисленные диапазоны. Обратите внимание, что, хотя QScrollBar обрабатывает очень большие числа, полосы прокрутки на текущих экранах не могут полезно отображать диапазоны выше примерно 100 000 пикселей. За пределами этого пользователю становится сложно управлять ползунком с помощью клавиатуры или мыши, а стрелки прокрутки будут иметь ограниченное использование.

ScrollBar наследует полный набор сигналов от QAbstractSlider:

• valueChanged() — вызывается при изменении значения полосы прокрутки. Флаг tracking() определяет, вызывается ли этот сигнал во время взаимодействия пользователя.
• rangeChanged() — вызывается при изменении диапазона значений полосы прокрутки.
• sliderPressed() — вызывается при начале перемещения ползунка пользователем.
• sliderMoved() — вызывается при перемещении ползунка пользователем.
• sliderReleased() — вызывается при отпускании ползунка пользователем.
• actionTriggered() — вызывается при изменении полосы прокрутки путём взаимодействия пользователя или через функцию triggerAction().

Полосу прокрутки можно управлять с клавиатуры, но у неё по умолчанию focusPolicy() равна Qt::NoFocus. Используйте setFocusPolicy(), чтобы включить взаимодействие с полосой прокрутки с помощью клавиатуры:

• Левая/правая клавиши перемещают горизонтальную полосу прокрутки на один шаг.
• Вверх/вниз перемещают вертикальную полосу прокрутки на один шаг.
• «Страница вверх» перемещает вверх на одну страницу.
• «Страница вниз» перемещает вниз на одну страницу.
• «Начало» перемещает в начало (минимум).
• «Конец» перемещает в конец (максимум).

Сам ползунок можно контролировать, используя функцию triggerAction() для имитации взаимодействия пользователя с элементами управления полосы прокрутки. Это полезно, если у вас много различных виджетов, использующих общий диапазон значений.

Большинство стилей GUI используют значение pageStep() для вычисления размера ползунка.

См. также QScrollArea, QSlider, QDial, QSpinBox, Руководство по проектированию GUI: Полоса прокрутки и Пример слайдеров.

Документация по членам-функциям

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

Создаёт полосу прокрутки с заданной ориентацией.

Аргумент parent передаётся конструктору QWidget.

Значение minimum по умолчанию равно 0, maximum — 99, singleStep — 1, pageStep — 10, а начальное значение value — 0.

QScrollBar::QScrollBar(QWidget *parent = nullptr)

Создаёт вертикальную полосу прокрутки.

Аргумент parent передаётся конструктору QWidget.

Значение minimum по умолчанию равно 0, maximum — 99, singleStep — 1, pageStep — 10, а начальное значение value — 0.

[virtual] QScrollBar::~QScrollBar()

Удаляет полосу прокрутки.

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

Переопределяет: QWidget::contextMenuEvent(QContextMenuEvent *event).

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

Переопределяет: QAbstractSlider::event(QEvent *e).

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

Переопределяет: QWidget::hideEvent(QHideEvent *event).

[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).