En esta página

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.

Aplicación «Bloc de notas»

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

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.

Cuadro de diálogo «Nuevo proyecto» de Qt Creator

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.

Cuadro de diálogo «Información de la clase»

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 deAquí
Uso Qt CreatorQt Creator
Crear otro tipo de aplicaciones con Qt CreatorQt 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 deAquí
Widgets y geometría de ventanasWidgets de ventana y de diálogo
Eventos y gestión de eventosEl 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 »:

  1. 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 ».
  2. Arrastra y suelta los widgets de Text Edit (QTextEdit) en el formulario.
  3. 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).
  4. Pulsa Ctrl+S (o Cmd+S) para guardar los cambios.

Ahora la interfaz de usuario tiene el siguiente aspecto en Qt Widgets Designer:

Modo de edición de widgets para crear el diseño

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_OBJECT

Las 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 deAquí
Uso Qt Widgets DesignerQt Widgets Designer Manual
DiseñosGestión de diseños, widgets y diseños, ejemplos de diseños
Los widgets que incluye QtGalería de widgets de Qt Widgets
Ventanas principales y clases de ventana principalVentana 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 QtManual 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.

TareaMétodo que se invoca
Copiarui->textEdit->copy()
Cortarui->textEdit->cut()
Pegarui->textEdit->pegar()
Deshacerui->textEdit->deshacer()
Rehacerui->textEdit->redo()

Más información

Acerca deAquí
Archivos y dispositivos de E/SQFile, QIODevice
tr() y la internacionalizaciónQt 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
ninja

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