En esta página

QLayout Class

La clase QLayout es la clase base de los gestores de geometría. Más información...

Encabezado: #include <QLayout>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de:QObject y QLayoutItem
Heredado por:

QBoxLayout, ` QFormLayout`, ` QGridLayout` y QStackedLayout

Tipos públicos

enum SizeConstraint { SetDefaultConstraint, SetFixedSize, SetMinimumSize, SetMaximumSize, SetMinAndMaxSize, SetNoConstraint }

Propiedades

Funciones públicas

QLayout(QWidget *parent = nullptr)
bool activate()
virtual void addItem(QLayoutItem *item) = 0
void addWidget(QWidget *w)
QMargins contentsMargins() const
QRect contentsRect() const
virtual int count() const = 0
void getContentsMargins(int *left, int *top, int *right, int *bottom) const
QLayout::SizeConstraint horizontalSizeConstraint() const
virtual int indexOf(const QLayoutItem *layoutItem) const
virtual int indexOf(const QWidget *widget) const
bool isEnabled() const
virtual QLayoutItem *itemAt(int index) const = 0
QWidget *menuBar() const
QWidget *parentWidget() const
void removeItem(QLayoutItem *item)
void removeWidget(QWidget *widget)
virtual QLayoutItem *replaceWidget(QWidget *from, QWidget *to, Qt::FindChildOptions options = Qt::FindChildrenRecursively)
bool setAlignment(QWidget *w, Qt::Alignment alignment)
bool setAlignment(QLayout *l, Qt::Alignment alignment)
void setContentsMargins(const QMargins &margins)
void setContentsMargins(int left, int top, int right, int bottom)
void setEnabled(bool enable)
void setHorizontalSizeConstraint(QLayout::SizeConstraint constraint)
void setMenuBar(QWidget *widget)
void setSizeConstraint(QLayout::SizeConstraint constraint)
(since 6.10) void setSizeConstraints(QLayout::SizeConstraint horizontal, QLayout::SizeConstraint vertical)
virtual void setSpacing(int)
void setVerticalSizeConstraint(QLayout::SizeConstraint constraint)
QLayout::SizeConstraint sizeConstraint() const
virtual int spacing() const
virtual QLayoutItem *takeAt(int index) = 0
(since 6.1) void unsetContentsMargins()
void update()
QLayout::SizeConstraint verticalSizeConstraint() const

Funciones públicas reimplementadas

virtual QSizePolicy::ControlTypes controlTypes() const override
virtual Qt::Orientations expandingDirections() const override
virtual QRect geometry() const override
virtual void invalidate() override
virtual bool isEmpty() const override
virtual QLayout *layout() override
virtual QSize maximumSize() const override
virtual QSize minimumSize() const override
virtual void setGeometry(const QRect &r) override

Miembros públicos estáticos

QSize closestAcceptableSize(const QWidget *widget, const QSize &size)

Funciones protegidas

void addChildLayout(QLayout *childLayout)
void addChildWidget(QWidget *w)
QRect alignmentRect(const QRect &r) const

Funciones protegidas reimplementadas

virtual void childEvent(QChildEvent *e) override

Descripción detallada

Esta es una clase base abstracta de la que heredan las clases concretas ` QBoxLayout`, ` QGridLayout`, ` QFormLayout` y ` QStackedLayout`.

Para los usuarios de las subclases de QLayout o de ` QMainWindow `, rara vez es necesario utilizar las funciones básicas que proporciona QLayout, como ` setSizeConstraint()` o ` setMenuBar()`. Consulte «Gestión de diseños» para obtener más información.

Para crear su propio gestor de diseño, implemente las funciones addItem(), sizeHint(), setGeometry(), itemAt() y takeAt(). También debe implementar minimumSize() para garantizar que su diseño no se redimensione a un tamaño cero si hay muy poco espacio. Para admitir elementos hijos cuya altura dependa de su anchura, implemente hasHeightForWidth() y heightForWidth(). Consulte el ejemplo de diseño de flujo (Flow Layout ) para obtener más información sobre cómo implementar gestores de diseño personalizados.

La gestión de la geometría se detiene cuando se elimina el gestor de diseño.

Véase también « QLayoutItem» , «Gestión de diseños», «Ejemplo de diseños básicos» y «Ejemplo de diseño de flujo».

Documentación sobre tipos de miembro

enum QLayout::SizeConstraint

Describe cómo el diseño limita el tamaño del widget.

