Класс QScrollBar

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

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

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

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

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

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

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

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

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

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

Длина ползунка обычно связана со значением шага страницы и, как правило, представляет собой пропорцию области документа, отображаемой в области прокрутки. Шаг страницы — это величина изменения значения при нажатии пользователем клавиш Page Up и Page Down, и задается с помощью 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(), чтобы включить взаимодействие с полосой прокрутки с помощью клавиатуры:

• Левый/правый перемещают горизонтальную полосу прокрутки на один шаг.
• Вверх/вниз перемещают вертикальную полосу прокрутки на один шаг.
• PageUp — перемещение вверх на одну страницу.
• PageDown — перемещение вниз на одну страницу.
• Home — перемещение в начало (минимум).
• End — перемещение в конец (максимум).

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

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

См. также QScrollArea, QSlider, QDial, QSpinBox, Справочник по проектированию графического интерфейса пользователя: полоса прокрутки и Пример слайдеров.

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

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

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

Аргумент 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() const.

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