Класс QAbstractScrollArea

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

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

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

Свойства

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

• 6 свойств унаследовано от QFrame
• 59 свойств унаследовано от QWidget
• 1 свойство унаследовано от QObject

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

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

• 14 открытых функций унаследовано от QFrame
• 214 открытых функций унаследовано от QWidget
• 31 открытых функций унаследовано от QObject
• 14 открытых функций унаследовано от QPaintDevice

Статические открытые члены

• 5 статических открытых членов унаследовано от QWidget
• 9 статических открытых членов унаследовано от QObject

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

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

• 4 защищённых функций, унаследованных от QFrame
• 35 защищённых функций, унаследованных от QWidget
• 9 защищённых функций, унаследованных от QObject
• 1 защищённая функция, унаследованная от QPaintDevice

Дополнительные унаследованные члены

• 19 публичных слотов, унаследованных от QWidget
• 1 публичный слот, унаследованный от QObject
• 3 сигнала, унаследованные от QWidget
• 2 сигнала, унаследованные от QObject
• 1 защищённый слот, унаследованный от QWidget

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

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

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.

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

enum QAbstractScrollArea::SizeAdjustPolicy

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

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

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

QAbstractScrollArea::QAbstractScrollArea(QWidget *parent = nullptr)

Создает область просмотра.

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

[virtual] QAbstractScrollArea::~QAbstractScrollArea()

Уничтожает область просмотра.

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) и установите ширину в это значение.

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

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

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

Переопределено из QWidget::contextMenuEvent().

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

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

QWidget *QAbstractScrollArea::cornerWidget() const

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

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

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

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

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

Переопределено из QWidget::dragEnterEvent().

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

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

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

Переопределено из QWidget::dragLeaveEvent().

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

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

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

Переопределено из QWidget::dragMoveEvent().

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

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

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

Переопределено из QWidget::dropEvent().

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

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

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

Переопределено из QFrame::event().

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

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

QScrollBar *QAbstractScrollArea::horizontalScrollBar() const

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

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

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

Переопределено из QWidget::keyPressEvent().

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

QSize QAbstractScrollArea::maximumViewportSize() const

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

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

Переопределено из QWidget::minimumSizeHint().

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

Переопределено из QWidget::mouseDoubleClickEvent().

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

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

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

Переопределено из QWidget::mouseMoveEvent().

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

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

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

Переопределено из QWidget::mousePressEvent().

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

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

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

Переопределено из QWidget::mouseReleaseEvent().

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

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

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

Переопределено из QFrame::paintEvent().

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

Примечание: Если вы открываете рисовальщик, убедитесь, что открываете его для viewport().

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

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

Переопределено из QWidget::resizeEvent().

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

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

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

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

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

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

См. также 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.

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

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

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

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

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

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

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

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

void QAbstractScrollArea::setHorizontalScrollBar(QScrollBar *scrollBar)

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

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

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

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

void QAbstractScrollArea::setVerticalScrollBar(QScrollBar *scrollBar)

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

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

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

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

void QAbstractScrollArea::setViewport(QWidget *widget)

Устанавливает viewport в указанный виджет widget. QAbstractScrollArea получит владение заданным widget.

Если widget равен 0, QAbstractScrollArea создаст новую экземпляр QWidget для viewport.

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

См. также 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)

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

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

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

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

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

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

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

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

Переопределено из QFrame::sizeHint().

Возвращает свойство 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] QMargins QAbstractScrollArea::viewportMargins() const

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

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

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

[virtual protected] QSize QAbstractScrollArea::viewportSizeHint() const

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

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

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

Переопределено из QWidget::wheelEvent().

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

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