Класс 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)

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

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

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