Una restricción vertical afecta a la altura del widget, mientras que una restricción horizontal afecta a su anchura.

Los valores posibles son:

ConstanteValorDescripción
QLayout::SetDefaultConstraint0En la(s) orientación(es) restringida(s), la extensión mínima del widget se establece en minimumSize(), a menos que ya se haya establecido un tamaño mínimo.
QLayout::SetFixedSize3En las orientaciones restringidas, la extensión del widget se establece en sizeHint(), y no se puede cambiar su tamaño en esa dirección.
QLayout::SetMinimumSize2En las orientaciones restringidas, la extensión mínima del widget se establece en minimumSize().
QLayout::SetMaximumSize4En las orientaciones restringidas, la extensión máxima del widget se establece en maximumSize().
QLayout::SetMinAndMaxSize5En las orientaciones restringidas, la extensión mínima del widget se establece en minimumSize(), y la extensión máxima se establece en maximumSize().
QLayout::SetNoConstraint1No se aplican restricciones de tamaño al widget.

Véase también setSizeConstraint(), setSizeConstraints(), horizontalSizeConstraint(), setHorizontalSizeConstraint() y setVerticalSizeConstraint().

Documentación de propiedades

contentsMargins : QMargins

Esta propiedad define los márgenes que se aplican alrededor del diseño

Por defecto, QLayout utiliza los valores proporcionados por el estilo. En la mayoría de las plataformas, el margen es de 11 píxeles en todas las direcciones.

Funciones de acceso:

QMargins contentsMargins() const
void setContentsMargins(int left, int top, int right, int bottom)
void setContentsMargins(const QMargins &margins)
void unsetContentsMargins()

Véase también setContentsMargins() y getContentsMargins().

[since 6.10] horizontalSizeConstraint : SizeConstraint

Esta propiedad establece la restricción de tamaño horizontal.

El modo por defecto es QLayout::SetDefaultConstraint

Esta enumeración se introdujo en Qt 6.10.

Funciones de acceso:

QLayout::SizeConstraint horizontalSizeConstraint() const
void setHorizontalSizeConstraint(QLayout::SizeConstraint constraint)

Véase también verticalSizeConstraint() y sizeConstraint().

sizeConstraint : SizeConstraint

Esta propiedad almacena el modo de redimensionamiento del diseño. Establece la restricción de tamaño del cuadro de diálogo. Si se establece una restricción de tamaño vertical u horizontal, esta prevalecerá sobre la anterior.

El modo predeterminado es « SetDefaultConstraint ».

Funciones de acceso:

QLayout::SizeConstraint sizeConstraint() const
void setSizeConstraint(QLayout::SizeConstraint constraint)

Véase también « horizontalSizeConstraint()» y « verticalSizeConstraint()».

spacing : int

Esta propiedad determina el espaciado entre los widgets dentro del diseño

Si no se establece ningún valor de forma explícita, el espaciado del diseño se hereda del diseño padre o de la configuración de estilo del widget padre.

En el caso de QGridLayout y QFormLayout, es posible establecer espaciados horizontales y verticales diferentes utilizando setHorizontalSpacing() y setVerticalSpacing(). En ese caso, spacing() devuelve -1.

Funciones de acceso:

virtual int spacing() const
virtual void setSpacing(int)

Véase también contentsRect(), getContentsMargins(), QStyle::layoutSpacing() y QStyle::pixelMetric().

[since 6.10] verticalSizeConstraint : SizeConstraint

Esta propiedad establece la restricción de tamaño vertical.

El modo predeterminado es QLayout::SetDefaultConstraint

Esta enumeración se introdujo en Qt 6.10.

Funciones de acceso:

QLayout::SizeConstraint verticalSizeConstraint() const
void setVerticalSizeConstraint(QLayout::SizeConstraint constraint)

Véase también horizontalSizeConstraint() y sizeConstraint().

Documentación de las funciones miembro

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

Crea un nuevo QLayout de nivel superior, con el parent como padre.

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 en otro diseño o establecerlo como diseño de un widget mediante QWidget::setLayout().

Véase también QWidget::setLayout().

bool QLayout::activate()

Vuelve a calcular el diseño de parentWidget() si es necesario.

Por lo general, no debería ser necesario llamar a esta función, ya que se ejecuta automáticamente en los momentos más adecuados. Devuelve «true» si se ha vuelto a generar el diseño.

Véanse también update() y QWidget::updateGeometry().

[protected] void QLayout::addChildLayout(QLayout *childLayout)

