Класс QAbstractScrollArea

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

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

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

Свойства

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

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

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

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

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

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

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

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

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

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

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

Виджет 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.

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

перечисление 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().

Примечание: Если вы открываете painter, убедитесь, что открываете его для 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)

Устанавливает отступы 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

Возвращает виджет viewport.

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

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