En esta página

QBoxLayout Class

La clase QBoxLayout alinea los widgets secundarios de forma horizontal o vertical. Más información...

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

QHBoxLayout y QVBoxLayout

Tipos públicos

enum Direction { LeftToRight, RightToLeft, TopToBottom, BottomToTop }

Funciones públicas

QBoxLayout(QBoxLayout::Direction dir, QWidget *parent = nullptr)
virtual ~QBoxLayout()
void addLayout(QLayout *layout, int stretch = 0)
void addSpacerItem(QSpacerItem *spacerItem)
void addSpacing(int size)
void addStretch(int stretch = 0)
void addStrut(int size)
void addWidget(QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())
QBoxLayout::Direction direction() const
void insertItem(int index, QLayoutItem *item)
void insertLayout(int index, QLayout *layout, int stretch = 0)
void insertSpacerItem(int index, QSpacerItem *spacerItem)
void insertSpacing(int index, int size)
void insertStretch(int index, int stretch = 0)
void insertWidget(int index, QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())
void setDirection(QBoxLayout::Direction direction)
void setStretch(int index, int stretch)
bool setStretchFactor(QWidget *widget, int stretch)
bool setStretchFactor(QLayout *layout, int stretch)
int stretch(int index) const

Funciones públicas reimplementadas

virtual void addItem(QLayoutItem *item) override
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 &r) override
virtual void setSpacing(int spacing) override
virtual QSize sizeHint() const override
virtual int spacing() const override
virtual QLayoutItem *takeAt(int index) override

Descripción detallada

QBoxLayout toma el espacio que recibe (de su diseño padre o de la función parentWidget()), lo divide en una fila de cuadros y hace que cada widget gestionado ocupe un cuadro.

Cinco botones dispuestos en horizontal

Si la orientación de QBoxLayout es « Qt::Horizontal », las cajas se colocan en una fila, con tamaños adecuados. Cada widget (u otra caja) ocupará como mínimo su tamaño mínimo y como máximo su tamaño máximo. Cualquier espacio sobrante se reparte según los factores de estiramiento (más información al respecto a continuación).

Cinco botones dispuestos en vertical

Si la orientación del QBoxLayout es Qt::Vertical, las casillas se colocan en una columna, de nuevo con los tamaños adecuados.

La forma más sencilla de crear un QBoxLayout es utilizar una de las clases de conveniencia, por ejemplo, QHBoxLayout (para cuadros « Qt::Horizontal ») o QVBoxLayout (para cuadros « Qt::Vertical »). También puedes utilizar directamente el constructor de QBoxLayout, especificando su dirección como LeftToRight, RightToLeft, TopToBottom o BottomToTop.

Si el QBoxLayout no es el diseño de nivel superior (es decir, no gestiona toda el área del widget ni sus elementos secundarios), debes añadirlo a su diseño padre antes de poder realizar ninguna operación con él. La forma habitual de añadir un diseño es llamando a parentLayout->addLayout().

Una vez hecho esto, puedes añadir cuadros al QBoxLayout utilizando una de estas cuatro funciones:

  • addWidget() para añadir un widget al QBoxLayout y establecer el factor de expansión del widget. (El factor de expansión se aplica a lo largo de la fila de cuadros.)
  • addSpacing() para crear un cuadro vacío; esta es una de las funciones que se utilizan para crear cuadros de diálogo atractivos y espaciosos. Más adelante se explican las formas de establecer los márgenes.
  • addStretch() para crear un cuadro vacío y extensible.
  • addLayout() para añadir a la fila un cuadro que contenga otro ` QLayout ` y establecer el factor de expansión de ese diseño.

Utilice « insertWidget » (), « insertSpacing » (), « insertStretch » () o « insertLayout » () para insertar una caja en una posición especificada del diseño.

QBoxLayout también incluye dos anchos de margen:

  • setContentsMargins() establece el ancho del borde exterior a cada lado del widget. Se trata del ancho del espacio reservado a lo largo de cada uno de los cuatro lados del QBoxLayout.
  • setSpacing() establece el ancho entre cuadros adyacentes. (Se puede utilizar addSpacing() para obtener más espacio en un punto concreto).

El valor predeterminado del margen viene dado por el estilo. El margen predeterminado que especifican la mayoría de los estilos de Qt es 9 para los widgets hijos y 11 para las ventanas. El espaciado predeterminado es igual al ancho del margen para un diseño de nivel superior, o igual al del diseño padre.

Para eliminar un widget de un diseño, llama a ` removeWidget()`. Llamar a ` QWidget::hide()` en un widget también elimina efectivamente dicho widget del diseño hasta que se llame a ` QWidget::show()`.

