Класс QAbstractScrollArea

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

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

Открытые типы

Свойства

• horizontalScrollBarPolicy : Qt::ScrollBarPolicy
• sizeAdjustPolicy : SizeAdjustPolicy
• verticalScrollBarPolicy : Qt::ScrollBarPolicy

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

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

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

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

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

QAbstractScrollArea — это абстрактный базовый класс области прокрутки. Область содержит центральный виджет, называемый viewport, в котором отображаются содержимое области при прокрутке (то есть видимые части содержимого отображаются в viewport).

Рядом с viewport находится вертикальная полоса прокрутки, а под ней — горизонтальная. Когда всё содержимое области помещается в viewport, каждая полоса прокрутки может быть либо видимой, либо скрытой в зависимости от значения Qt::ScrollBarPolicy полосы прокрутки. Когда полоса прокрутки скрыта, viewport расширяется, чтобы занять всё доступное пространство. Когда полоса прокрутки становится видимой снова, viewport уменьшается, чтобы освободить место для полосы прокрутки.

Можно зарезервировать область отступа вокруг viewport, см. setViewportMargins(). Эта функция в основном используется для размещения виджета QHeaderView над или рядом с областью прокрутки. Подклассы QAbstractScrollArea должны реализовывать отступы.

При наследовании от QAbstractScrollArea необходимо выполнить следующие действия:

• Управлять полосами прокрутки, задавая их диапазон, значение, шаг страницы и отслеживать их перемещения.
• Отображать содержимое области в viewport в соответствии со значениями полос прокрутки.
• Обрабатывать события, полученные viewport в viewportEvent() — в частности, события изменения размера.
• Использовать viewport->update() для обновления содержимого viewport вместо update(), поскольку все операции рисования выполняются в viewport.

С политикой полос прокрутки Qt::ScrollBarAsNeeded (по умолчанию), QAbstractScrollArea отображает полосы прокрутки, когда они предоставляют ненулевой диапазон прокрутки, и скрывает их в противном случае.

Полосы прокрутки и viewport должны обновляться всякий раз, когда viewport получает событие изменения размера или меняется размер содержимого. Viewport также необходимо обновлять, когда изменяются значения полос прокрутки. Начальные значения полос прокрутки часто задаются при получении областью нового содержимого.

Мы приводим простой пример, в котором мы реализовали область прокрутки, которая может прокручивать любой QWidget. Мы делаем виджет дочерним элементом viewport; таким образом, нам не нужно рассчитывать, какую часть виджета нужно отобразить, а можно просто переместить виджет с помощью QWidget::move(). Когда содержимое области или размер viewport изменяются, мы выполняем следующие действия:

    QSize areaSize = viewport()->size();
    QSize  widgetSize = widget->size();

    verticalScrollBar()->setPageStep(areaSize.height());
    horizontalScrollBar()->setPageStep(areaSize.width());
    verticalScrollBar()->setRange(0, widgetSize.height() - areaSize.height());
    horizontalScrollBar()->setRange(0, widgetSize.width() - areaSize.width());
    updateWidgetPosition();

Когда изменяются значения полос прокрутки, нам необходимо обновить положение виджета, т.е. найти часть виджета, которая должна быть отображена в viewport:

    int hvalue = horizontalScrollBar()->value();
    int vvalue = verticalScrollBar()->value();
    QPoint topLeft = viewport()->rect().topLeft();

    widget->move(topLeft.x() - hvalue, topLeft.y() - vvalue);

Для отслеживания перемещения полос прокрутки переопределите виртуальную функцию scrollContentsBy(). Для точной настройки поведения прокрутки подключитесь к сигналу QAbstractSlider::actionTriggered() полосы прокрутки и настройте QAbstractSlider::sliderPosition по своему желанию.

Для удобства QAbstractScrollArea делает все события viewport доступными в обработчике виртуальной функции viewportEvent(). Специализированные обработчики QWidget перенаправляются на события viewport в тех случаях, когда это имеет смысл. Перенаправленные специализированные обработчики: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