Esta función se invoca desde las funciones ` addLayout() ` o ` insertLayout() ` en las subclases para añadir el diseño ` childLayout ` como un subdiseño.

El único caso en el que es necesario llamarla directamente es si se implementa un diseño personalizado que admita diseños anidados.

Véanse también QBoxLayout::addLayout(), QBoxLayout::insertLayout() y QGridLayout::addLayout().

[protected] void QLayout::addChildWidget(QWidget *w)

Esta función se invoca desde las funciones ` addWidget() ` de las subclases para añadir ` w ` como widget gestionado de un diseño.

Si w ya está gestionado por un diseño, esta función generará una advertencia y eliminará w de dicho diseño. Por lo tanto, esta función debe invocarse antes de añadir w a la estructura de datos del diseño.

[pure virtual] void QLayout::addItem(QLayoutItem *item)

Se implementa en las subclases para añadir un « item ». La forma de añadirlo varía según cada subclase.

Esta función no suele invocarse en el código de la aplicación. Para añadir un widget a un diseño, utiliza la función addWidget(); para añadir un diseño secundario, utiliza la función addLayout() que proporciona la subclase correspondiente de QLayout.

Nota: La propiedad de item se transfiere al diseño, y es responsabilidad de este eliminarlo.

Véanse también addWidget(), QBoxLayout::addLayout() y QGridLayout::addLayout().

void QLayout::addWidget(QWidget *w)

Añade el widget w a este diseño de una forma específica para dicho diseño. Esta función utiliza addItem().

[protected] QRect QLayout::alignmentRect(const QRect &r) const

Devuelve el rectángulo que debe cubrirse cuando la geometría de este diseño se establece en « r », siempre que este diseño admita la función « setAlignment()».

El resultado se obtiene a partir de ` sizeHint()` y ` expandingDirections()`. Nunca es mayor que ` r`.

[override virtual protected] void QLayout::childEvent(QChildEvent *e)

Reimplementa: ` QObject::childEvent(QChildEvent *event)`.

[static] QSize QLayout::closestAcceptableSize(const QWidget *widget, const QSize &size)

Devuelve un tamaño que cumple todas las restricciones de tamaño de widget, incluidas las de heightForWidth(), y que se aproxima lo máximo posible a size.

QMargins QLayout::contentsMargins() const

Devuelve los márgenes utilizados alrededor del diseño.

Por defecto, QLayout utiliza los valores proporcionados por el estilo. En la mayoría de las plataformas, el margen es de 11 píxeles en todas las direcciones.

Nota: Funcióngetter para la propiedad contentsMargins.

Véase también setContentsMargins().

QRect QLayout::contentsRect() const

Devuelve el rectángulo de la propiedad « geometry()» del diseño, pero teniendo en cuenta los márgenes del contenido.

Véase también ` setContentsMargins()` y ` getContentsMargins()`.

[override virtual] QSizePolicy::ControlTypes QLayout::controlTypes() const

Reimplementa: ` QLayoutItem::controlTypes()` const.

[pure virtual] int QLayout::count() const

Debe implementarse en las subclases para devolver el número de elementos del diseño.

Véase también itemAt().

[override virtual] Qt::Orientations QLayout::expandingDirections() const

Reimplementa: ` QLayoutItem::expandingDirections()` const.

Devuelve si este diseño puede utilizar más espacio que sizeHint(). Un valor de Qt::Vertical o Qt::Horizontal significa que quiere crecer solo en una dimensión, mientras que Qt::Vertical | Qt::Horizontal significa que quiere crecer en ambas dimensiones.

La implementación predeterminada devuelve Qt::Horizontal | Qt::Vertical. Las subclases la reimplementan para devolver un valor significativo basado en el size policies de sus widgets hijos.

Véase también sizeHint().

[override virtual] QRect QLayout::geometry() const

Reimplementa: ` QLayoutItem::geometry()` const.

Véase también setGeometry().

void QLayout::getContentsMargins(int *left, int *top, int *right, int *bottom) const

Para cada una de las direcciones left, top, right y bottom que no sea nullptr, almacena el tamaño del margen indicado en la ubicación a la que apunta el puntero.

Por defecto, QLayout utiliza los valores proporcionados por el estilo. En la mayoría de las plataformas, el margen es de 11 píxeles en todas las direcciones.

Véase también setContentsMargins(), QStyle::pixelMetric(), PM_LayoutLeftMargin, PM_LayoutTopMargin, PM_LayoutRightMargin y PM_LayoutBottomMargin.

