Gestión del diseño
El sistema de disposición de Qt ofrece una forma sencilla y eficaz de organizar automáticamente los widgets hijos dentro de un widget para garantizar que aprovechen bien el espacio disponible.
Introducción
Qt incluye un conjunto de clases de gestión de diseño que se utilizan para describir cómo se distribuyen los widgets en la interfaz de usuario de una aplicación. Estos diseños colocan y redimensionan automáticamente los widgets cuando cambia el espacio disponible para ellos, garantizando que se dispongan de forma coherente y que la interfaz de usuario en su conjunto siga siendo usable.
Todas las subclases de ` QWidget ` pueden utilizar diseños para gestionar sus elementos hijos. La función ` QWidget::setLayout()` aplica un diseño a un widget. Cuando se establece un diseño en un widget de esta forma, este se encarga de las siguientes tareas:
- Posicionamiento de los widgets hijos
- Tamaños predeterminados adecuados para las ventanas
- Tamaños mínimos adecuados para las ventanas
- Gestión del redimensionamiento
- Actualizaciones automáticas cuando cambia el contenido:
- Tamaño de la fuente, texto u otros contenidos de los widgets secundarios
- Ocultar o mostrar un widget secundario
- Eliminación de widgets secundarios
Clases de diseño de Qt
Las clases de diseño de Qt se diseñaron para código C++ escrito a mano, lo que permite especificar las medidas en píxeles para mayor simplicidad, por lo que son fáciles de entender y utilizar. El código generado para los formularios creados con Qt Widgets Designer también utiliza las clases de diseño. Resulta útil utilizar Qt Widgets Designer al experimentar con el diseño de un formulario, ya que evita el ciclo de compilación, enlace y ejecución que suele implicar el desarrollo de interfaces de usuario.
Alinea los widgets hijos horizontal o verticalmente | |
Contenedor para organizar grupos de widgets de botón | |
Gestiona formularios de widgets de entrada y sus etiquetas asociadas | |
Representa un anclaje entre dos elementos en un QGraphicsAnchorLayout | |
Diseño en el que se pueden anclar widgets entre sí en la vista gráfica | |
Distribuye los widgets en una cuadrícula | |
Marco de cuadro de grupo con título | |
Alinea los widgets horizontalmente | |
La clase base de los gestores de geometría | |
Elemento abstracto que manipula un QLayout | |
Atributo de diseño que describe la política de redimensionamiento horizontal y vertical | |
Espacio en blanco en un diseño | |
Pila de widgets en la que solo es visible un widget a la vez | |
Pila de widgets en la que solo es visible un widget a la vez | |
Alinea los widgets verticalmente | |
Elemento de diseño que representa un widget |
Diseños horizontal, vertical, en cuadrícula y de formulario
La forma más sencilla de dar a tus widgets una buena disposición es utilizar los gestores de disposición integrados: QHBoxLayout, QVBoxLayout, QGridLayout y QFormLayout. Estas clases heredan de QLayout, que a su vez deriva de QObject (no de QWidget). Se encargan de la gestión de la geometría de un conjunto de widgets. Para crear disposiciones más complejas, puedes anidar los gestores de disposición unos dentro de otros.
- Un « QHBoxLayout » distribuye los widgets en una fila horizontal, de izquierda a derecha (o de derecha a izquierda en el caso de los idiomas que se escriben de derecha a izquierda).

- Un « QVBoxLayout » distribuye los widgets en una columna vertical, de arriba abajo.

- Un « QGridLayout » distribuye los widgets en una cuadrícula bidimensional. Los widgets pueden ocupar varias celdas.

- Un « QFormLayout » distribuye los widgets en un estilo de dos columnas con etiqueta descriptiva y campo.

