En esta página

QScrollArea Class

La clase QScrollArea ofrece una vista con desplazamiento sobre otro widget. Más información...

Encabezado: #include <QScrollArea>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredan: QAbstractScrollArea

Propiedades

Funciones públicas

QScrollArea(QWidget *parent = nullptr)
virtual ~QScrollArea()
Qt::Alignment alignment() const
void ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)
void ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)
void setAlignment(Qt::Alignment)
void setWidget(QWidget *widget)
void setWidgetResizable(bool resizable)
QWidget *takeWidget()
QWidget *widget() const
bool widgetResizable() const

Funciones públicas reimplementadas

virtual bool focusNextPrevChild(bool next) override
virtual QSize sizeHint() const override

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override
virtual bool eventFilter(QObject *o, QEvent *e) override
virtual void resizeEvent(QResizeEvent *) override
virtual void scrollContentsBy(int dx, int dy) override
virtual QSize viewportSizeHint() const override

Descripción detallada

Un área de desplazamiento se utiliza para mostrar el contenido de un widget secundario dentro de un marco. Si el widget supera el tamaño del marco, la vista puede proporcionar barras de desplazamiento para que se pueda ver toda el área del widget secundario. El widget secundario debe especificarse con ` setWidget()`. Por ejemplo:

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

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

El código anterior crea un área de desplazamiento (que se muestra en las imágenes siguientes) que contiene una etiqueta de imagen. Al escalar la imagen, el área de desplazamiento puede proporcionar las barras de desplazamiento necesarias:

Imagen sin barra de desplazamientoImagen con una barra de desplazamiento horizontalImagen con una barra de desplazamiento horizontal y otra vertical

El aspecto de las barras de desplazamiento depende de la propiedad ` scroll bar policies` establecida en ese momento. Puedes controlar el aspecto de las barras de desplazamiento utilizando la funcionalidad heredada de ` QAbstractScrollArea`.

Por ejemplo, puede establecer las propiedades ` QAbstractScrollArea::horizontalScrollBarPolicy ` y ` QAbstractScrollArea::verticalScrollBarPolicy `. O bien, si desea que las barras de desplazamiento se ajusten dinámicamente cuando cambie el contenido del área de desplazamiento, puede utilizar las funciones ` horizontalScrollBar()` y ` verticalScrollBar()` (que le permiten acceder a las barras de desplazamiento) y establecer los valores de las barras de desplazamiento cada vez que cambie el contenido del área de desplazamiento, utilizando la función ` QScrollBar::setValue()`.

Puedes recuperar el widget secundario utilizando la función widget(). La vista se puede hacer redimensionable con la función setWidgetResizable(). La alineación del widget se puede especificar con setAlignment().

Dos funciones de conveniencia, ` ensureVisible()` y ` ensureWidgetVisible()`, garantizan que una determinada región del contenido sea visible dentro del área de visualización, desplazando el contenido si es necesario.

Recomendaciones de tamaño y diseños

Al utilizar un área de desplazamiento para mostrar el contenido de un widget personalizado, es importante asegurarse de que la propiedad ` size hint ` del widget secundario esté establecida en un valor adecuado. Si se utiliza un ` QWidget ` estándar para el widget secundario, puede ser necesario llamar a ` QWidget::setMinimumSize()` para garantizar que el contenido del widget se muestre correctamente dentro del área de desplazamiento.

Si se utiliza un área de desplazamiento para mostrar el contenido de un widget que contiene widgets hijos dispuestos en un diseño, es importante tener en cuenta que la política de tamaño del diseño también determinará el tamaño del widget. Esto resulta especialmente útil si se tiene intención de cambiar dinámicamente el contenido del diseño. En tales casos, al establecer la propiedad ` size constraint ` del diseño en un valor que imponga restricciones sobre el tamaño mínimo y/o máximo del mismo (por ejemplo, ` QLayout::SetMinAndMaxSize`), el tamaño del área de desplazamiento se actualizará cada vez que cambie el contenido del diseño.

