QGridLayout Class
La clase QGridLayout dispone los widgets en una rejilla. Más...
| Cabecera: | #include <QGridLayout> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | QLayout |
Propiedades
- horizontalSpacing : int
- verticalSpacing : int
Funciones públicas
| QGridLayout(QWidget *parent = nullptr) | |
| virtual | ~QGridLayout() |
| void | addItem(QLayoutItem *item, int row, int column, int rowSpan = 1, int columnSpan = 1, Qt::Alignment alignment = Qt::Alignment()) |
| void | addLayout(QLayout *layout, int row, int column, Qt::Alignment alignment = Qt::Alignment()) |
| void | addLayout(QLayout *layout, int row, int column, int rowSpan, int columnSpan, Qt::Alignment alignment = Qt::Alignment()) |
| void | addWidget(QWidget *widget, int row, int column, Qt::Alignment alignment = Qt::Alignment()) |
| void | addWidget(QWidget *widget, int fromRow, int fromColumn, int rowSpan, int columnSpan, Qt::Alignment alignment = Qt::Alignment()) |
| QRect | cellRect(int row, int column) const |
| int | columnCount() const |
| int | columnMinimumWidth(int column) const |
| int | columnStretch(int column) const |
| void | getItemPosition(int index, int *row, int *column, int *rowSpan, int *columnSpan) const |
| int | horizontalSpacing() const |
| QLayoutItem * | itemAtPosition(int row, int column) const |
| Qt::Corner | originCorner() const |
| int | rowCount() const |
| int | rowMinimumHeight(int row) const |
| int | rowStretch(int row) const |
| void | setColumnMinimumWidth(int column, int minSize) |
| void | setColumnStretch(int column, int stretch) |
| void | setHorizontalSpacing(int spacing) |
| void | setOriginCorner(Qt::Corner corner) |
| void | setRowMinimumHeight(int row, int minSize) |
| void | setRowStretch(int row, int stretch) |
| void | setVerticalSpacing(int spacing) |
| int | verticalSpacing() const |
Funciones públicas reimplementadas
| virtual int | count() const override |
| virtual Qt::Orientations | expandingDirections() const override |
| virtual bool | hasHeightForWidth() const override |
| virtual int | heightForWidth(int w) const override |
| virtual void | invalidate() override |
| virtual QLayoutItem * | itemAt(int index) const override |
| virtual QSize | maximumSize() const override |
| virtual int | minimumHeightForWidth(int w) const override |
| virtual QSize | minimumSize() const override |
| virtual void | setGeometry(const QRect &rect) override |
| virtual void | setSpacing(int spacing) override |
| virtual QSize | sizeHint() const override |
| virtual int | spacing() const override |
| virtual QLayoutItem * | takeAt(int index) override |
Funciones protegidas reimplementadas
| virtual void | addItem(QLayoutItem *item) override |
Descripción Detallada
QGridLayout toma el espacio disponible (por su layout padre o por parentWidget()), lo divide en filas y columnas, y coloca cada widget que maneja en la celda correcta.
Las columnas y las filas se comportan de forma idéntica; hablaremos de las columnas, pero existen funciones equivalentes para las filas.
Cada columna tiene una anchura mínima y un factor de estiramiento. La anchura mínima es la mayor de las establecidas usando setColumnMinimumWidth() y la anchura mínima de cada widget en esa columna. El factor de estiramiento se establece utilizando setColumnStretch() y determina cuánto espacio disponible tendrá la columna por encima de su mínimo necesario.
Normalmente, cada widget o diseño gestionado se coloca en una celda propia utilizando addWidget(). También es posible que un widget ocupe varias celdas utilizando las sobrecargas de extensión de filas y columnas de addItem() y addWidget(). Si haces esto, QGridLayout adivinará cómo distribuir el tamaño entre las columnas/filas (basándose en los factores de estiramiento).
Para eliminar un widget de un layout, llama a removeWidget(). Llamar a QWidget::hide() en un widget también elimina el widget del diseño hasta que se llame a QWidget::show().
Esta ilustración muestra un fragmento de un diálogo con una rejilla de cinco columnas y tres filas (la rejilla se muestra superpuesta en magenta):