Distribución de widgets en el código
El siguiente código crea un « QHBoxLayout » que gestiona la geometría de cinco « QPushButtons », tal y como se muestra en la primera captura de pantalla anterior:
QWidget *window = new QWidget;
QPushButton *button1 = new QPushButton("One");
QPushButton *button2 = new QPushButton("Two");
QPushButton *button3 = new QPushButton("Three");
QPushButton *button4 = new QPushButton("Four");
QPushButton *button5 = new QPushButton("Five");
QHBoxLayout *layout = new QHBoxLayout(window);
layout->addWidget(button1);
layout->addWidget(button2);
layout->addWidget(button3);
layout->addWidget(button4);
layout->addWidget(button5);
window->show();El código de QVBoxLayout es idéntico, salvo la línea en la que se crea la disposición. El código de QGridLayout es ligeramente diferente, ya que debemos especificar la posición en la fila y la columna del widget secundario:
QWidget *window = new QWidget;
QPushButton *button1 = new QPushButton("One");
QPushButton *button2 = new QPushButton("Two");
QPushButton *button3 = new QPushButton("Three");
QPushButton *button4 = new QPushButton("Four");
QPushButton *button5 = new QPushButton("Five");
QGridLayout *layout = new QGridLayout(window);
layout->addWidget(button1, 0, 0);
layout->addWidget(button2, 0, 1);
layout->addWidget(button3, 1, 0, 1, 2);
layout->addWidget(button4, 2, 0);
layout->addWidget(button5, 2, 1);
window->show();El tercer QPushButton ocupa 2 columnas. Esto es posible especificando 2 como quinto argumento de QGridLayout::addWidget().
QFormLayout Añadirá dos widgets en una fila, normalmente un QLabel y un QLineEdit para crear formularios. Si se añaden un QLabel y un QLineEdit en la misma fila, se establecerá el QLineEdit como compañero del QLabel. El siguiente código utilizará el QFormLayout para colocar tres QPushButtons y un QLineEdit correspondiente en una fila.
QWidget *window = new QWidget;
QPushButton *button1 = new QPushButton("One");
QLineEdit *lineEdit1 = new QLineEdit();
QPushButton *button2 = new QPushButton("Two");
QLineEdit *lineEdit2 = new QLineEdit();
QPushButton *button3 = new QPushButton("Three");
QLineEdit *lineEdit3 = new QLineEdit();
QFormLayout *layout = new QFormLayout(window);
layout->addRow(button1, lineEdit1);
layout->addRow(button2, lineEdit2);
layout->addRow(button3, lineEdit3);
window->show();Consejos para utilizar diseños
Cuando se utiliza un diseño, no es necesario pasar un padre al crear los widgets hijos. El diseño reasignará automáticamente los widgets (utilizando QWidget::setParent()) para que sean hijos del widget en el que está instalado el diseño.
Nota: Los widgets de un diseño son hijos del widget en el que está instalado el diseño, no del propio diseño. Los widgets solo pueden tener como padre a otros widgets, no a diseños.
Puedes anidar diseños utilizando addLayout() en un diseño; el diseño interior pasa entonces a ser un hijo del diseño en el que se inserta.
Añadir widgets a un diseño
Cuando se añaden widgets a un diseño, el proceso de diseño funciona de la siguiente manera:
- Inicialmente, a todos los widgets se les asignará una cantidad de espacio de acuerdo con sus propiedades ` QWidget::sizePolicy()` y ` QWidget::sizeHint()`.
- Si alguno de los widgets tiene definidos factores de estiramiento con un valor superior a cero, se le asignará espacio en proporción a su factor de estiramiento (como se explica a continuación).
- Si alguno de los widgets tiene factores de estiramiento establecidos en cero, solo obtendrá más espacio si ningún otro widget lo reclama. De entre estos, se asigna espacio en primer lugar a los widgets con una política de tamaño « Expanding ».
- A cualquier widget al que se le haya asignado menos espacio que su tamaño mínimo (o su indicación de tamaño mínimo si no se ha especificado ningún tamaño mínimo) se le asignará dicho tamaño mínimo que necesita. (Los widgets no tienen por qué tener un tamaño mínimo ni una indicación de tamaño mínimo; en tal caso, el factor de expansión es el factor determinante).
- A cualquier widget al que se le asigne más espacio que su tamaño máximo se le asignará el espacio correspondiente a dicho tamaño máximo que necesite. (Los widgets no tienen por qué tener un tamaño máximo; en ese caso, el factor de estiramiento es el factor determinante).
Factores de estiramiento
Normalmente, los widgets se crean sin ningún factor de estiramiento establecido. Cuando se distribuyen en un diseño, se les asigna una parte del espacio de acuerdo con su tamaño QWidget::sizePolicy() o su sugerencia de tamaño mínimo, el que sea mayor. Los factores de estiramiento se utilizan para modificar la cantidad de espacio que se asigna a los widgets en proporción entre sí.
Si tenemos tres widgets dispuestos mediante un « QHBoxLayout » sin factores de estiramiento definidos, obtendremos una disposición como esta:

