Introducción a la programación con Qt Widgets
En este tema, enseñamos los conceptos básicos de Qt mediante la implementación de una sencilla aplicación de bloc de notas utilizando C++ y el Qt Widgets módulo. La aplicación es un pequeño editor de texto que permite crear un archivo de texto, guardarlo, imprimirlo o volver a abrirlo y editarlo. También se puede configurar la fuente que se va a utilizar.

Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en « Examples ». Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
Creación del proyecto «Notepad»
La configuración de un nuevo proyecto en Qt Creator cuenta con la ayuda de un asistente que le guía paso a paso a lo largo del proceso de creación del proyecto. El asistente le pedirá que introduzca los ajustes necesarios para ese tipo concreto de proyecto y creará el proyecto por usted.
Nota: El texto de la interfaz de usuario de Qt Creator y el contenido de los archivos generados dependen de la versión de Qt Creator que utilices.

Para crear el proyecto «Notepad», selecciona « File » > « New Project » > « Application (Qt) » > Qt Widgets Application > « Choose » y sigue las instrucciones del asistente. En el cuadro de diálogo « Class Information », escribe «Notepad» como nombre de la clase y selecciona « QMainWindow » como clase base.

El Qt Widgets Application asistente crea un proyecto que contiene un archivo fuente principal y un conjunto de archivos que definen una interfaz de usuario (el widget «Notepad»):
- CMakeLists.txt: el archivo del proyecto.
- main.cpp: el archivo fuente principal de la aplicación.
- notepad.cpp: el archivo fuente de la clase «notepad» del widget «Notepad».
- notepad.h: el archivo de cabecera de la clase «notepad» del widget «Notepad».
- notepad.ui: el formulario de interfaz de usuario del widget «Notepad».
Los archivos incluyen el código básico necesario para que puedas compilar y ejecutar el proyecto. Analizaremos con más detalle el contenido de los archivos en las siguientes secciones.
Más información
| Acerca de | Aquí |
|---|---|
| Uso Qt Creator | Qt Creator |
| Crear otro tipo de aplicaciones con Qt Creator | Qt Creator Tutoriales |
Archivo fuente principal
El asistente genera el siguiente código en el archivo main.cpp:
#include "notepad.h"
#include <QApplication>
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
Notepad w;
w.show();
return a.exec();
}Repasaremos el código línea por línea. Las siguientes líneas incluyen los archivos de cabecera para el widget Notepad y QApplication. Todas las clases de Qt tienen un archivo de cabecera que lleva su nombre.
#include "notepad.h"
#include <QApplication>La siguiente línea define la función main, que es el punto de entrada para todas las aplicaciones basadas en C y C++:
int main(int argc, char *argv[])La siguiente línea crea un objeto ` QApplication `. Este objeto gestiona los recursos de toda la aplicación y es necesario para ejecutar cualquier programa Qt que utilice ` Qt Widgets`. Construye un objeto de aplicación con los argumentos de la línea de comandos ` argc ` ejecutados en ` argv`. (Para aplicaciones GUI que no utilicen ` Qt Widgets`, puedes usar ` QGuiApplication ` en su lugar).
QApplication a(argc, argv);La siguiente línea crea el objeto Notepad. Este es el objeto para el que el asistente ha creado la clase y el archivo de interfaz de usuario. La interfaz de usuario contiene elementos visuales que en Qt se denominan « widgets ». Algunos ejemplos de widgets son los campos de texto, las barras de desplazamiento, las etiquetas y los botones de opción. Un widget también puede actuar como contenedor de otros widgets; por ejemplo, un cuadro de diálogo o la ventana principal de una aplicación.
Notepad w;La siguiente línea muestra el widget «Notepad» en la pantalla, en su propia ventana. Los widgets también pueden funcionar como contenedores. Un ejemplo de ello es « QMainWindow », que a menudo contiene varios tipos de widgets. Los widgets no son visibles de forma predeterminada; la función « show()» hace que el widget sea visible.
w.show();La siguiente línea hace que « QApplication » entre en su bucle de eventos. Cuando se ejecuta una aplicación Qt, se generan eventos y se envían a los widgets de la aplicación. Algunos ejemplos de eventos son las pulsaciones del ratón y las pulsaciones de teclas.
return a.exec();Más información
| Acerca de | Aquí |
|---|---|
| Widgets y geometría de ventanas | Widgets de ventana y de diálogo |
| Eventos y gestión de eventos | El sistema de eventos |
Diseño de una interfaz de usuario
El asistente genera una definición de interfaz de usuario en formato XML: notepad.ui. Al abrir el archivo notepad.ui en Qt Creator, este se abre automáticamente en el editor integrado Qt Widgets Designer.
User Interface Compiler Al compilar la aplicación, Qt Creator ejecuta el generador de interfaces de usuario de Qt (uic), que lee el archivo .ui y crea el archivo de cabecera de C++ correspondiente, ui_notepad.h.
Uso de Qt Widgets Designer
El asistente crea una aplicación que utiliza un QMainWindow. Tiene su propio diseño, al que puedes añadir una barra de menús, widgets acoplables, barras de herramientas y una barra de estado. El área central puede ocuparla cualquier tipo de widget. El asistente coloca allí el widget «Notepad».
Para añadir widgets en « Qt Widgets Designer »:
- En el modo « Edit » de « Qt Creator », haz doble clic en el archivo «notepad.ui» en la vista « Projects » para abrir el archivo en el editor integrado « Qt Widgets Designer ».
- Arrastra y suelta los widgets de Text Edit (QTextEdit) en el formulario.
- Pulsa Ctrl+A (o Cmd+A) para seleccionar los widgets y haz clic en « Lay out Vertically » (o pulsa Ctrl+L) para aplicar un diseño vertical (QVBoxLayout).
- Pulsa Ctrl+S (o Cmd+S) para guardar los cambios.
Ahora la interfaz de usuario tiene el siguiente aspecto en Qt Widgets Designer:

