En esta página

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

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):

Un diseño en cuadrícula

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.