QScrollArea, наследуемый от QAbstractScrollArea, обеспечивает плавную прокрутку любого QWidget (т.е. виджет прокручивается по пикселям). Необходимо наследовать от QAbstractScrollArea только в случае необходимости более специализированного поведения. Например, это верно, если всё содержимое области не подходит для отображения на QWidget, или если не требуется плавная прокрутка.

См. также QScrollArea.

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

[since 5.2] перечисление QAbstractScrollArea::SizeAdjustPolicy

Это перечисление определяет, как размер подсказки QAbstractScrollArea должен изменяться при изменении размера viewport.

Это перечисление было введено или изменено в Qt 5.2.

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

QAbstractScrollArea::QAbstractScrollArea(QWidget *parent = nullptr)

Конструктор viewport.

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

[virtual] QAbstractScrollArea::~QAbstractScrollArea()

Деструктор viewport.

void QAbstractScrollArea::addScrollBarWidget(QWidget *widget, Qt::Alignment alignment)

Добавляет widget в качестве виджета полосы прокрутки в указанном месте alignment.

Виджеты полос прокрутки отображаются рядом с горизонтальной или вертикальной полосой прокрутки и могут быть размещены с любой стороны. Если вы хотите, чтобы виджеты полос прокрутки всегда отображались, установите scrollBarPolicy соответствующей полосы прокрутки в AlwaysOn.

alignment должен быть одним из Qt::Alignleft и Qt::AlignRight, которые соответствуют горизонтальной полосе прокрутки, или Qt::AlignTop и Qt::AlignBottom, которые соответствуют вертикальной полосе прокрутки.

Виджет полосы прокрутки можно удалить, либо переродив его, либо удалив его. Также можно скрыть виджет с помощью QWidget::hide()

Виджет полосы прокрутки будет изменён так, чтобы соответствовать геометрии полосы прокрутки для текущего стиля. Ниже описан случай виджетов полос прокрутки на горизонтальной полосе прокрутки:

Высота виджета будет установлена так, чтобы соответствовать высоте полосы прокрутки. Для управления шириной виджета используйте QWidget::setMinimumWidth и QWidget::setMaximumWidth, или реализуйте QWidget::sizeHint() и установите горизонтальную политику размера. Если вам нужен квадратный виджет, вызовите QStyle::pixelMetric(QStyle::PM_ScrollBarExtent) и установите ширину в это значение.

См. также scrollBarWidgets().

[override virtual protected] void QAbstractScrollArea::contextMenuEvent(QContextMenuEvent *e)

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

Обработчик этого события может быть переопределён в подклассе для получения событий контекстного меню для виджета viewport(). Событие передаётся в e.

См. также QWidget::contextMenuEvent().

QWidget *QAbstractScrollArea::cornerWidget() const

Возвращает виджет в углу между двумя полосами прокрутки.

По умолчанию виджета в углу нет.

См. также setCornerWidget().

[override virtual protected] void QAbstractScrollArea::dragEnterEvent(QDragEnterEvent *event)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий входа перетаскивания (передаваемых в event) для виджета viewport().

См. также QWidget::dragEnterEvent().

[override virtual protected] void QAbstractScrollArea::dragLeaveEvent(QDragLeaveEvent *event)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий выхода перетаскивания (передаваемых в event) для виджета viewport().

См. также QWidget::dragLeaveEvent().

[override virtual protected] void QAbstractScrollArea::dragMoveEvent(QDragMoveEvent *event)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий перемещения перетаскивания (передаваемых в event) для виджета viewport().

См. также QWidget::dragMoveEvent().

[override virtual protected] void QAbstractScrollArea::dropEvent(QDropEvent *event)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий опускания (передаваемых в event) для виджета viewport().

См. также QWidget::dropEvent().

[override virtual protected] bool QAbstractScrollArea::event(QEvent *event)

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

Это основной обработчик событий для виджета QAbstractScrollArea (не области прокрутки viewport()). Указанное событие event — это общий объект события, который может потребоваться привести к соответствующему классу в зависимости от его типа.

См. также QEvent::type().

QScrollBar *QAbstractScrollArea::horizontalScrollBar() const

Возвращает горизонтальную полосу прокрутки.

