Uso de un archivo de interfaz de usuario de « Qt Widgets Designer » en tu aplicación C++
Qt Widgets Designer Los archivos de interfaz de usuario representan el árbol de widgets del formulario en formato XML. Los formularios se pueden procesar:
- En tiempo de compilación, lo que significa que los formularios se convierten en código C++ que se puede compilar.
- En tiempo de ejecución, lo que significa que los formularios son procesados por la clase QUiLoader, que construye dinámicamente el árbol de widgets mientras analiza el archivo XML.
Procesamiento de formularios en tiempo de compilación
Se crean componentes de interfaz de usuario con ` Qt Widgets Designer ` y se utilizan las herramientas de compilación integradas de Qt, `qmake` y `uic`, para generar código para ellos cuando se compila la aplicación. El código generado contiene el objeto de interfaz de usuario del formulario. Se trata de una estructura de C++ que contiene:
- Punteros a los widgets, diseños, elementos de diseño, grupos de botones y acciones del formulario.
- Una función miembro denominada
setupUi()para construir el árbol de widgets en el widget padre. - Una función miembro denominada «
retranslateUi()» que se encarga de la traducción de las propiedades de cadena del formulario. Para obtener más información, consulta «Reaccionar ante los cambios de idioma».
El código generado se puede incluir en su aplicación y utilizar directamente desde ella. Como alternativa, puede utilizarlo para ampliar subclases de widgets estándar.
Un formulario procesado en tiempo de compilación puede utilizarse en su aplicación mediante uno de los siguientes enfoques:
- El enfoque directo: se crea un widget que servirá de marcador de posición para el componente y se configura la interfaz de usuario en su interior.
- El enfoque de herencia única: se crea una subclase de la clase base del formulario (por ejemplo, `QWidget ` o ` QDialog`) e incluye una instancia privada del objeto de interfaz de usuario del formulario.
- El enfoque de herencia múltiple: se crea una subclase tanto de la clase base del formulario como del objeto de interfaz de usuario del formulario. Esto permite utilizar los widgets definidos en el formulario directamente desde el ámbito de la subclase.
A modo de demostración, crearemos una sencilla aplicación de «Formulario de calculadora». Se basa en el ejemplo original del «Formulario de calculadora ».
La aplicación consta de un archivo fuente, main.cpp, y un archivo de interfaz de usuario.
A continuación se muestra el archivo « calculatorform.ui », diseñado con « Qt Widgets Designer »:

