QScrollArea Class
La clase QScrollArea proporciona una vista de desplazamiento sobre otro widget. Más...
| Cabecera: | #include <QScrollArea> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | QAbstractScrollArea |
Propiedades
- alignment : Qt::Alignment
- widgetResizable : bool
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 hijo dentro de un marco. Si el widget excede el tamaño del marco, la vista puede proporcionar barras de desplazamiento para que se pueda ver toda el área del widget hijo. El widget hijo 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 de abajo) que contiene una etiqueta de imagen. Al escalar la imagen, el área de desplazamiento puede proporcionar las barras de desplazamiento necesarias:
 |  |  |
El aspecto de las barras de desplazamiento depende de la configuración actual de scroll bar policies. Puede controlar el aspecto de las barras de desplazamiento utilizando la funcionalidad heredada de QAbstractScrollArea.
Por ejemplo, puede configurar las propiedades QAbstractScrollArea::horizontalScrollBarPolicy y QAbstractScrollArea::verticalScrollBarPolicy. O 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().
La función widget() permite recuperar el widget hijo. La vista puede cambiar de tamaño con la función setWidgetResizable(). La alineación del widget puede especificarse con setAlignment().
Dos funciones prácticas ensureVisible() y ensureWidgetVisible() garantizan que una determinada región del contenido sea visible dentro de la ventana gráfica, desplazando el contenido si es necesario.
Sugerencias de tamaño y disposición
Cuando se utiliza un área de desplazamiento para mostrar el contenido de un widget personalizado, es importante asegurarse de que el size hint del widget hijo está ajustado a un valor adecuado. Si se utiliza un QWidget estándar para el widget hijo, puede ser necesario llamar a QWidget::setMinimumSize() para asegurarse de que el contenido del widget se muestra 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 saber que la política de tamaño del diseño también determinará el tamaño del widget. Esto es especialmente útil si pretende cambiar dinámicamente el contenido del diseño. En tales casos, si se define la propiedad size constraint del diseño como una propiedad que limita el tamaño mínimo y/o máximo del diseño (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 propiedades
alignment : Qt::Alignment
Esta propiedad contiene la alineación del widget del área de desplazamiento.
Una alineación válida es una combinación de las siguientes banderas:
Qt::AlignLeftQt::AlignHCenterQt::AlignRightQt::AlignTopQt::AlignVCenterQt::AlignBottom
Por defecto, el widget se sitúa en la esquina superior izquierda del área de desplazamiento.
Funciones de acceso:
| Qt::Alignment | alignment() const |
| void | setAlignment(Qt::Alignment) |
widgetResizable : bool
Esta propiedad indica si el área de desplazamiento debe cambiar el tamaño del widget de la vista.
Si esta propiedad está establecida a false (por defecto), el área de desplazamiento respeta el tamaño de su widget. Independientemente de esta propiedad, puede redimensionar el widget mediante programación utilizando widget()->resize(), y el área de desplazamiento se ajustará automáticamente al nuevo tamaño.
Si esta propiedad está establecida a true, el área de desplazamiento redimensionará automáticamente el widget para evitar las barras de desplazamiento donde puedan evitarse, o para aprovechar el espacio extra.
Funciones de acceso:
| bool | widgetResizable() const |
| void | setWidgetResizable(bool resizable) |
Documentación de funciones miembro
[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)
Construye un área de desplazamiento vacía con la dirección parent.
Véase también setWidget().
[virtual noexcept] QScrollArea::~QScrollArea()
Destruye el área de desplazamiento y su widget hijo.
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 forma que el punto (x, y) sea visible dentro de la región de la ventana gráfica con los márgenes especificados en píxeles por xmargin y ymargin. Si no se puede 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 forma que childWidget de QScrollArea::widget() sea visible dentro de la ventana gráfica con los márgenes especificados en píxeles por xmargin y ymargin. Si no se puede 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 área de desplazamiento widget.
widget se convierte en hijo del área de desplazamiento y se destruirá 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 es visible cuando se añade el widget, debe show() explícitamente.
Tenga en cuenta que debe añadir el diseño de widget antes de llamar a esta función; si lo añade más tarde, el widget no será visible - independientemente de cuándo show() el área de desplazamiento. En este caso, tampoco podrá show() el widget más tarde.
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 pasa la propiedad del widget a la persona que llama.
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 nullptr si no hay ninguno.
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.