См. также setHorizontalScrollBar(), horizontalScrollBarPolicy и verticalScrollBar().

[override virtual protected] void QAbstractScrollArea::keyPressEvent(QKeyEvent *e)

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

Этот метод вызывается с событием нажатия клавиши e при нажатии клавиш. Он обрабатывает PageUp, PageDown, Up, Down, Left и Right, и игнорирует все другие нажатия клавиш.

QSize QAbstractScrollArea::maximumViewportSize() const

Возвращает размер viewport, как если бы полосы прокрутки не имели допустимого диапазона прокрутки.

[override virtual] QSize QAbstractScrollArea::minimumSizeHint() const

Переопределяет функцию доступа к свойству: QWidget::minimumSizeHint.

[override virtual protected] void QAbstractScrollArea::mouseDoubleClickEvent(QMouseEvent *e)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий двойного щелчка мыши для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseDoubleClickEvent().

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

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

Этот обработчик событий может быть переопределен в подклассе для получения событий перемещения мыши для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseMoveEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий нажатия мыши для виджета viewport(). Событие передаётся в e.

По умолчанию вызывается QWidget::mousePressEvent() для обработки всплывающих окон по умолчанию.

См. также QWidget::mousePressEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий отпускания мыши для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseReleaseEvent().

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

Переопределяет: QFrame::paintEvent(QPaintEvent *).

Этот обработчик событий может быть переопределен в подклассе для получения событий рисования (передаваемых в event) для виджета viewport().

См. также QWidget::paintEvent().

[override virtual protected] void QAbstractScrollArea::resizeEvent(QResizeEvent *event)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий изменения размера (передаваемых в event) для виджета viewport().

Когда вызывается resizeEvent(), viewport уже имеет свою новую геометрию: новый размер доступен через функцию QResizeEvent::size(), а старый размер — через QResizeEvent::oldSize().

См. также QWidget::resizeEvent().

QWidgetList QAbstractScrollArea::scrollBarWidgets(Qt::Alignment alignment)

Возвращает список текущих установленных виджетов полос прокрутки. alignment может быть любой комбинацией четырёх флагов расположения.

См. также addScrollBarWidget().

[virtual protected] void QAbstractScrollArea::scrollContentsBy(int dx, int dy)

Этот виртуальный обработчик вызывается при перемещении полос прокрутки на dx, dy, и, следовательно, содержимое viewport должно быть прокручено соответствующим образом.

По умолчанию просто вызывается update() для всего viewport(), подклассы могут переопределить этот обработчик для оптимизации или, как QScrollArea, для перемещения виджета содержимого. Параметры dx и dy служат для удобства, чтобы класс знал, на сколько следует прокрутить (полезно, например, при выполнении сдвигов пикселей). Вы можете так же игнорировать эти значения и прокрутить напрямую до позиции, указанной полосами прокрутки.

Вызов этого метода для программируемой прокрутки является ошибкой, используйте полосы прокрутки вместо этого (например, вызвав QScrollBar::setValue() напрямую).

void QAbstractScrollArea::setCornerWidget(QWidget *widget)

Устанавливает виджет в углу между двумя полосами прокрутки в widget.

Вероятно, также потребуется установить хотя бы один из режимов полосы прокрутки в AlwaysOn.

Передача nullptr отображает отсутствие виджета в углу.

Любой предыдущий виджет угла скрывается.

Вы можете вызывать setCornerWidget() с тем же виджетом в разное время.

Все виджеты, установленные здесь, будут удалены областью прокрутки при её уничтожении, если вы не переместите виджет после установки другого виджета угла (или nullptr).

Любой новый установленный виджет не должен иметь текущего родителя.

По умолчанию угол виджета отсутствует.

См. также cornerWidget(), horizontalScrollBarPolicy и horizontalScrollBarPolicy.

void QAbstractScrollArea::setHorizontalScrollBar(QScrollBar *scrollBar)

Заменяет существующую горизонтальную полосу прокрутки на scrollBar и устанавливает все свойства ползунка предыдущей полосы прокрутки на новую. Предыдущая полоса прокрутки затем удаляется.

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