Casi siempre será preferible utilizar ` QVBoxLayout ` y ` QHBoxLayout ` en lugar de `QBoxLayout`, debido a la comodidad que ofrecen sus constructores.

Véase también QGridLayout, QStackedLayout y Gestión de diseños.

Documentación sobre los tipos de miembros

enum QBoxLayout::Direction

Este tipo se utiliza para determinar la orientación de una disposición de cuadros.

ConstanteValorDescripción
QBoxLayout::LeftToRight0Horizontal, de izquierda a derecha.
QBoxLayout::RightToLeft1Horizontal, de derecha a izquierda.
QBoxLayout::TopToBottom2Vertical, de arriba abajo.
QBoxLayout::BottomToTop3Vertical, de abajo hacia arriba.

Documentación de funciones de miembro

[explicit] QBoxLayout::QBoxLayout(QBoxLayout::Direction dir, QWidget *parent = nullptr)

Crea un nuevo QBoxLayout con la dirección dir y el widget padre parent.

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().

Véanse también direction() y QWidget::setLayout().

[virtual noexcept] QBoxLayout::~QBoxLayout()

Elimina este diseño de cuadro.

Los widgets del diseño no se eliminan.

[override virtual] void QBoxLayout::addItem(QLayoutItem *item)

Reimplementa: QLayout::addItem(QLayoutItem *item).

void QBoxLayout::addLayout(QLayout *layout, int stretch = 0)

Añade « layout » al final del cuadro, con un factor de estiramiento en serie de « stretch ».

layout Se convierte en un elemento secundario del diseño del recuadro.

Véase también insertLayout(), addItem() y addWidget().

void QBoxLayout::addSpacerItem(QSpacerItem *spacerItem)

Añade « spacerItem » al final de este diseño de cuadro.

La propiedad de spacerItem se transfiere a este diseño.

Véase también addSpacing() y addStretch().

void QBoxLayout::addSpacing(int size)

Añade un espacio no extensible (un ` QSpacerItem`) con un tamaño de ` size ` al final de este diseño de cuadro. ` QBoxLayout ` proporciona el margen y el espaciado predeterminados. Esta función añade espacio adicional.

Véase también insertSpacing(), addItem() y QSpacerItem.

void QBoxLayout::addStretch(int stretch = 0)

Añade un espacio elástico (un QSpacerItem) con un tamaño mínimo nulo y un factor de elasticidad stretch al final de este diseño de cuadro.

Véase también insertStretch(), addItem() y QSpacerItem.

void QBoxLayout::addStrut(int size)

Limita la dimensión perpendicular de la caja (por ejemplo, la altura si la caja es de tipo « LeftToRight ») a un mínimo de « size ». Otras restricciones pueden aumentar este límite.

Véase también addItem().

void QBoxLayout::addWidget(QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())

Añade widget al final de este diseño de cuadro, con un factor de extensión de stretch y una alineación de alignment.

El factor de expansión se aplica únicamente en el « direction » del « QBoxLayout » y es relativo con respecto a los demás recuadros y widgets de este « QBoxLayout ». Los widgets y recuadros con factores de expansión más altos se expanden más.

Si el factor de expansión es 0 y ningún otro elemento de la QBoxLayout tiene un factor de expansión superior a cero, el espacio se distribuye según el QWidget::sizePolicy() de cada widget implicado.

La alineación se especifica mediante alignment. La alineación predeterminada es 0, lo que significa que el widget ocupa toda la celda.

widget se convierte en un elemento hijo de QLayout::parentWidget().

Véanse también insertWidget(), addItem(), addLayout(), addStretch(), addSpacing() y addStrut().

[override virtual] int QBoxLayout::count() const

Reimplementa: QLayout::count() const.

QBoxLayout::Direction QBoxLayout::direction() const

Devuelve la dirección del rectángulo. Las funciones ` addWidget()` y ` addSpacing()` actúan en esta dirección; el estiramiento se produce en esta dirección.

Véase también setDirection(), QBoxLayout::Direction, addWidget() y addSpacing().

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

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

[override virtual] bool QBoxLayout::hasHeightForWidth() const

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

[override virtual] int QBoxLayout::heightForWidth(int w) const

Reimplementa: ` QLayoutItem::heightForWidth(int) const`.

void QBoxLayout::insertItem(int index, QLayoutItem *item)

Inserta item en este diseño de cuadro en la posición index. El índice debe ser negativo o estar comprendido entre 0 y count(), ambos inclusive. Si index es negativo o count(), el elemento se añade al final.

La propiedad de item se transfiere a este diseño.

Véase también addItem(), insertWidget(), insertLayout(), insertStretch() y insertSpacing().

void QBoxLayout::insertLayout(int index, QLayout *layout, int stretch = 0)

Inserta « layout » en la posición « index », con un factor de estiramiento « stretch ». Si « index » es negativo, el diseño se añade al final.