[virtual] int QLayout::indexOf(const QLayoutItem *layoutItem) const

Busca el elemento de diseño « layoutItem » en este diseño (sin incluir los diseños secundarios).

Devuelve el índice de « layoutItem », o -1 si no se encuentra « layoutItem ».

[virtual] int QLayout::indexOf(const QWidget *widget) const

Busca el widget « widget » en este diseño (sin incluir los diseños secundarios).

Devuelve el índice de widget, o -1 si no se encuentra widget.

La implementación predeterminada recorre todos los elementos utilizando itemAt().

[override virtual] void QLayout::invalidate()

Reimplementa: QLayoutItem::invalidate().

[override virtual] bool QLayout::isEmpty() const

Reimplementa: ` QLayoutItem::isEmpty()` const.

bool QLayout::isEnabled() const

Devuelve « true » si el diseño está activado; en caso contrario, devuelve « false ».

Véase también setEnabled().

[pure virtual] QLayoutItem *QLayout::itemAt(int index) const

Debe implementarse en las subclases para devolver el elemento de diseño en index. Si no existe dicho elemento, la función debe devolver nullptr. Los elementos se numeran consecutivamente a partir de 0. Si se elimina un elemento, los demás elementos se renumerarán.

Esta función se puede utilizar para recorrer un diseño. El siguiente código dibujará un rectángulo por cada elemento de diseño presente en la estructura de diseño del widget.

static void paintLayout(QPainter *painter, QLayoutItem *item)
{
    QLayout *layout = item->layout();
    if (layout) {
        for (int i = 0; i < layout->count(); ++i)
            paintLayout(painter, layout->itemAt(i));
    }
    painter->drawRect(item->geometry());
}

void MyWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    if (layout())
        paintLayout(&painter, layout());
}

Véase también count() y takeAt().

[override virtual] QLayout *QLayout::layout()

Reimplementa: QLayoutItem::layout().

[override virtual] QSize QLayout::maximumSize() const

Reimplementa: QLayoutItem::maximumSize() const.

Devuelve el tamaño máximo de este diseño. Se trata del tamaño máximo que puede tener el diseño sin dejar de cumplir con las especificaciones.

El valor devuelto no incluye el espacio requerido por QWidget::setContentsMargins() ni por menuBar().

La implementación por defecto permite un redimensionamiento ilimitado.

Devuelve la barra de menús configurada para este diseño, o ` nullptr ` si no hay ninguna barra de menús configurada.

Véase también setMenuBar().

[override virtual] QSize QLayout::minimumSize() const

Reimplementa: ` QLayoutItem::minimumSize()` const.

Devuelve el tamaño mínimo de este diseño. Se trata del tamaño más pequeño que puede tener el diseño sin dejar de cumplir con las especificaciones.

El valor devuelto no incluye el espacio requerido por QWidget::setContentsMargins() ni por menuBar().

La implementación por defecto permite un redimensionamiento ilimitado.

QWidget *QLayout::parentWidget() const

Devuelve el widget padre de este diseño, o un objeto ` nullptr ` si este diseño no está instalado en ningún widget.

Si el diseño es un subdiseño, esta función devuelve el widget padre del diseño padre.

Véase también parent().

void QLayout::removeItem(QLayoutItem *item)

Elimina el elemento de diseño « item » del diseño. Es responsabilidad de quien realiza la llamada eliminar el elemento.

Ten en cuenta que item puede ser un diseño (ya que QLayout hereda de QLayoutItem).

Véase también removeWidget() y addItem().

void QLayout::removeWidget(QWidget *widget)

Elimina el widget widget del diseño. Tras esta llamada, es responsabilidad de quien la realiza asignar al widget una geometría adecuada, volver a colocarlo en un diseño o ocultarlo explícitamente si es necesario.

Nota: La propiedad de widget sigue siendo la misma que cuando se añadió.

Véase también removeItem(), QWidget::setGeometry() y addWidget().

[virtual] QLayoutItem *QLayout::replaceWidget(QWidget *from, QWidget *to, Qt::FindChildOptions options = Qt::FindChildrenRecursively)

Busca el widget from y lo sustituye por el widget to si lo encuentra. Devuelve el elemento de diseño que contiene el widget from si la operación se realiza con éxito. De lo contrario, se devuelve nullptr. Si options contiene Qt::FindChildrenRecursively (el valor por defecto), se buscan los subdiseños para realizar la sustitución. Se ignora cualquier otro indicador presente en options.