Al utilizar CMake para compilar el ejecutable, se requiere un archivo CMakeLists.txt:
cmake_minimum_required(VERSION 3.16)
project(calculatorform LANGUAGES CXX)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
qt_add_executable(calculatorform
calculatorform.ui main.cpp)
set_target_properties(calculatorform PROPERTIES
WIN32_EXECUTABLE TRUE
MACOSX_BUNDLE TRUE
)
target_link_libraries(calculatorform PUBLIC
Qt::Core
Qt::Gui
Qt::Widgets
)El formulario aparece entre los archivos fuente de C++ en qt_add_executable(). La opción « CMAKE_AUTOUIC » indica a CMake que ejecute la herramienta uic para crear un archivo ui_calculatorform.h que puedan utilizar los archivos fuente.
Al utilizar qmake para compilar el ejecutable, se requiere un archivo .pro:
TEMPLATE = app
FORMS = calculatorform.ui
SOURCES = main.cppLa característica especial de este archivo es la declaración FORMS, que indica a qmake qué archivos debe procesar con uic. En este caso, el archivo calculatorform.ui se utiliza para crear un archivo ui_calculatorform.h que puede ser utilizado por cualquier archivo incluido en la declaración SOURCES.
Nota: Puedes utilizar Qt Creator para crear el proyecto «Calculator Form». Genera automáticamente el archivo main.cpp, la interfaz de usuario y un archivo de proyecto para la herramienta de compilación deseada, que puedes modificar.
El enfoque directo
Para utilizar el enfoque directo, incluimos el archivo ui_calculatorform.h directamente en main.cpp:
#include "ui_calculatorform.h"La función ` main ` crea el widget de la calculadora construyendo un ` QWidget ` estándar que utilizamos para alojar la interfaz de usuario descrita en el archivo ` calculatorform.ui `.
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWidget widget;
Ui::CalculatorForm ui;
ui.setupUi(&widget);
widget.show();
return app.exec();
}En este caso, Ui::CalculatorForm es un objeto de descripción de interfaz procedente del archivo ui_calculatorform.h que configura todos los widgets del cuadro de diálogo y las conexiones entre sus señales y ranuras.
El enfoque directo ofrece una forma rápida y sencilla de utilizar componentes sencillos e independientes en tus aplicaciones. Sin embargo, los componentes creados con Qt Widgets Designer suelen requerir una estrecha integración con el resto del código de la aplicación. Por ejemplo, el código de « CalculatorForm » proporcionado anteriormente se compilará y ejecutará, pero los objetos de « QSpinBox » no interactuarán con « QLabel », ya que necesitamos una ranura personalizada para llevar a cabo la operación de suma y mostrar el resultado en « QLabel ». Para lograrlo, debemos utilizar el enfoque de herencia única.
El enfoque de herencia única
Para utilizar el enfoque de herencia única, creamos una subclase de un widget estándar de Qt Widgets e incluimos una instancia privada del objeto de interfaz de usuario del formulario. Esto puede tener la siguiente forma:
- Una variable miembro
- Una variable miembro de tipo puntero
Uso de una variable miembro
En este enfoque, creamos una subclase de un widget de Qt Widgets y configuramos la interfaz de usuario desde el constructor. Los componentes utilizados de esta manera exponen los widgets y los diseños empleados en el formulario a la subclase del widget de Qt Widgets, y proporcionan un sistema estándar para establecer conexiones de señales y ranuras entre la interfaz de usuario y otros objetos de la aplicación. La estructura generada ` Ui::CalculatorForm ` es un miembro de la clase.
Este enfoque se utiliza en el ejemplo «Formulario de calculadora ».
Para asegurarnos de que podemos utilizar la interfaz de usuario, debemos incluir el archivo de cabecera que genera uic antes de hacer referencia a Ui::CalculatorForm:
#include "ui_calculatorform.h"El archivo del proyecto debe actualizarse para incluir calculatorform.h. En cuanto a CMake:
qt_add_executable(calculatorform
calculatorform.cpp calculatorform.h calculatorform.ui
main.cpp
)En casos concretos, como el ejemplo siguiente, en el que la directiva «include» utiliza una ruta relativa, se puede utilizar «qt_add_ui()» para generar el archivo « ui_calculatorform.h » en lugar de recurrir a AUTOUIC.
Cuándo es preferible utilizar `qt_add_ui` en lugar de AUTOUIC
#include "src/files/ui_calculatorform.h"qt_add_ui(calculatorform SOURCES calculatorform.ui
INCLUDE_PREFIX src/files)Para qmake:
HEADERS = calculatorform.hLa subclase se define de la siguiente manera:
class CalculatorForm : public QWidget
{
Q_OBJECT
public:
explicit CalculatorForm(QWidget *parent = nullptr);
private slots:
void updateResult();
private:
Ui::CalculatorForm ui;
};La característica más importante de la clase es el objeto privado ` ui `, que proporciona el código para configurar y gestionar la interfaz de usuario.
El constructor de la subclase crea y configura todos los widgets y diseños del cuadro de diálogo con solo llamar a la función « setupUi() » del objeto « ui ». Una vez hecho esto, es posible modificar la interfaz de usuario según sea necesario.
CalculatorForm::CalculatorForm(QWidget *parent)
: QWidget(parent)
{
ui.setupUi(this);
connect(ui.inputSpinBox1, &QSpinBox::valueChanged, this, &CalculatorForm::updateResult);
connect(ui.inputSpinBox2, &QSpinBox::valueChanged, this, &CalculatorForm::updateResult);
}Podemos conectar señales y ranuras en los widgets de la interfaz de usuario de la forma habitual añadiendo el prefijo «on_<nombre del objeto>». Para obtener más información, consulta widgets-and-dialogs-with-auto-connect.
Las ventajas de este enfoque son su sencillo uso de la herencia para proporcionar una interfaz basada en ` QWidget`, y la encapsulación de las variables de los widgets de la interfaz de usuario dentro del miembro de datos ` ui `. Podemos utilizar este método para definir varias interfaces de usuario dentro del mismo widget, cada una de las cuales se encuentra dentro de su propio espacio de nombres, y superponerlas (o componerlas). Este enfoque puede utilizarse, por ejemplo, para crear pestañas individuales a partir de formularios existentes.
Uso de una variable miembro de tipo puntero
Como alternativa, la estructura ` Ui::CalculatorForm ` puede convertirse en una variable miembro de tipo puntero de la clase. El encabezado quedaría entonces así:
namespace Ui {
class CalculatorForm;
}
class CalculatorForm : public QWidget
...
virtual ~CalculatorForm();
...
private:
Ui::CalculatorForm *ui;
...El archivo fuente correspondiente tiene el siguiente aspecto:
#include "ui_calculatorform.h"
CalculatorForm::CalculatorForm(QWidget *parent) :
QWidget(parent), ui(new Ui::CalculatorForm)
{
ui->setupUi(this);
}
CalculatorForm::~CalculatorForm()
{
delete ui;
}La ventaja de este enfoque es que el objeto de la interfaz de usuario se puede declarar por adelantado, lo que significa que no es necesario incluir el archivo « ui_calculatorform.h » generado en el encabezado. De este modo, el formulario se puede modificar sin necesidad de recompilar los archivos fuente dependientes. Esto resulta especialmente importante si la clase está sujeta a restricciones de compatibilidad binaria.
Por lo general, recomendamos este enfoque para bibliotecas y aplicaciones de gran tamaño. Para obtener más información, consulta Creación de bibliotecas compartidas.
El enfoque de herencia múltiple
Los formularios creados con « Qt Widgets Designer » pueden subclasificarse junto con una clase estándar basada en « QWidget ». Este enfoque hace que todos los componentes de la interfaz de usuario definidos en el formulario sean directamente accesibles dentro del ámbito de la subclase, y permite establecer conexiones de señales y ranuras de la forma habitual con la función « connect()».
Debemos incluir el archivo de cabecera que genera uic a partir del archivo calculatorform.ui, de la siguiente manera:
#include "ui_calculatorform.h"La clase se define de forma similar a la utilizada en el enfoque de herencia única, salvo que en esta ocasión heredamos tanto de ` QWidget ` como de ` Ui::CalculatorForm`, de la siguiente manera:
class CalculatorForm : public QWidget, private Ui::CalculatorForm
{
Q_OBJECT
public:
explicit CalculatorForm(QWidget *parent = nullptr);
private slots:
void on_inputSpinBox1_valueChanged(int value);
void on_inputSpinBox2_valueChanged(int value);
};Heredamos Ui::CalculatorForm de forma privada para garantizar que los objetos de la interfaz de usuario sean privados en nuestra subclase. También podemos heredarla con las palabras clave public o protected, del mismo modo que podríamos haber definido ui como pública o protegida en el caso anterior.
El constructor de la subclase realiza muchas de las mismas tareas que el constructor utilizado en el ejemplo de herencia única:
En este caso, se puede acceder a los widgets utilizados en la interfaz de usuario de la misma forma que a un widget creado manualmente en el código. Ya no necesitamos el prefijo « ui » para acceder a ellos.
Cómo reaccionar ante los cambios en el lenguaje
Qt notifica a las aplicaciones si cambia el idioma de la interfaz de usuario enviando un evento del tipo QEvent::LanguageChange. Para llamar a la función miembro retranslateUi() del objeto de interfaz de usuario, reimplementamos QWidget::changeEvent() en la clase Form, de la siguiente manera:
void CalculatorForm::changeEvent(QEvent *e)
{
QWidget::changeEvent(e);
switch (e->type()) {
case QEvent::LanguageChange:
ui->retranslateUi(this);
break;
default:
break;
}
}Procesamiento de formularios en tiempo de ejecución
Como alternativa, los formularios se pueden procesar en tiempo de ejecución, lo que permite generar interfaces de usuario dinámicas. Esto se puede hacer utilizando el módulo ` QtUiTools `, que proporciona la clase ` QUiLoader ` para gestionar los formularios creados con ` Qt Widgets Designer`.
El enfoque de UiTools
Para procesar formularios en tiempo de ejecución se requiere un archivo de recursos que contenga un archivo UI. Además, la aplicación debe configurarse para utilizar el módulo ` QtUiTools `. Esto se consigue incluyendo las siguientes declaraciones en un archivo de proyecto ` CMake `, asegurándose de que la aplicación se compile y se enlace correctamente.
find_package(Qt6 REQUIRED COMPONENTS Core Gui UiTools Widgets)
target_link_libraries(textfinder PUBLIC
Qt::Core
Qt::Gui
Qt::UiTools
Qt::Widgets
)Para qmake:
QT += uitoolsLa clase ` QUiLoader ` proporciona un objeto cargador de formularios para construir la interfaz de usuario. Esta interfaz de usuario se puede recuperar desde cualquier objeto ` QIODevice`, por ejemplo, un objeto ` QFile `, para obtener un formulario almacenado en el archivo de recursos de un proyecto. La función ` QUiLoader::load()` construye el widget del formulario utilizando la descripción de la interfaz de usuario contenida en el archivo.
Las clases del módulo QtUiTools se pueden incluir mediante la siguiente directiva:
#include <QtUiTools>La función QUiLoader::load() se invoca tal y como se muestra en este código del ejemplo «Text Finder »:
static QWidget*loadUiFile(QWidget*parent)
{
QFile file(u":/forms/textfinder.ui"_s);
if (!file.open(QIODevice::ReadOnly))
qFatal("Cannot open resource file");
return QUiLoader().load(&file, parent);
}En una clase que utiliza ` QtUiTools ` para crear su interfaz de usuario en tiempo de ejecución, podemos localizar objetos en el formulario mediante ` QObject::findChild()`. Por ejemplo, en el siguiente código, localizamos algunos componentes basándonos en sus nombres de objeto y tipos de widget:
ui_findButton = findChild<QPushButton*>("findButton");
ui_textEdit = findChild<QTextEdit*>("textEdit");
ui_lineEdit = findChild<QLineEdit*>("lineEdit");El procesamiento de formularios en tiempo de ejecución ofrece al desarrollador la libertad de modificar la interfaz de usuario de un programa con solo cambiar el archivo de interfaz de usuario. Esto resulta útil a la hora de personalizar programas para adaptarlos a las distintas necesidades de los usuarios, como iconos extragrandes o una combinación de colores diferente para facilitar la accesibilidad.
Conexiones automáticas
Las conexiones entre señales y ranuras definidas para los formularios en tiempo de compilación o en tiempo de ejecución pueden configurarse de forma manual o automática, utilizando la capacidad de QMetaObject para establecer conexiones entre señales y ranuras con nombres adecuados.
Por lo general, en un QDialog, si queremos procesar la información introducida por el usuario antes de aceptarla, debemos conectar la señal clicked() del botón «Aceptar» a una ranura personalizada de nuestro cuadro de diálogo. Primero mostraremos un ejemplo del cuadro de diálogo en el que la ranura se conecta manualmente y, a continuación, lo compararemos con un cuadro de diálogo que utiliza la conexión automática.
Un cuadro de diálogo sin conexión automática
Definimos el cuadro de diálogo de la misma forma que antes, pero ahora incluimos una ranura además del constructor:
class ImageDialog : public QDialog, private Ui::ImageDialog
{
Q_OBJECT
public:
explicit ImageDialog(QWidget *parent = nullptr);
private slots:
void checkValues();
};La ranura checkValues() se utilizará para validar los valores proporcionados por el usuario.
En el constructor del cuadro de diálogo configuramos los widgets como antes y conectamos la señal « clicked()» del botón «Cancelar» a la ranura «reject()» del cuadro de diálogo. También desactivamos la propiedad « autoDefault » en ambos botones para garantizar que el cuadro de diálogo no interfiera en la forma en que el campo de edición de línea gestiona los eventos de la tecla Intro:
ImageDialog::ImageDialog(QWidget *parent)
: QDialog(parent)
{
setupUi(this);
okButton->setAutoDefault(false);
cancelButton->setAutoDefault(false);
...
connect(okButton, &QAbstractButton::clicked, this, &ImageDialog::checkValues);
}Conectamos la señal « clicked()» del botón «Aceptar» a la ranura «checkValues()» del cuadro de diálogo, que implementamos de la siguiente manera:
void ImageDialog::checkValues()
{
if (nameLineEdit->text().isEmpty()) {
QMessageBox::information(this, tr("No Image Name"),
tr("Please supply a name for the image."), QMessageBox::Cancel);
} else {
accept();
}
}Esta ranura personalizada realiza lo mínimo necesario para garantizar que los datos introducidos por el usuario sean válidos: solo acepta la entrada si se ha asignado un nombre a la imagen.
Widgets y cuadros de diálogo con conexión automática
Aunque es fácil implementar un slot personalizado en el cuadro de diálogo y conectarlo en el constructor, podríamos utilizar en su lugar las funciones de conexión automática de QMetaObject para conectar la señal clicked() del botón «Aceptar» a un slot de nuestra subclase. uic genera automáticamente código en la función ` setupUi() ` del cuadro de diálogo para hacer esto, por lo que solo tenemos que declarar e implementar una ranura con un nombre que siga una convención estándar:
void on_<object name>_<signal name>(<signal parameters>);Nota: Al cambiar el nombre de los widgets del formulario, los nombres de las ranuras deben adaptarse en consecuencia, lo que puede suponer un problema de mantenimiento. Por este motivo, no recomendamos utilizar esta técnica en código nuevo.
Siguiendo esta convención, podemos definir e implementar una ranura que responda a los clics del ratón sobre el botón «Aceptar »:
class ImageDialog : public QDialog, private Ui::ImageDialog
{
Q_OBJECT
public:
explicit ImageDialog(QWidget *parent = nullptr);
private slots:
void on_okButton_clicked();
};Otro ejemplo de conexión automática entre señales y ranuras sería el Text Finder con su ranura « on_findButton_clicked() ».
Utilizamos el sistema de « QMetaObject » para habilitar las conexiones entre señales y ranuras:
QMetaObject::connectSlotsByName(this);Esto nos permite implementar el slot, tal y como se muestra a continuación:
void TextFinder::on_findButton_clicked()
{
QString searchString = ui_lineEdit->text();
QTextDocument *document = ui_textEdit->document();
bool found = false;
// undo previous change (if any)
document->undo();
if (searchString.isEmpty()) {
QMessageBox::information(this, tr("Empty Search Field"),
tr("The search field is empty. "
"Please enter a word and click Find."));
} else {
QTextCursor highlightCursor(document);
QTextCursor cursor(document);
cursor.beginEditBlock();
...
cursor.endEditBlock();
if (found == false) {
QMessageBox::information(this, tr("Word Not Found"),
tr("Sorry, the word cannot be found."));
}
}
}La conexión automática de señales y ranuras proporciona tanto una convención de nomenclatura estándar como una interfaz explícita con la que pueden trabajar los diseñadores de widgets. Al proporcionar código fuente que implementa una interfaz determinada, los diseñadores de interfaces de usuario pueden comprobar que sus diseños funcionan realmente sin tener que escribir código ellos mismos.
© 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.