QGridLayout Class
La clase QGridLayout distribuye los widgets en una cuadrícula. Más información...
| Encabezado: | #include <QGridLayout> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | 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 ocupa el espacio que tiene a su disposición (ya sea por el diseño de su elemento padre o mediante la función parentWidget()), lo divide en filas y columnas, y coloca cada widget que gestiona 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 un ancho mínimo y un factor de expansión. El ancho mínimo es el mayor entre el establecido mediante ` setColumnMinimumWidth()` y el ancho mínimo de cada widget de esa columna. El factor de expansión se establece mediante ` setColumnStretch()` y determina cuánto espacio disponible ocupará la columna por encima de su mínimo necesario.
Normalmente, cada widget o diseño gestionado se coloca en su propia celda mediante ` addWidget()`. También es posible que un widget ocupe varias celdas utilizando las sobrecargas de ` addItem()` y ` addWidget()` que abarcan filas y columnas. Si se hace esto, QGridLayout determinará cómo distribuir el tamaño entre las columnas y filas (en función de los factores de expansión).
Para eliminar un widget de un diseño, llama a removeWidget(). Llamar a QWidget::hide() sobre un widget también elimina efectivamente el widget del diseño hasta que se llame a QWidget::show().
Esta ilustración muestra un fragmento de un cuadro de diálogo con una cuadrícula de cinco columnas y tres filas (la cuadrícula se muestra superpuesta en color magenta):