Tenga en cuenta que, por lo tanto, es posible que el elemento devuelto no pertenezca a este diseño, sino a un subdiseño.

El elemento de diseño devuelto ya no es propiedad del diseño y debe eliminarse o insertarse en otro diseño. El widget from ya no es gestionado por el diseño y puede que sea necesario eliminarlo u ocultarlo. El padre del widget from permanece sin cambios.

Esta función funciona con los diseños integrados de Qt, pero es posible que no funcione con diseños personalizados.

Véase también indexOf().

bool QLayout::setAlignment(QWidget *w, Qt::Alignment alignment)

Establece la alineación del widget w en alignment y devuelve «true» si se encuentra w en este diseño (sin incluir los diseños secundarios); en caso contrario, devuelve false.

bool QLayout::setAlignment(QLayout *l, Qt::Alignment alignment)

Establece la alineación del diseño de l a alignment y devuelve true si se encuentra l en este diseño (sin incluir los diseños secundarios); en caso contrario, devuelve false.

Esta es una función sobrecargada.

void QLayout::setContentsMargins(const QMargins &margins)

Establece el valor de ` margins ` que se utilizará en el diseño.

Por defecto, « QLayout » utiliza los valores proporcionados por el estilo. En la mayoría de las plataformas, el margen es de 11 píxeles en todas las direcciones.

Nota: Funciónde asignación para la propiedad contentsMargins.

Véase también contentsMargins().

void QLayout::setContentsMargins(int left, int top, int right, int bottom)

Establece los márgenes left, top, right y bottom que se utilizarán alrededor del diseño.

Por defecto, QLayout utiliza los valores proporcionados por el estilo. En la mayoría de las plataformas, el margen es de 11 píxeles en todas las direcciones.

Nota: Funciónde asignación para la propiedad contentsMargins.

Véase también getContentsMargins(), QStyle::pixelMetric(), PM_LayoutLeftMargin, PM_LayoutTopMargin, PM_LayoutRightMargin y PM_LayoutBottomMargin.

void QLayout::setEnabled(bool enable)

Activa este diseño si « enable » es «true»; en caso contrario, lo desactiva.

Un diseño activado se adapta dinámicamente a los cambios; un diseño desactivado actúa como si no existiera.

Por defecto, todos los diseños están habilitados.

Véase también isEnabled().

[override virtual] void QLayout::setGeometry(const QRect &r)

Reimplementa: QLayoutItem::setGeometry(const QRect &r).

Véase también geometry().

void QLayout::setMenuBar(QWidget *widget)

Indica al gestor de geometría que coloque la barra de menús widget en la parte superior de parentWidget(), fuera de QWidget::contentsMargins(). Todos los widgets hijos se colocan por debajo del borde inferior de la barra de menús.

Véase también menuBar().

[since 6.10] void QLayout::setSizeConstraints(QLayout::SizeConstraint horizontal, QLayout::SizeConstraint vertical)

Establece las restricciones de tamaño tanto de « horizontal » como de « vertical ».

Esta función se introdujo en Qt 6.10.

Véase también sizeConstraint(), horizontalSizeConstraint() y verticalSizeConstraint().

[pure virtual] QLayoutItem *QLayout::takeAt(int index)

Debe implementarse en las subclases para eliminar del diseño el elemento de diseño situado en ` index ` y devolver dicho elemento. Si no existe dicho elemento, la función no debe realizar ninguna acción y debe devolver 0. Los elementos se numeran consecutivamente a partir de 0. Si se elimina un elemento, los demás elementos se renumerarán.

El siguiente fragmento de código muestra una forma segura de eliminar todos los elementos de un diseño:

QLayoutItem *child;
while ((child = layout->takeAt(0)) != nullptr) {
    ...
    delete child->widget(); // delete the widget
    delete child;   // delete the layout item
}

Véase también itemAt() y count().

[since 6.1] void QLayout::unsetContentsMargins()

Elimina cualquier margen definido por el usuario alrededor del diseño. El diseño utilizará los valores predeterminados proporcionados por el estilo.

Nota: Funciónde restablecimiento para la propiedad « contentsMargins ».

Esta función se introdujo en Qt 6.1.

Véase también ` setContentsMargins()`.

void QLayout::update()

Actualiza el diseño de parentWidget().

Por lo general, no debería ser necesario llamar a esta función, ya que se ejecuta automáticamente en los momentos más adecuados.

Véanse también activate() y invalidate().

© 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.