См. также horizontalScrollBar() и setVerticalScrollBar().

void QAbstractScrollArea::setVerticalScrollBar(QScrollBar *scrollBar)

Заменяет существующую вертикальную полосу прокрутки на scrollBar и устанавливает все свойства ползунка предыдущей полосы прокрутки на новую. Предыдущая полоса прокрутки затем удаляется.

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

См. также verticalScrollBar() и setHorizontalScrollBar().

void QAbstractScrollArea::setViewport(QWidget *widget)

Устанавливает область прокрутки в качестве заданного виджета widget. QAbstractScrollArea возьмёт на себя управление заданным widget.

Если widget равен nullptr, QAbstractScrollArea назначит новый экземпляр QWidget для области прокрутки.

См. также viewport().

[protected] void QAbstractScrollArea::setViewportMargins(int left, int top, int right, int bottom)

Устанавливает отступы вокруг области прокрутки до left, top, right и bottom. Это полезно для приложений, таких как электронные таблицы с "закреплёнными" строками и столбцами. Отступы остаются пустыми; размещайте виджеты в неиспользуемой области.

Обратите внимание, что эта функция часто вызывается QTreeView и QTableView, поэтому отступы должны быть реализованы подклассами QAbstractScrollArea. Кроме того, если подклассы должны использоваться в представлениях элементов, они не должны вызывать эту функцию.

По умолчанию все отступы равны нулю.

См. также viewportMargins().

[protected] void QAbstractScrollArea::setViewportMargins(const QMargins &margins)

Устанавливает margins вокруг области прокрутки. Это полезно для приложений, таких как электронные таблицы с "закреплёнными" строками и столбцами. Отступы остаются пустыми; размещайте виджеты в неиспользуемой области.

По умолчанию все отступы равны нулю.

См. также viewportMargins().

[virtual] void QAbstractScrollArea::setupViewport(QWidget *viewport)

Этот слот вызывается QAbstractScrollArea после вызова setViewport(viewport). Переопределите эту функцию в подклассе QAbstractScrollArea, чтобы инициализировать новый viewport перед его использованием.

См. также setViewport().

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

Переопределяет: QFrame::sizeHint() const.

Возвращает свойство sizeHint области прокрутки. Размер определяется с помощью viewportSizeHint() плюс дополнительное пространство для полос прокрутки, если необходимо.

QScrollBar *QAbstractScrollArea::verticalScrollBar() const

Возвращает вертикальную полосу прокрутки.

См. также setVerticalScrollBar(), verticalScrollBarPolicy и horizontalScrollBar().

QWidget *QAbstractScrollArea::viewport() const

Возвращает виджет области прокрутки.

Используйте функцию QScrollArea::widget(), чтобы получить содержимое виджета области прокрутки.

См. также setViewport() и QScrollArea::widget().

[virtual protected] bool QAbstractScrollArea::viewportEvent(QEvent *event)

Основной обработчик событий для области прокрутки (виджет viewport() ). Обрабатывает указанное событие event и может вызываться подклассами для предоставления разумного поведения по умолчанию.

Возвращает true чтобы указать системе событий, что событие обработано и не требует дальнейшей обработки; в противном случае возвращает false чтобы указать, что событие должно быть распространено дальше.

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

Специализированные обработчики событий области прокрутки: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

[protected, since 5.5] QMargins QAbstractScrollArea::viewportMargins() const

Возвращает отступы вокруг области прокрутки. По умолчанию все отступы равны нулю.

Эта функция была введена в Qt 5.5.

См. также setViewportMargins().

[virtual protected, since 5.2] QSize QAbstractScrollArea::viewportSizeHint() const

Возвращает рекомендуемый размер для области прокрутки. Стандартная реализация возвращает viewport()->sizeHint(). Обратите внимание, что размер — это только размер области прокрутки без видимых полос прокрутки.

Эта функция была введена в Qt 5.2.

[override virtual protected] void QAbstractScrollArea::wheelEvent(QWheelEvent *e)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий прокрутки для виджета viewport(). Событие передаётся в e.

См. также QWidget::wheelEvent().