Las columnas 0, 2 y 4 de este fragmento de cuadro de diálogo están formadas por un QLabel, un QLineEdit y un QListBox. Las columnas 1 y 3 son marcadores de posición creados con setColumnMinimumWidth(). La fila 0 consta de tres objetos QLabel, la fila 1 de tres objetos QLineEdit y la fila 2 de tres objetos QListBox. Hemos utilizado columnas de marcador de posición (1 y 3) para conseguir el espacio adecuado entre las columnas.
Ten en cuenta que las columnas y las filas no tienen la misma anchura ni la misma altura. Si quieres que dos columnas tengan la misma anchura, debes establecer tú mismo que sus anchuras mínimas y sus factores de expansión sean iguales. Para ello, utiliza setColumnMinimumWidth() y setColumnStretch().
Si el QGridLayout no es el diseño de nivel superior (es decir, no gestiona toda el área del widget ni sus elementos hijos), debes añadirlo a su diseño padre al crearlo, pero antes de realizar ninguna operación con él. La forma habitual de añadir un diseño es llamando a addLayout() en el diseño padre.
Una vez añadido el diseño, puedes empezar a colocar widgets y otros diseños en las celdas de tu diseño de cuadrícula utilizando 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. El spacing() es el ancho del espaciado asignado automáticamente entre cuadros adyacentes.
Los valores predeterminados del margen de contenido los proporciona style. El valor predeterminado especificado por los estilos de Qt es 9 para los widgets hijos y 11 para las ventanas. El espaciado predeterminado es el mismo que el ancho del margen de un diseño de nivel superior, o el mismo que el del diseño padre.
Véase también QBoxLayout, QStackedLayout, Gestión de diseños y Ejemplo de diseños básicos.
Documentación de la propiedad
horizontalSpacing : int
Esta propiedad define el espaciado entre los widgets 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 la configuración 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 determina el espaciado entre los widgets dispuestos uno encima de otro
Si no se establece ningún valor explícitamente, el espaciado vertical del diseño se hereda del diseño padre o de la configuración 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 de miembro
[explicit] QGridLayout::QGridLayout(QWidget *parent = nullptr)
Crea un nuevo QGridLayout con el widget padre, parent. El diseño tiene inicialmente una fila y una columna, y se ampliará cuando se inserten nuevos elementos.
El diseño se establece directamente como el diseño de nivel superior para ` parent`. Solo puede haber un diseño de nivel superior para un widget. Se devuelve mediante ` QWidget::layout()`.
Si parent es nullptr, entonces debes insertar este diseño de cuadrícula en otro diseño, o establecerlo como diseño de un widget mediante QWidget::setLayout().
Véase también QWidget::setLayout().
[virtual noexcept] QGridLayout::~QGridLayout()
Destruye el diseño de cuadrícula. Si se trata de una cuadrícula de nivel superior, se interrumpe la gestión de la geometría.
Los widgets del diseño no se eliminan.
[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, con una extensión de 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. El diseño asume la propiedad de item.
Advertencia: No utilices esta función para añadir diseños secundarios o elementos de widget secundarios. Utiliza en su lugar addLayout() o addWidget().
void QGridLayout::addLayout(QLayout *layout, int row, int column, Qt::Alignment alignment = Qt::Alignment())
Coloca el elemento « layout » en la posición (row, column) de la cuadrícula. La posición superior izquierda es (0, 0).
La alineación se especifica mediante alignment. La alineación por defecto es 0, lo que significa que el widget ocupa toda la celda.
Una alineación distinta de cero indica que el diseño no debe expandirse para ocupar todo el espacio disponible, sino que debe ajustarse según sizeHint().
layout se convierte en un elemento secundario del diseño de cuadrícula.
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 cuadrícula de celdas, que abarca varias filas y columnas. La celda comenzará en « row », « column » y abarcará « 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.
Esta es una función sobrecargada.
void QGridLayout::addWidget(QWidget *widget, int row, int column, Qt::Alignment alignment = Qt::Alignment())
Añade el « widget » indicado a la cuadrícula de celdas en « row » y « column ». La posición superior izquierda es (0, 0) por defecto.
La alineación se especifica mediante ` alignment`. La alineación por defecto es 0, lo que significa que el widget ocupa 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 » especificado a la cuadrícula de celdas, abarcando varias filas y columnas. La celda comenzará en « fromRow », « fromColumn » y abarcará « rowSpan » filas y « columnSpan » columnas. El « widget » tendrá el valor especificado en « alignment ».
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 situada en la fila row y la columna column de la cuadrícula. Devuelve un rectángulo no válido si row o column se encuentran fuera de la cuadrícula.
Advertencia: en la versión actual de Qt, esta función no devuelve resultados válidos hasta que se haya llamado a setGeometry(), es decir, una vez que parentWidget() sea visible.
int QGridLayout::columnCount() const
Devuelve el número de columnas de esta tabla.
int QGridLayout::columnMinimumWidth(int column) const
Devuelve el espaciado entre columnas de 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 el index indicado.
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 espaciados vertical y horizontal del elemento.
Véanse 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 index) 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 como 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 tabla.
int QGridLayout::rowMinimumHeight(int row) const
Devuelve el ancho mínimo establecido 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 el ancho mínimo 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 expansión de la columna column en stretch. La primera columna es la número 0.
El factor de expansión es relativo respecto a las demás columnas de esta cuadrícula. Las columnas con un factor de expansión mayor ocupan más espacio del disponible.
El factor de expansión predeterminado es 0. Si el factor de expansión es 0 y ninguna otra columna de esta tabla puede ampliarse en absoluto, la columna puede seguir ampliándose.
Una alternativa es añadir espaciado utilizando addItem() con QSpacerItem.
Véanse 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 en minSize píxeles.
Véase también rowMinimumHeight() y setColumnMinimumWidth().
void QGridLayout::setRowStretch(int row, int stretch)
Establece el factor de expansión de la fila row en stretch. La primera fila es la número 0.
El factor de expansión es relativo con respecto a las demás filas de esta cuadrícula. Las filas con un factor de expansión mayor ocupan más espacio disponible.
El factor de expansión predeterminado es 0. Si el factor de expansión es 0 y ninguna otra fila de esta tabla puede expandirse en absoluto, la fila puede seguir expandiéndose.
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éanse 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 para la propiedad: QLayout::spacing.
Si el espaciado vertical es igual al espaciado 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 index)`.
© 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.