Класс QScrollArea

Класс QScrollArea предоставляет прокручиваемый вид на другой виджет. Подробнее...

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

Свойства

• alignment : Qt::Alignment
• widgetResizable : bool

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

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

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

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

Область прокрутки используется для отображения содержимого дочернего виджета в рамках рамки. Если виджет превышает размер рамки, просмотр может обеспечить полосы прокрутки, чтобы весь виджет можно было просмотреть. Дочерний виджет должен быть указан с помощью setWidget(). Например:

QLabel *imageLabel = new QLabel;
QImage image("happyguy.png");
imageLabel->setPixmap(QPixmap::fromImage(image));

scrollArea = new QScrollArea;
scrollArea->setBackgroundRole(QPalette::Dark);
scrollArea->setWidget(imageLabel);

Код выше создаёт область прокрутки (показанную на изображениях ниже), содержащую метку изображения. При масштабировании изображения область прокрутки может обеспечить необходимые полосы прокрутки:

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

Например, вы можете установить свойства QAbstractScrollArea::horizontalScrollBarPolicy и QAbstractScrollArea::verticalScrollBarPolicy. Или, если вы хотите, чтобы полосы прокрутки динамически подстраивались при изменении содержимого области прокрутки, вы можете использовать функции horizontalScrollBar() и verticalScrollBar() (которые позволяют получить доступ к полосам прокрутки) и устанавливать значения полос прокрутки всякий раз, когда содержимое области прокрутки изменяется, используя функцию QScrollBar::setValue().

Вы можете получить дочерний виджет, используя функцию widget(). Вид можно сделать масштабируемым с помощью функции setWidgetResizable(). Выравнивание виджета можно указать с помощью setAlignment().

Две удобные функции ensureVisible() и ensureWidgetVisible() гарантируют, что определённый участок содержимого виден внутри области просмотра, прокручивая содержимое при необходимости.

Рекомендации по размерам и макеты

При использовании области прокрутки для отображения содержимого пользовательского виджета важно убедиться, что рекомендация по размеру дочернего виджета установлена в подходящее значение. Если для дочернего виджета используется стандартный QWidget, может потребоваться вызвать QWidget::setMinimumSize(), чтобы убедиться, что содержимое виджета отображается правильно в области прокрутки.

Если область прокрутки используется для отображения содержимого виджета, содержащего дочерние виджеты, организованные в макете, важно понимать, что политика размера макета также будет определять размер виджета. Это особенно полезно знать, если вы намерены динамически изменять содержимое макета. В таких случаях установка свойства ограничения размера макета на значение, которое задаёт ограничения на минимальный и/или максимальный размер макета (например, QLayout::SetMinAndMaxSize) приведёт к обновлению размера области прокрутки всякий раз, когда изменяется содержимое макета.

Полный пример использования класса QScrollArea можно найти в примере Image Viewer. Пример показывает, как комбинировать QLabel и QScrollArea для отображения изображения.

См. также QAbstractScrollArea, QScrollBar и Пример Image Viewer.

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

QScrollArea::QScrollArea(QWidget *parent = nullptr)

Создаёт пустую область прокрутки с заданным parent.

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

[virtual] QScrollArea::~QScrollArea()

Уничтожает область прокрутки и её дочерний виджет.

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

void QScrollArea::ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)

Прокручивает содержимое области прокрутки так, чтобы точка (x, y) была видна внутри области просмотра с отступами, заданными в пикселях параметрами xmargin и ymargin. Если указанную точку нельзя достигнуть, содержимое прокручивается до ближайшей допустимой позиции. Значение по умолчанию для обоих отступов составляет 50 пикселей.

void QScrollArea::ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)

Прокручивает содержимое области прокрутки так, чтобы childWidget области QScrollArea::widget() был виден внутри области просмотра с отступами, заданными в пикселях параметрами xmargin и ymargin. Если указанную точку нельзя достигнуть, содержимое прокручивается до ближайшей допустимой позиции. Значение по умолчанию для обоих отступов составляет 50 пикселей.

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

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

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

[override virtual protected] bool QScrollArea::eventFilter(QObject *o, QEvent *e)

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] bool QScrollArea::focusNextPrevChild(bool next)

Переопределяет: QWidget::focusNextPrevChild(bool next).

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

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

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

Переопределяет: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QScrollArea::setWidget(QWidget *widget)

Устанавливает widget области прокрутки.

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

Свойство autoFillBackground виджета будет установлено в true.

Если область прокрутки видна при добавлении widget, необходимо явно вызвать show().

Обратите внимание, что необходимо добавить макет widget перед вызовом этой функции; если вы добавите его позже, widget не будет виден — независимо от того, когда вы вызовете show() для области прокрутки. В этом случае вы также не сможете вызвать show() для widget позже.

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

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

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

QWidget *QScrollArea::takeWidget()

Удаляет виджет области прокрутки и передает владение им вызывающему объекту.

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

[override virtual protected] QSize QScrollArea::viewportSizeHint() const

Переопределяет: QAbstractScrollArea::viewportSizeHint() const.

QWidget *QScrollArea::widget() const

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

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