Si aplicamos factores de estiramiento a cada widget, se distribuirán de forma proporcional (pero nunca por debajo de su indicación de tamaño mínimo), p. ej.:

Widgets personalizados en diseños
Al crear tu propia clase de widget, también debes especificar sus propiedades de diseño. Si el widget utiliza uno de los diseños de Qt, esto ya está resuelto. Si el widget no tiene ningún widget hijo o utiliza un diseño manual, puedes modificar su comportamiento utilizando cualquiera o todos los mecanismos siguientes:
- Reimplementa ` QWidget::sizeHint()` para devolver el tamaño preferido del widget.
- Reimplementa ` QWidget::minimumSizeHint()` para devolver el tamaño mínimo que puede tener el widget.
- Llamar a ` QWidget::setSizePolicy()` para especificar los requisitos de espacio del widget.
Llama a ` QWidget::updateGeometry()` cada vez que cambie la sugerencia de tamaño, la sugerencia de tamaño mínimo o la política de tamaño. Esto provocará un nuevo cálculo del diseño. Varias llamadas consecutivas a ` QWidget::updateGeometry()` solo provocarán un único recálculo del diseño.
Si la altura preferida de tu widget depende de su anchura real (por ejemplo, una etiqueta con división automática de palabras), establece el indicador « height-for-width » en la propiedad « size policy » del widget y reimplementa la función « QWidget::heightForWidth()».
Aunque implemente ` QWidget::heightForWidth()`, sigue siendo recomendable proporcionar un `sizeHint()` razonable.
Para obtener más orientación a la hora de implementar estas funciones, consulta el artículo de Qt Quarterly «Trading Height for Width».
Problemas de diseño
El uso de texto enriquecido en un widget de etiqueta puede plantear algunos problemas en el diseño de su widget padre. Estos problemas se deben a la forma en que los gestores de diseño de Qt gestionan el texto enriquecido cuando la etiqueta realiza un ajuste de línea.
En determinados casos, el diseño padre pasa al modo QLayout::FreeResize, lo que significa que no adaptará el diseño de su contenido para que quepa en ventanas de tamaño reducido, ni siquiera impedirá que el usuario reduzca la ventana hasta un tamaño que la haga inutilizable. Esto se puede solucionar creando subclases de los widgets problemáticos e implementando las funciones adecuadas sizeHint() y minimumSizeHint().
En algunos casos, es importante tener en cuenta cuándo se añade un diseño a un widget. Al establecer el widget de un ` QDockWidget ` o un ` QScrollArea ` (mediante ` QDockWidget::setWidget()` y ` QScrollArea::setWidget()`), el diseño ya debe estar establecido en el widget. De lo contrario, el widget no será visible.
Diseño manual
Si estás creando un diseño especial y único, también puedes crear un widget personalizado tal y como se ha descrito anteriormente. Reimplementa QWidget::resizeEvent() para calcular la distribución de tamaños necesaria y llama a setGeometry() en cada elemento secundario.
El widget recibirá un evento de tipo QEvent::LayoutRequest cuando sea necesario recalcular el diseño. Reimplementa QWidget::event() para gestionar los eventos QEvent::LayoutRequest.
Cómo escribir un gestor de diseño personalizado
Una alternativa al diseño manual es escribir tu propio gestor de diseño creando una subclase de ` QLayout`. El ejemplo «Flow Layout» muestra cómo hacerlo.
A continuación presentamos un ejemplo detallado. La clase ` CardLayout ` se inspira en el gestor de diseño de Java del mismo nombre. Coloca los elementos (widgets o diseños anidados) unos encima de otros, desplazando cada elemento mediante ` QLayout::spacing()`.
Para escribir tu propia clase de diseño, debes definir lo siguiente:
- Una estructura de datos para almacenar los elementos gestionados por el diseño. Cada elemento es un ` QLayoutItem`. En este ejemplo utilizaremos un ` QList `.
- addItem(), cómo añadir elementos al diseño.
- setGeometry(), cómo realizar el diseño.
- sizeHint(), el tamaño preferido del diseño.
- itemAt(), cómo recorrer el diseño.
- takeAt(), cómo eliminar elementos del diseño.
En la mayoría de los casos, también deberás implementar el método ` minimumSize()`.
El archivo de cabecera (card.h)
#ifndef CARD_H
#define CARD_H
#include <QtWidgets>
#include <QList>
class CardLayout : public QLayout
{
public:
CardLayout(int spacing): QLayout()
{ setSpacing(spacing); }
CardLayout(int spacing, QWidget *parent): QLayout(parent)
{ setSpacing(spacing); }
~CardLayout();
void addItem(QLayoutItem *item) override;
QSize sizeHint() const override;
QSize minimumSize() const override;
int count() const override;
QLayoutItem *itemAt(int) const override;
QLayoutItem *takeAt(int) override;
void setGeometry(const QRect &rect) override;
private:
QList<QLayoutItem *> m_items;
};
#endifEl archivo de implementación (card.cpp)
//#include "card.h"En primer lugar, definimos count() para obtener el número de elementos de la lista.
int CardLayout::count() const
{
// QList::size() returns the number of QLayoutItems in m_items
return m_items.size();
}A continuación, definimos dos funciones que recorren el diseño: ` itemAt() ` y ` takeAt()`. El sistema de diseño utiliza estas funciones internamente para gestionar la eliminación de widgets. También están disponibles para los programadores de aplicaciones.
itemAt() devuelve el elemento del índice indicado. takeAt() elimina el elemento del índice indicado y lo devuelve. En este caso utilizamos el índice de la lista como índice de diseño. En otros casos en los que tengamos una estructura de datos más compleja, es posible que tengamos que dedicar más esfuerzo a definir un orden lineal para los elementos.
QLayoutItem *CardLayout::itemAt(int idx) const
{
// QList::value() performs index checking, and returns nullptr if we are
// outside the valid range
return m_items.value(idx);
}
QLayoutItem *CardLayout::takeAt(int idx)
{
// QList::take does not do index checking
return idx >= 0 && idx < m_items.size() ? m_items.takeAt(idx) : 0;
}addItem() Implementa la estrategia de colocación predeterminada para los elementos del diseño. Esta función debe implementarse. La utilizan QLayout::add() y el constructor de QLayout, que toma un diseño como padre. Si tu diseño tiene opciones de colocación avanzadas que requieren parámetros, debes proporcionar funciones de acceso adicionales, como las sobrecargas de QGridLayout::addItem(), QGridLayout::addWidget() y QGridLayout::addLayout() que abarcan filas y columnas.
void CardLayout::addItem(QLayoutItem *item)
{
m_items.append(item);
}El diseño asume la responsabilidad de los elementos añadidos. Dado que QLayoutItem no hereda de QObject, debemos eliminar los elementos manualmente. En el destructor, retiramos cada elemento de la lista utilizando takeAt() y, a continuación, lo eliminamos.
CardLayout::~CardLayout()
{
QLayoutItem *item;
while ((item = takeAt(0)))
delete item;
}La función setGeometry() es la que realmente lleva a cabo la disposición. El rectángulo proporcionado como argumento no incluye margin(). Si procede, utiliza spacing() como distancia entre elementos.
void CardLayout::setGeometry(const QRect &r)
{
QLayout::setGeometry(r);
if (m_items.size() == 0)
return;
int w = r.width() - (m_items.count() - 1) * spacing();
int h = r.height() - (m_items.count() - 1) * spacing();
int i = 0;
while (i < m_items.size()) {
QLayoutItem *o = m_items.at(i);
QRect geom(r.x() + i * spacing(), r.y() + i * spacing(), w, h);
o->setGeometry(geom);
++i;
}
}sizeHint() y minimumSize() suelen ser muy similares en su implementación. Los tamaños devueltos por ambas funciones deben incluir spacing(), pero no margin().
QSize CardLayout::sizeHint() const
{
QSize s(0, 0);
int n = m_items.count();
if (n > 0)
s = QSize(100, 70); //start with a nice default size
int i = 0;
while (i < n) {
QLayoutItem *o = m_items.at(i);
s = s.expandedTo(o->sizeHint());
++i;
}
return s + n * QSize(spacing(), spacing());
}
QSize CardLayout::minimumSize() const
{
QSize s(0, 0);
int n = m_items.count();
int i = 0;
while (i < n) {
QLayoutItem *o = m_items.at(i);
s = s.expandedTo(o->minimumSize());
++i;
}
return s + n * QSize(spacing(), spacing());
}Notas adicionales
- Este diseño personalizado no gestiona la altura en relación con el ancho.
- Ignoramos ` QLayoutItem::isEmpty()`; esto significa que el diseño tratará los widgets ocultos como visibles.
- En el caso de diseños complejos, la velocidad puede aumentarse considerablemente almacenando en caché los valores calculados. En ese caso, implementa QLayoutItem::invalidate() para marcar los datos almacenados en caché como modificados.
- Llamar a ` QLayoutItem::sizeHint()`, etc., puede resultar costoso. Por lo tanto, debes almacenar el valor en una variable local si lo vas a necesitar de nuevo más adelante dentro de la misma función.
- No debes llamar a ` QLayoutItem::setGeometry()` dos veces sobre el mismo elemento dentro de la misma función. Esta llamada puede resultar muy costosa si el elemento tiene varios widgets hijos, ya que el gestor de diseño debe realizar un diseño completo cada vez. En su lugar, calcula la geometría y, a continuación, establécela. (Esto no solo se aplica a los diseños; deberías hacer lo mismo si implementas tu propio `resizeEvent()`, por ejemplo).
Ejemplos de diseño
Muchos ejemplos de Qt Widgets ya utilizan diseños; sin embargo, existen varios ejemplos que muestran distintos diseños.
El ejemplo muestra cómo utilizar señales y ranuras para implementar la funcionalidad de un widget de calculadora, y cómo utilizar QGridLayout para colocar widgets hijos en una cuadrícula. | |
El ejemplo del widget de calendario muestra el uso de QCalendarWidget. | |
Muestra cómo organizar los widgets para diferentes tamaños de ventana. | |
Muestra cómo funcionan los modos de composición en QPainter. | |
El ejemplo «Menús» muestra cómo se pueden utilizar los menús en una aplicación con ventana principal. | |
El ejemplo «Modelo de árbol simple» muestra cómo utilizar un modelo jerárquico con las clases de vista estándar de Qt. |
© 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.