layout se convierte en un elemento secundario del diseño de la caja.

Véase también addLayout() y insertItem().

void QBoxLayout::insertSpacerItem(int index, QSpacerItem *spacerItem)

Inserta « spacerItem » en la posición « index », con un tamaño mínimo y un factor de estiramiento iguales a cero. Si « index » es negativo, el espacio se añade al final.

La propiedad de spacerItem se transfiere a este diseño.

Véase también addSpacerItem(), insertStretch() y insertSpacing().

void QBoxLayout::insertSpacing(int index, int size)

Inserta un espacio no extensible (un ` QSpacerItem`) en la posición ` index`, con un tamaño de ` size`. Si ` index ` es negativo, el espacio se añade al final.

El diseño del cuadro tiene márgenes y espaciado predeterminados. Esta función añade espacio adicional.

Véase también addSpacing(), insertItem() y QSpacerItem.

void QBoxLayout::insertStretch(int index, int stretch = 0)

Inserta un espacio extensible (un ` QSpacerItem`) en la posición ` index`, con un tamaño mínimo igual a cero y un factor de extensión ` stretch`. Si ` index ` es negativo, el espacio se añade al final.

Véanse también addStretch(), insertItem() y QSpacerItem.

void QBoxLayout::insertWidget(int index, QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())

Inserta widget en la posición index, con el factor de estiramiento stretch y la alineación alignment. Si index es negativo, el widget se añade al final.

El factor de expansión se aplica únicamente en el direction del QBoxLayout y es relativo a los demás recuadros y widgets de este QBoxLayout. Los widgets y recuadros con factores de expansión más altos se expanden más.

Si el factor de expansión es 0 y ningún otro elemento del QBoxLayout tiene un factor de expansión mayor que cero, el espacio se distribuye según el QWidget::sizePolicy() de cada widget implicado.

La alineación se especifica mediante alignment. La alineación por defecto es 0, lo que significa que el widget ocupa toda la celda.

widget se convierte en un elemento secundario del QLayout::parentWidget().

Véanse también addWidget() y insertItem().

[override virtual] void QBoxLayout::invalidate()

Reimplementa: QLayout::invalidate().

Restablece la información almacenada en la caché.

[override virtual] QLayoutItem *QBoxLayout::itemAt(int index) const

Reimplementa: ` QLayout::itemAt(int index) const`.

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

Reimplementa: ` QLayout::maximumSize()` const.

[override virtual] int QBoxLayout::minimumHeightForWidth(int w) const

Reimplementa: ` QLayoutItem::minimumHeightForWidth(int w) const`.

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

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

void QBoxLayout::setDirection(QBoxLayout::Direction direction)

Establece la orientación de este diseño en « direction ».

Véase también direction().

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

Reimplementa: ` QLayout::setGeometry` (const QRect &r).

[override virtual] void QBoxLayout::setSpacing(int spacing)

Reimplementa una función de acceso para la propiedad: QLayout::spacing.

Reimplementa QLayout::setSpacing(). Establece la propiedad de espaciado en spacing.

Véase también QLayout::setSpacing() y spacing().

void QBoxLayout::setStretch(int index, int stretch)

Establece el factor de estiramiento en la posición index en stretch.

Véase también stretch().

bool QBoxLayout::setStretchFactor(QWidget *widget, int stretch)

Establece el factor de estiramiento de « widget » en « stretch » y devuelve «true» si se encuentra « widget » en este diseño (sin incluir los diseños secundarios); en caso contrario, devuelve « false ».

Véase también setAlignment().

bool QBoxLayout::setStretchFactor(QLayout *layout, int stretch)

Establece el factor de estiramiento del diseño layout en stretch y devuelve true si se encuentra layout en este diseño (sin incluir los diseños secundarios); en caso contrario, devuelve false.

Esta es una función sobrecargada.

[override virtual] QSize QBoxLayout::sizeHint() const

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

[override virtual] int QBoxLayout::spacing() const

Reimplementa una función de acceso para la propiedad: QLayout::spacing.

Reimplementa QLayout::spacing(). Si la propiedad «spacing» es válida, se devuelve ese valor. De lo contrario, se calcula y se devuelve un valor para la propiedad de espaciado. Dado que el espaciado del diseño en un widget depende del estilo, si el elemento padre es un widget, consulta el estilo para obtener el espaciado (horizontal o vertical) del diseño. De lo contrario, el elemento padre es un diseño, y consulta al diseño padre la propiedad spacing().

Véase también QLayout::spacing() y setSpacing().

int QBoxLayout::stretch(int index) const

Devuelve el factor de estiramiento en la posición index.

Véase también setStretch().

[override virtual] QLayoutItem *QBoxLayout::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.