Puedes ver el archivo XML generado en el editor de código:
<?xml version="1.0" encoding="UTF-8"?>
<ui version="4.0">
<class>Notepad</class>
<widget class="QMainWindow" name="Notepad">
<property name="geometry">
<rect>
<x>0</x>
<y>0</y>
<width>800</width>
<height>400</height>
</rect>
</property>
<property name="windowTitle">
<string>Notepad</string>
</property>
<widget class="QWidget" name="centralWidget">
<layout class="QVBoxLayout" name="verticalLayout">
<item>
<widget class="QTextEdit" name="textEdit"/>
</item>
</layout>
</widget>
<widget class="QMenuBar" name="menuBar">
...La siguiente línea contiene la declaración XML, que especifica la versión XML y la codificación de caracteres utilizadas en el documento:
<?xml version="1.0" encoding="UTF-8"?>El resto del archivo especifica un elemento ` ui ` que define un widget de Bloc de notas:
<ui version="4.0">El archivo de interfaz de usuario se utiliza junto con el archivo de cabecera y el archivo fuente de la clase Notepad. Analizaremos el resto del archivo de interfaz de usuario en secciones posteriores.
Archivo de cabecera de Notepad
El asistente ha generado un archivo de cabecera para la clase Notepad que contiene los #includes necesarios, un constructor, un destructor y el objeto Ui. El archivo tiene el siguiente aspecto:
#include <QMainWindow>
QT_BEGIN_NAMESPACE
namespace Ui {
class Notepad;
}
QT_END_NAMESPACE
class Notepad : public QMainWindow
{
Q_OBJECT
public:
explicit Notepad(QWidget *parent = nullptr);
~Notepad();
private:
Ui::Notepad *ui;
QString currentFile;
};La siguiente línea incluye « QMainWindow », que proporciona una ventana principal de la aplicación:
#include <QMainWindow>Las siguientes líneas declaran la clase Notepad en el espacio de nombres Ui, que es el espacio de nombres estándar para las clases de interfaz de usuario generadas a partir de archivos .ui por la herramienta uic:
namespace Ui {
class Notepad;
}La declaración de la clase contiene la macro « Q_OBJECT ». Debe aparecer en primer lugar en la definición de la clase y declara nuestra clase como un « QObject ». Naturalmente, también debe heredar de « QObject ». Un « QObject » añade varias capacidades a una clase normal de C++. Cabe destacar que el nombre de la clase y los nombres de los slots se pueden consultar en tiempo de ejecución. También es posible consultar los tipos de los parámetros de un slot e invocarlo.
class Notepad : public QMainWindow
{
Q_OBJECTLas siguientes líneas declaran un constructor que tiene un argumento por defecto llamado parent. El valor 0 indica que el widget no tiene padre (es un widget de nivel superior).
public:
explicit Notepad(QWidget *parent = nullptr);La siguiente línea declara un destructor virtual para liberar los recursos que el objeto ha adquirido durante su ciclo de vida. Según la convención de nomenclatura de C++, los destructores tienen el mismo nombre que la clase a la que están asociados, precedido por una tilde (~). En ` QObject`, los destructores son virtuales para garantizar que los destructores de las clases derivadas se invoquen correctamente cuando se elimine un objeto a través de un puntero a la clase base.
~Notepad();Las siguientes líneas declaran una variable miembro que es un puntero a la clase de interfaz de usuario de Notepad. Una variable miembro está asociada a una clase específica y es accesible para todos sus métodos.
private:
Ui::Notepad *ui;
QString currentFile;
};Archivo fuente de Notepad
El archivo fuente que el asistente generó para la clase Notepad tiene el siguiente aspecto:
#include "notepad.h"
#include "ui_notepad.h"
Notepad::Notepad(QWidget *parent) :
QMainWindow(parent),
ui(new Ui::Notepad)
{
ui->setupUi(this);
}Las siguientes líneas incluyen el archivo de cabecera de la clase Notepad generado por el asistente y el archivo de cabecera de la interfaz de usuario generado por la herramienta uic:
#include "notepad.h"
#include "ui_notepad.h"La siguiente línea define el constructor de ` Notepad `:
Notepad::Notepad(QWidget *parent) :La siguiente línea invoca el constructor de ` QMainWindow `, que es la clase base de la clase `Notepad`:
QMainWindow(parent),La siguiente línea crea la instancia de la clase UI y la asigna al miembro ui:
ui(new Ui::Notepad)La siguiente línea configura la interfaz de usuario:
{
ui->setupUi(this);En el destructor, eliminamos ` ui`:
Notepad::~Notepad()
{
delete ui;
}Archivo del proyecto
El asistente genera el siguiente archivo de proyecto, ` CMakeLists.txt`, por nosotros:
# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
cmake_minimum_required(VERSION 3.16)
project(notepad LANGUAGES CXX)
find_package(Qt6
REQUIRED COMPONENTS Core Gui Widgets
OPTIONAL_COMPONENTS PrintSupport
)
qt_standard_project_setup()
qt_add_executable(notepad
main.cpp
notepad.cpp notepad.h notepad.ui
)
set_target_properties(notepad PROPERTIES
WIN32_EXECUTABLE TRUE
MACOSX_BUNDLE TRUE
)
target_link_libraries(notepad PRIVATE
Qt6::Core
Qt6::Gui
Qt6::Widgets
)
if(TARGET Qt6::PrintSupport)
target_link_libraries(notepad PRIVATE Qt6::PrintSupport)
endif()
# Resources:
set(notepad_resource_files
"images/bold.png"
"images/copy.png"
"images/create.png"
"images/cut.png"
"images/edit_redo.png"
"images/edit_undo.png"
"images/exit.png"
"images/font.png"
"images/info.png"
"images/italic.png"
"images/new.png"
"images/open.png"
"images/paste.png"
"images/pencil.png"
"images/print.png"
"images/save.png"
"images/save_as.png"
"images/underline.png"
)
qt_add_resources(notepad "notepad"
PREFIX
"/"
FILES
${notepad_resource_files}
)
install(TARGETS notepad
BUNDLE DESTINATION .
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)
qt_generate_deploy_app_script(
TARGET notepad
OUTPUT_SCRIPT deploy_script
NO_UNSUPPORTED_PLATFORM_ERROR
)
install(SCRIPT ${deploy_script})El archivo de proyecto especifica los archivos de código fuente, de cabecera y de interfaz de usuario incluidos en el proyecto.
Más información
| Acerca de | Aquí |
|---|---|
| Uso Qt Widgets Designer | Qt Widgets Designer Manual |
| Diseños | Gestión de diseños, widgets y diseños, ejemplos de diseños |
| Los widgets que incluye Qt | Galería de widgets de Qt Widgets |
| Ventanas principales y clases de ventana principal | Ventana principal de la aplicación, ejemplos de ventanas principales |
| QObjects y el modelo de objetos de Qt (esto es esencial para comprender Qt) | Modelo de objetos |
| qmake y el sistema de compilación de Qt | Manual de qmake |
Añadir interacción con el usuario
Para añadir funcionalidad al editor, empezamos añadiendo elementos de menú y botones en una barra de herramientas.
Haz clic en «Type Here» y añade las opciones «New», «Open», «Save», «Save as», «Print» y «Exit». Esto crea cinco líneas en el «Action Editor» que aparece a continuación. Para conectar las acciones a las ranuras (slots), haz clic con el botón derecho sobre una acción, selecciona « Go to slot » > « triggered() » y completa el código para esa ranura concreta.
Si además queremos añadir las acciones a una barra de herramientas, podemos asignar un icono a cada « QAction » y, a continuación, arrastrar el « QAction » a la barra de herramientas. Para asignar un icono, introduce un nombre de icono en la propiedad «Icono» de la acción en cuestión. Una vez que hayas arrastrado el « QAction » a la barra de herramientas, al hacer clic en el icono se ejecutará el «slot» asociado.
Completa el método newDocument():
void Notepad::newDocument()
{
currentFile.clear();
ui->textEdit->setText(QString());
}La variable ` currentFile ` es una variable global que contiene el archivo que se está editando en ese momento, y ` clear() ` borra el búfer de texto. La variable ` currentFile ` se define en la parte privada de `notepad.h`:
private:
Ui::Notepad *ui;
QString currentFile;Abrir un archivo
En notepad.ui, haz clic con el botón derecho del ratón en « actionOpen » y selecciona « Go to Slot ».
Completa el método ` open()`.
void Notepad::open()
{
QString fileName = QFileDialog::getOpenFileName(this, "Open the file");
if (fileName.isEmpty())
return;
QFile file(fileName);
currentFile = fileName;
if (!file.open(QIODevice::ReadOnly | QFile::Text)) {
QMessageBox::warning(this, "Warning", "Cannot open file: " + file.errorString());
return;
}
setWindowTitle(fileName);
QTextStream in(&file);
QString text = in.readAll();
ui->textEdit->setText(text);
file.close();
}QFileDialog::getOpenFileName Se abre un cuadro de diálogo que permite seleccionar un archivo. El objeto « QFile » myfile tiene como parámetro el archivo seleccionado file_name. Almacenamos el archivo seleccionado también en la variable global currentFile para utilizarlo más adelante. Abrimos el archivo con file.open como archivo de texto de solo lectura. Si no se puede abrir, se emite una advertencia y el programa se detiene.
Definimos un QTextStream instream para el parámetro myfile. El contenido del archivo myfile se copia en QString text . setText(text) llena el búfer de nuestro editor con text.
Guardar un archivo
Creamos el método para guardar un archivo de la misma forma que para abrirlo: haciendo clic con el botón derecho del ratón en actionSave y seleccionando « Go to Slot ».
void Notepad::save()
{
QString fileName;
// If we don't have a filename from before, get one.
if (currentFile.isEmpty()) {
fileName = QFileDialog::getSaveFileName(this, "Save");
if (fileName.isEmpty())
return;
currentFile = fileName;
} else {
fileName = currentFile;
}
QFile file(fileName);
if (!file.open(QIODevice::WriteOnly | QFile::Text)) {
QMessageBox::warning(this, "Warning", "Cannot save file: " + file.errorString());
return;
}
setWindowTitle(fileName);
QTextStream out(&file);
QString text = ui->textEdit->toPlainText();
out << text;
file.close();
}QFile El objeto ` myfile ` está vinculado a la variable global ` current_file`, la variable que contiene el archivo con el que estábamos trabajando. Si no podemos abrir ` myfile`, se muestra un mensaje de error y el método se detiene. Creamos un ` QTextStream ` ` outstream`. El contenido del búfer del editor se convierte a texto sin formato y, a continuación, se escribe en ` outstream`.
Guardar un archivo con otro nombre
void Notepad::saveAs()
{
QString fileName = QFileDialog::getSaveFileName(this, "Save as");
if (fileName.isEmpty())
return;
QFile file(fileName);
if (!file.open(QFile::WriteOnly | QFile::Text)) {
QMessageBox::warning(this, "Warning", "Cannot save file: " + file.errorString());
return;
}
currentFile = fileName;
setWindowTitle(fileName);
QTextStream out(&file);
QString text = ui->textEdit->toPlainText();
out << text;
file.close();
}Este procedimiento es el mismo que el de «Guardar un archivo», con la única diferencia de que aquí hay que introducir un nuevo nombre para el archivo que se va a crear.
Imprimir un archivo
Si quieres utilizar las funciones de impresión, debes añadir « PrintSupport » al archivo del proyecto:
find_package(Qt6
REQUIRED COMPONENTS Core Gui Widgets
OPTIONAL_COMPONENTS PrintSupport
)En ` notepad.cpp`, declaramos un objeto `QPrinter` llamado ` printDev`:
void Notepad::print()
{
#if defined(QT_PRINTSUPPORT_LIB) && QT_CONFIG(printer)
QPrinter printDev;
#if QT_CONFIG(printdialog)
QPrintDialog dialog(&printDev, this);
if (dialog.exec() == QDialog::Rejected)
return;
#endif // QT_CONFIG(printdialog)
ui->textEdit->print(&printDev);
#endif // QT_CONFIG(printer)
}Abrimos un cuadro de diálogo de impresora y almacenamos la impresora seleccionada en el objeto ` printDev`. Si hemos hecho clic en ` Cancel ` y no hemos seleccionado ninguna impresora, el método devuelve el valor inicial. El comando de impresión propiamente dicho se ejecuta mediante ` ui->textEdit->print `, pasando nuestro objeto `QPrinter` como parámetro.
Seleccionar una fuente
void Notepad::selectFont()
{
bool fontSelected;
QFont font = QFontDialog::getFont(&fontSelected, this);
if (fontSelected)
ui->textEdit->setFont(font);
}Declaramos un valor booleano que indica si hemos seleccionado una fuente mediante ` QFontDialog`. Si es así, establecemos la fuente con ` ui->textEdit->setFont(myfont)`.
Copiar, cortar, pegar, deshacer y rehacer
Si seleccionas un texto y quieres copiarlo al portapapeles, debes llamar al método correspondiente de ui->textEdit. Lo mismo ocurre con cortar, pegar, deshacer y rehacer.
Esta tabla muestra el nombre del método que hay que utilizar.
| Tarea | Método que se invoca |
|---|---|
| Copiar | ui->textEdit->copy() |
| Cortar | ui->textEdit->cut() |
| Pegar | ui->textEdit->pegar() |
| Deshacer | ui->textEdit->deshacer() |
| Rehacer | ui->textEdit->redo() |
Más información
| Acerca de | Aquí |
|---|---|
| Archivos y dispositivos de E/S | QFile, QIODevice |
| tr() y la internacionalización | Qt Linguist Manual, cómo escribir código fuente para su traducción, internacionalización con Qt |
Compilación y ejecución desde la línea de comandos
Para compilar una aplicación de ejemplo desde la línea de comandos, crea un directorio de compilación para ella. Accede al directorio de compilación y ejecuta « qt-cmake » para configurar el proyecto para la compilación. Si el proyecto se configura correctamente, los archivos generados te permitirán compilarlo.
md <build_directory>
cd <build_directory>
<qt_installation_directory>\bin\qt-cmake -GNinja <source_directory>
<generator>Los comandos crean un ejecutable en el directorio de compilación. La herramienta CMake lee el archivo de proyecto y genera instrucciones sobre cómo compilar la aplicación. A continuación, el generador utiliza esas instrucciones para generar el binario ejecutable.
Por ejemplo, para compilar el ejemplo del Bloc de notas en Windows, si utilizas Ninja como generador, introduce los siguientes comandos:
md notepad-build
cd notepad-build
C:\Qt\6.12.0\msvc2022_64\bin\qt-cmake -GNinja C:\Examples\notepad
ninjaSi no utilizas Ninja como generador, utiliza el comando CMake independiente del generador para compilar la aplicación en lugar de ` ninja`:
cmake --build© 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.