Las columnas 0, 2 y 4 de este fragmento de diálogo están formadas por un QLabel, un QLineEdit, y un QListBox. Las columnas 1 y 3 son marcadores de posición hechos con setColumnMinimumWidth(). La fila 0 está formada por tres objetos QLabel, la fila 1 por tres objetos QLineEdit y la fila 2 por tres objetos QListBox. Hemos utilizado columnas de marcadores de posición (1 y 3) para obtener la cantidad correcta de espacio entre las columnas.
Ten en cuenta que las columnas y filas no son igualmente anchas o altas. Si quieres que dos columnas tengan el mismo ancho, debes establecer tu mismo sus anchos mínimos y factores de estiramiento. Esto se hace usando setColumnMinimumWidth() y setColumnStretch().
Si el QGridLayout no es el layout de nivel superior (es decir, no gestiona todas las áreas e hijos del widget), debes añadirlo a su layout padre cuando lo crees, pero antes de hacer nada con él. La forma normal de añadir un layout es llamando a addLayout() en el layout padre.
Una vez que hayas añadido tu layout puedes empezar a poner widgets y otros layouts en las celdas de tu grid layout usando addWidget(), addItem(), y addLayout().
QGridLayout también incluye dos anchos de margen: el contents margin y el spacing(). El margen de contenido es el ancho del espacio reservado a lo largo de cada uno de los cuatro lados del QGridLayout. spacing () es la anchura del espacio asignado automáticamente entre cajas vecinas.
Los valores por defecto del margen de contenido son proporcionados por style. El valor por defecto que especifican los estilos Qt es 9 para los widgets hijos y 11 para las ventanas. El espaciado por defecto es el mismo que el ancho del margen para un diseño de nivel superior, o el mismo que el diseño padre.
Véase también QBoxLayout, QStackedLayout, Gestión de maquetaciones y Ejemplo de maquetaciones básicas.
Documentación de propiedades
horizontalSpacing : int
Esta propiedad contiene el espaciado entre los widgets que están dispuestos uno al lado del otro.
Si no se establece ningún valor explícitamente, el espaciado horizontal del diseño se hereda del diseño padre, o de los ajustes de estilo del widget padre.
Funciones de acceso:
| int | horizontalSpacing() const |
| void | setHorizontalSpacing(int spacing) |
Véase también verticalSpacing, QStyle::pixelMetric(), y PM_LayoutHorizontalSpacing.
verticalSpacing : int
Esta propiedad contiene el espaciado entre los widgets que están dispuestos uno encima del otro.
Si no se establece ningún valor explícitamente, el espaciado vertical del diseño se hereda del diseño padre, o de los ajustes de estilo del widget padre.
Funciones de acceso:
| int | verticalSpacing() const |
| void | setVerticalSpacing(int spacing) |
Véase también horizontalSpacing, QStyle::pixelMetric(), y PM_LayoutHorizontalSpacing.
Documentación de las funciones miembro
[explicit] QGridLayout::QGridLayout(QWidget *parent = nullptr)
Construye un nuevo QGridLayout con el widget padre, parent. El layout tiene inicialmente una fila y una columna, y se expandirá cuando se inserten nuevos elementos.
El layout se establece directamente como el layout de nivel superior para parent. Sólo puede haber un diseño de nivel superior para un widget. Se devuelve mediante QWidget::layout().
Si parent es nullptr, entonces debe insertar este diseño de rejilla en otro diseño, o establecerlo como diseño de un widget utilizando QWidget::setLayout().
Véase también QWidget::setLayout().
[virtual noexcept] QGridLayout::~QGridLayout()
Destruye el diseño de la rejilla. La gestión de la geometría finaliza si se trata de una rejilla de nivel superior.
Los widgets del diseño no se destruyen.
[override virtual protected] void QGridLayout::addItem(QLayoutItem *item)
Reimplementa: QLayout::addItem(QLayoutItem *item).
void QGridLayout::addItem(QLayoutItem *item, int row, int column, int rowSpan = 1, int columnSpan = 1, Qt::Alignment alignment = Qt::Alignment())
Añade item en la posición row, column, abarcando rowSpan filas y columnSpan columnas, y lo alinea según alignment. Si rowSpan y/o columnSpan es -1, el elemento se extenderá hasta el borde inferior y/o derecho, respectivamente. La maquetación se apropia de item.
Advertencia: No utilice esta función para añadir layouts hijos o elementos widget hijos. Utilice addLayout() o addWidget() en su lugar.
void QGridLayout::addLayout(QLayout *layout, int row, int column, Qt::Alignment alignment = Qt::Alignment())
Coloca el layout en la posición (row, column) de la cuadrícula. La posición superior izquierda es (0, 0).
La alineación se especifica en alignment. La alineación por defecto es 0, lo que significa que el widget llena toda la celda.
Una alineación distinta de cero indica que el diseño no debe crecer para llenar el espacio disponible, sino que debe dimensionarse según sizeHint().
layout se convierte en un hijo del grid layout.
void QGridLayout::addLayout(QLayout *layout, int row, int column, int rowSpan, int columnSpan, Qt::Alignment alignment = Qt::Alignment())
Esta versión añade el diseño layout a la rejilla de celdas, abarcando múltiples filas/columnas. La celda comenzará en row, column abarcando rowSpan filas y columnSpan columnas.
Si rowSpan y/o columnSpan es -1, el diseño se extenderá hasta el borde inferior y/o derecho, respectivamente.
Se trata de una función sobrecargada.
void QGridLayout::addWidget(QWidget *widget, int row, int column, Qt::Alignment alignment = Qt::Alignment())
Añade el widget dado a la cuadrícula de celdas en row, column. La posición superior izquierda es (0, 0) por defecto.
La alineación se especifica en alignment. La alineación por defecto es 0, lo que significa que el widget llena toda la celda.
void QGridLayout::addWidget(QWidget *widget, int fromRow, int fromColumn, int rowSpan, int columnSpan, Qt::Alignment alignment = Qt::Alignment())
Esta versión añade el widget dado a la cuadrícula de la celda, abarcando múltiples filas/columnas. La celda comenzará en fromRow, fromColumn abarcando rowSpan filas y columnSpan columnas. El widget tendrá el alignment dado.
Si rowSpan y/o columnSpan es -1, el widget se extenderá hasta el borde inferior y/o derecho, respectivamente.
Esta es una función sobrecargada.
QRect QGridLayout::cellRect(int row, int column) const
Devuelve la geometría de la celda con fila row y columna column en la rejilla. Devuelve un rectángulo inválido si row o column están fuera de la rejilla.
Advertencia: en la versión actual de Qt esta función no devuelve resultados válidos hasta que se ha llamado a setGeometry(), es decir, después de que parentWidget() sea visible.
int QGridLayout::columnCount() const
Devuelve el número de columnas de esta cuadrícula.
int QGridLayout::columnMinimumWidth(int column) const
Devuelve el espaciado entre columnas para la columna column.
Véase también setColumnMinimumWidth().
int QGridLayout::columnStretch(int column) const
Devuelve el factor de estiramiento de la columna column.
Véase también setColumnStretch().
[override virtual] int QGridLayout::count() const
Reimplementa: QLayout::count() const.
[override virtual] Qt::Orientations QGridLayout::expandingDirections() const
Reimplementa: QLayout::expandingDirections() const.
void QGridLayout::getItemPosition(int index, int *row, int *column, int *rowSpan, int *columnSpan) const
Devuelve la información de posición del elemento con la dirección index.
Las variables pasadas como row y column se actualizan con la posición del elemento en el diseño, y las variables rowSpan y columnSpan se actualizan con los espacios vertical y horizontal del elemento.
Véase también itemAtPosition() y itemAt().
[override virtual] bool QGridLayout::hasHeightForWidth() const
Reimplementa: QLayoutItem::hasHeightForWidth() const.
[override virtual] int QGridLayout::heightForWidth(int w) const
Reimplementa: QLayoutItem::heightForWidth(int) const.
[override virtual] void QGridLayout::invalidate()
Reimplementa: QLayout::invalidate().
[override virtual] QLayoutItem *QGridLayout::itemAt(int index) const
Reimplementa: QLayout::itemAt(int índice) const.
QLayoutItem *QGridLayout::itemAtPosition(int row, int column) const
Devuelve el elemento de diseño que ocupa la celda (row, column), o nullptr si la celda está vacía.
Véase también getItemPosition() y indexOf().
[override virtual] QSize QGridLayout::maximumSize() const
Reimplementa: QLayout::maximumSize() const.
[override virtual] int QGridLayout::minimumHeightForWidth(int w) const
Reimplementa: QLayoutItem::minimumHeightForWidth(int w) const.
[override virtual] QSize QGridLayout::minimumSize() const
Reimplementa: QLayout::minimumSize() const.
Qt::Corner QGridLayout::originCorner() const
Devuelve la esquina que se utiliza para el origen de la cuadrícula, es decir, para la posición (0, 0).
Véase también setOriginCorner().
int QGridLayout::rowCount() const
Devuelve el número de filas de esta cuadrícula.
int QGridLayout::rowMinimumHeight(int row) const
Devuelve la anchura mínima establecida para la fila row.
Véase también setRowMinimumHeight().
int QGridLayout::rowStretch(int row) const
Devuelve el factor de estiramiento de la fila row.
Véase también setRowStretch().
void QGridLayout::setColumnMinimumWidth(int column, int minSize)
Establece la anchura mínima de la columna column en minSize píxeles.
Véase también columnMinimumWidth() y setRowMinimumHeight().
void QGridLayout::setColumnStretch(int column, int stretch)
Establece el factor de estiramiento de la columna column a stretch. La primera columna es la número 0.
El factor de estiramiento es relativo a las otras columnas de esta cuadrícula. Las columnas con un factor de estiramiento mayor ocupan más espacio.
El factor de estiramiento por defecto es 0. Si el factor de estiramiento es 0 y ninguna otra columna en esta tabla puede crecer en absoluto, la columna todavía puede crecer.
Un enfoque alternativo es añadir espaciado utilizando addItem() con un QSpacerItem.
Véase también columnStretch() y setRowStretch().
[override virtual] void QGridLayout::setGeometry(const QRect &rect)
Reimplementa: QLayout::setGeometry(const QRect &r).
void QGridLayout::setOriginCorner(Qt::Corner corner)
Establece la esquina de origen de la cuadrícula, es decir, la posición (0, 0), en corner.
Véase también originCorner().
void QGridLayout::setRowMinimumHeight(int row, int minSize)
Establece la altura mínima de la fila row a minSize píxeles.
Véase también rowMinimumHeight() y setColumnMinimumWidth().
void QGridLayout::setRowStretch(int row, int stretch)
Establece el factor de estiramiento de la fila row a stretch. La primera fila es el número 0.
El factor de estiramiento es relativo a las otras filas de esta cuadrícula. Las filas con un factor de estiramiento mayor ocupan más espacio.
El factor de estiramiento por defecto es 0. Si el factor de estiramiento es 0 y ninguna otra fila en esta tabla puede crecer en absoluto, la fila todavía puede crecer.
Véase también rowStretch(), setRowMinimumHeight(), y setColumnStretch().
[override virtual] void QGridLayout::setSpacing(int spacing)
Reimplementa una función de acceso para la propiedad: QLayout::spacing.
Esta función establece tanto el espaciado vertical como el horizontal en spacing.
Véase también spacing(), setVerticalSpacing() y setHorizontalSpacing().
[override virtual] QSize QGridLayout::sizeHint() const
Reimplementa: QLayoutItem::sizeHint() const.
[override virtual] int QGridLayout::spacing() const
Reimplementa una función de acceso a la propiedad: QLayout::spacing.
Si el espaciado vertical es igual al horizontal, esta función devuelve ese valor; en caso contrario, devuelve -1.
Véase también setSpacing(), verticalSpacing(), y horizontalSpacing().
[override virtual] QLayoutItem *QGridLayout::takeAt(int index)
Reimplementa: QLayout::takeAt(int índice).
© 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.