Véase también « QAbstractScrollArea » y « QScrollBar ».

Documentación de la propiedad

alignment : Qt::Alignment

Esta propiedad define la alineación del widget del área de desplazamiento

Una alineación válida es una combinación de los siguientes indicadores:

  • Qt::AlignLeft
  • Qt::AlignHCenter
  • Qt::AlignRight
  • Qt::AlignTop
  • Qt::AlignVCenter
  • Qt::AlignBottom

Por defecto, el widget permanece anclado a la esquina superior izquierda del área de desplazamiento.

Funciones de acceso:

Qt::Alignment alignment() const
void setAlignment(Qt::Alignment)

widgetResizable : bool

Esta propiedad determina si el área de desplazamiento debe ajustar el tamaño del widget de vista

Si esta propiedad se establece en «false» (valor predeterminado), el área de desplazamiento respeta el tamaño de su widget. Independientemente de esta propiedad, puedes cambiar el tamaño del widget mediante programación utilizando widget()->resize(), y el área de desplazamiento se ajustará automáticamente al nuevo tamaño.

Si esta propiedad se establece en «true», el área de desplazamiento cambiará automáticamente el tamaño del widget para evitar las barras de desplazamiento cuando sea posible, o para aprovechar el espacio adicional.

Funciones de acceso:

bool widgetResizable() const
void setWidgetResizable(bool resizable)

Documentación de funciones de miembro

[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)

Crea un área de desplazamiento vacía con el ` parent` indicado.

Véase también setWidget().

[virtual noexcept] QScrollArea::~QScrollArea()

Elimina el área de desplazamiento y su widget secundario.

Véase también setWidget().

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

Desplaza el contenido del área de desplazamiento de modo que el punto (x, y) quede visible dentro de la región de la ventana gráfica, con los márgenes especificados en píxeles mediante xmargin y ymargin. Si no es posible alcanzar el punto especificado, el contenido se desplaza hasta la posición válida más cercana. El valor por defecto para ambos márgenes es de 50 píxeles.

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

Desplaza el contenido del área de desplazamiento de modo que el childWidget de QScrollArea::widget() quede visible dentro de la ventana de visualización, con los márgenes especificados en píxeles mediante xmargin y ymargin. Si no es posible alcanzar el punto especificado, el contenido se desplaza hasta la posición válida más cercana. El valor por defecto para ambos márgenes es de 50 píxeles.

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

Reimplementa: QAbstractScrollArea::event(QEvent *event).

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

Reimplementa: ` QObject::eventFilter` (`QObject *watched, QEvent *event)`.

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

Reimplementa: ` QWidget::focusNextPrevChild` (bool next).

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

Reimplementa: QAbstractScrollArea::resizeEvent(QResizeEvent *event).

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

Reimplementa: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QScrollArea::setWidget(QWidget *widget)

Establece el ` widget` del área de desplazamiento.

El ` widget ` pasa a ser un elemento secundario del área de desplazamiento y se eliminará cuando se elimine el área de desplazamiento o cuando se establezca un nuevo widget.

La propiedad ` autoFillBackground ` del widget se establecerá en ` true`.

Si el área de desplazamiento está visible cuando se añade el « widget », debes llamar explícitamente a ` show()`.

Ten en cuenta que debes añadir el diseño de ` widget ` antes de llamar a esta función; si lo añades más tarde, el ` widget ` no será visible, independientemente de cuándo utilices ` show()` en el área de desplazamiento. En este caso, tampoco podrás utilizar ` show()` en ` widget ` más adelante.

Véase también widget().

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

Reimplementa: QAbstractScrollArea::sizeHint() const.

QWidget *QScrollArea::takeWidget()

Elimina el widget del área de desplazamiento y transfiere la propiedad del widget al llamante.

Véase también widget().

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

Reimplementa: ` QAbstractScrollArea::viewportSizeHint()` const.

QWidget *QScrollArea::widget() const

Devuelve el widget del área de desplazamiento o, si no hay ninguno, ` nullptr `.

Véase también setWidget().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.