En esta página

Visor de documentos

Una aplicación de Widgets para visualizar e imprimir archivos JSON, de texto y PDF.

Interfaz de usuario del visor de documentos que muestra una ventana emergente con la opción «Seleccionar modo de apertura»

El visor de documentos muestra cómo utilizar un « QMainWindow » con barras de herramientas, menús y acciones tanto estáticas como dinámicas. Además, ilustra las siguientes características de las aplicaciones basadas en widgets:

  • Uso de la « QSettings » para consultar y guardar las preferencias del usuario, así como para gestionar el historial de archivos abiertos anteriormente.
  • Control del comportamiento del cursor al pasar por encima de los widgets.
  • Creación de complementos que se cargan dinámicamente.
  • Localización de la interfaz de usuario a diferentes idiomas.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Creación de una aplicación y de la ventana principal

La aplicación y su ventana principal se crean en main.cpp. La función main() utiliza QCommandLineParser para procesar los argumentos de la línea de comandos:ayuda, versión y un argumento posicional opcional, archivo. Si el usuario ha proporcionado una ruta a un archivo al iniciar la aplicación, la ventana principal lo abre:

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QCoreApplication::setOrganizationName("QtProject"_L1);
    QCoreApplication::setApplicationName("DocumentViewer"_L1);
    QCoreApplication::setApplicationVersion("1.0"_L1);

    Translator mainTranslator;
    mainTranslator.setBaseName("docviewer"_L1);
    mainTranslator.install();

    QCommandLineParser parser;
    parser.setApplicationDescription(Tr::tr("A viewer for JSON, PDF and text files"));
    parser.addHelpOption();
    parser.addVersionOption();
    parser.addPositionalArgument("File"_L1, Tr::tr("JSON, PDF or text file to open"));
    parser.process(app);

    const QStringList &positionalArguments = parser.positionalArguments();
    const QString &fileName = (positionalArguments.count() > 0) ? positionalArguments.at(0)
                                                                : QString();

    MainWindow w(mainTranslator);

    // Start application only if plugins are available
    if (!w.hasPlugins()) {
        QMessageBox::critical(nullptr,
                              Tr::tr("No viewer plugins found"),
                              Tr::tr("Unable to load viewer plugins. Exiting application."));
        return 1;
    }

    w.show();
    if (!fileName.isEmpty())
        w.openFile(fileName);

    return app.exec();
}

Clase MainWindow

La clase ` MainWindow ` proporciona una pantalla de aplicación con menús, acciones y una barra de herramientas. Puede abrir un archivo, detectando automáticamente su tipo de contenido. También mantiene una lista de archivos abiertos anteriormente, utilizando ` QSettings ` para almacenar y recargar la configuración al iniciarse. La clase `MainWindow` crea un visor adecuado para el archivo abierto, en función de su tipo de contenido, y ofrece soporte para la impresión de documentos.

El constructor de MainWindow inicializa la interfaz de usuario creada en Qt Designer. El archivo mainwindow.ui proporciona un QTabWidget a la izquierda, en el que se muestran marcadores y miniaturas. A la derecha, hay un QScrollArea para visualizar el contenido del archivo.

Clase ViewerFactory

La clase ViewerFactory gestiona los visores para los tipos de archivo conocidos. Estos visores se implementan como complementos. Cuando se crea una instancia de ViewerFactory, se pasan al constructor los punteros al área de visualización y a la ventana principal:

m_factory.reset(new ViewerFactory(ui->viewArea, this));

ViewerFactory carga todos los complementos disponibles durante su creación. Proporciona una API pública para consultar los complementos cargados, sus nombres y los tipos MIME compatibles:

    using ViewerList = QList<AbstractViewer *>;
    QStringList viewerNames(bool showDefault = false) const;
    ViewerList viewers() const;
    AbstractViewer *findViewer(const QString &viewerName) const;
    AbstractViewer *defaultViewer() const;
    QStringList supportedMimeTypes() const;

La función ` viewer() ` devuelve un puntero al complemento adecuado para abrir el ` QFile ` pasado como argumento:

m_viewer = m_factory->viewer(file);

Si la configuración de la aplicación contiene una sección para el visor, esta se pasa a la función virtual ` restoreState() ` del visor:

void MainWindow::restoreViewerSettings()
{
    if (!m_viewer)
        return;

    QSettings settings;
    settings.beginGroup(settingsViewers);
    QByteArray viewerSettings = settings.value(m_viewer->viewerName(), QByteArray()).toByteArray();
    settings.endGroup();
    if (!viewerSettings.isEmpty())
        m_viewer->restoreState(viewerSettings);
}

A continuación, los recursos estándar de la interfaz de usuario se pasan al visor y el área de desplazamiento principal se configura para mostrar el widget de visualización del visor:

    m_viewer->initViewer(ui->actionBack, ui->actionForward, ui->menuHelp->menuAction(), ui->tabWidget);
    restoreViewerSettings();
    ui->scrollArea->setWidget(m_viewer->widget());
    return true;
}

Clase AbstractViewer

AbstractViewer proporciona una API generalizada para visualizar, guardar e imprimir un documento. Se pueden consultar las propiedades tanto del documento como del visor:

  • ¿Tiene contenido el documento?
  • ¿Se ha modificado?
  • ¿Admite una vista general (miniaturas o marcadores)?

AbstractViewer proporciona métodos protegidos para que las clases derivadas puedan crear acciones y menús en la ventana principal. Para mostrar estos elementos en la ventana principal, se vinculan a ella. AbstractViewer se encarga de eliminar y destruir los elementos de la interfaz de usuario que crea. Hereda de ` QObject ` para implementar señales y ranuras.

Señales

void uiInitialized();

Esta señal se emite después de que un visor reciba toda la información necesaria sobre los elementos de la interfaz de usuario en la ventana principal.

void printingEnabledChanged(bool enabled);

Esta señal se emite cuando se activa o se desactiva la impresión del documento. Esto ocurre después de que se haya cargado correctamente un nuevo documento o, por ejemplo, de que se haya eliminado todo el contenido.

void showMessage(const QString &message, int timeout = 8000);

Esta señal se emite para mostrar un mensaje de estado al usuario.

void documentLoaded(const QString &fileName);

Esta señal notifica a la aplicación que un documento se ha cargado correctamente.

La clase TxtViewer

TxtViewer es un sencillo visor de texto que hereda de `AbstractViewer`. Permite editar archivos de texto, copiar, cortar y pegar, imprimir y guardar los cambios.

Definición de la clase
class TxtViewer : public ViewerInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.DocumentViewer.ViewerInterface" FILE "txtviewer.json")
    Q_INTERFACES(ViewerInterface)

La definición de la clase comienza con la macro « Q_OBJECT », que gestiona las señales y las ranuras. A continuación, aparecen las macros « Q_PLUGIN_METADATA » y « Q_INTERFACES », necesarias para registrar el complemento.

La clase hereda de ` ViewerInterface`, que a su vez hereda de ` AbstractViewer`. La clase ` ViewerInterface ` se utiliza para proporcionar una interfaz entre la aplicación de la ventana principal y el complemento.

QPluginLoader También requiere el archivo txtviewer.json, que debe contener la clave del complemento:

{ "Keys": [ "txtviewer" ] }

La clase no define ningún constructor, lo que significa que solo está disponible un constructor estándar sin argumentos. Todas las demás funciones, incluido el destructor, reimplementan funciones virtuales de ` ViewerInterface`. Se utilizan para intercambiar datos, información e instrucciones con la aplicación principal.

public:
    TxtViewer();
    ~TxtViewer() override;
    void init(QFile *file, QWidget *parent, QMainWindow *mainWindow) override;
    QString viewerName() const override { return QLatin1StringView(staticMetaObject.className()); };
    QStringList supportedMimeTypes() const override;
    bool saveDocument() override { return saveFile(m_file.get()); };
    bool saveDocumentAs() override;
    bool hasContent() const override;
    QByteArray saveState() const override { return {}; }
    bool restoreState(QByteArray &) override { return true; }
    bool supportsOverview() const override { return false; }

#ifdef DOCUMENTVIEWER_PRINTSUPPORT
protected:
    void printDocument(QPrinter *printer) const override;
#endif // DOCUMENTVIEWER_PRINTSUPPORT

private slots:
    void setupTxtUi();

private:
    void retranslate() override;
    void openFile();
    bool saveFile (QFile *file);

    QPlainTextEdit *m_textEdit;
    QAction *m_cutAct = nullptr;
    QAction *m_copyAct = nullptr;
    QAction *m_pasteAct = nullptr;
};
Implementación de la clase TxtViewer
#include "txtviewer.h"

#include <QFileDialog>
#include <QMainWindow>
#include <QMenu>
#include <QMenuBar>
#include <QPlainTextEdit>
#include <QScrollBar>
#include <QToolBar>

#include <QGuiApplication>
#include <QPainter>
#include <QTextDocument>

#include <QDir>

#ifdef DOCUMENTVIEWER_PRINTSUPPORT
#include <QPrinter>
#include <QPrintDialog>
#endif

using namespace Qt::StringLiterals;

TxtViewer::TxtViewer()
    : m_cutAct(new QAction(this)),
      m_copyAct(new QAction(this)),
      m_pasteAct(new QAction(this))
{
    connect(this, &AbstractViewer::uiInitialized, this, &TxtViewer::setupTxtUi);

    const QIcon cutIcon = QIcon::fromTheme(QIcon::ThemeIcon::EditCut,
                                           QIcon(":/demos/documentviewer/images/cut.png"_L1));
    m_cutAct->setIcon(cutIcon);
    m_cutAct->setShortcuts(QKeySequence::Cut);

    const QIcon copyIcon = QIcon::fromTheme(QIcon::ThemeIcon::EditCopy,
                                            QIcon(":/demos/documentviewer/images/copy.png"_L1));
    m_copyAct->setIcon(copyIcon);
    m_copyAct->setShortcuts(QKeySequence::Copy);

    const QIcon pasteIcon = QIcon::fromTheme(QIcon::ThemeIcon::EditPaste,
                                             QIcon(":/demos/documentviewer/images/paste.png"_L1));
    m_pasteAct->setIcon(pasteIcon);
    m_pasteAct->setShortcuts(QKeySequence::Paste);
}

TxtViewer::~TxtViewer() = default;

void TxtViewer::init(QFile *file, QWidget *parent, QMainWindow *mainWindow)
{
    AbstractViewer::init(file, new QPlainTextEdit(parent), mainWindow);
    m_textEdit = qobject_cast<QPlainTextEdit *>(widget());
    setTranslationBaseName("txtviewer"_L1);
}

QStringList TxtViewer::supportedMimeTypes() const
{
    return {"text/plain"_L1};
}

void TxtViewer::setupTxtUi()
{
    QMenu *editMenu = addMenu();
    QToolBar *editToolBar = addToolBar();
#if QT_CONFIG(clipboard)
    connect(m_cutAct, &QAction::triggered, m_textEdit, &QPlainTextEdit::cut);
    editMenu->addAction(m_cutAct);
    editToolBar->addAction(m_cutAct);

    connect(m_copyAct, &QAction::triggered, m_textEdit, &QPlainTextEdit::copy);
    editMenu->addAction(m_copyAct);
    editToolBar->addAction(m_copyAct);

    connect(m_pasteAct, &QAction::triggered, m_textEdit, &QPlainTextEdit::paste);
    editMenu->addAction(m_pasteAct);
    editToolBar->addAction(m_pasteAct);

    menuBar()->addSeparator();

    m_cutAct->setEnabled(false);
    m_copyAct->setEnabled(false);
    connect(m_textEdit, &QPlainTextEdit::copyAvailable, m_cutAct, &QAction::setEnabled);
    connect(m_textEdit, &QPlainTextEdit::copyAvailable, m_copyAct, &QAction::setEnabled);
#endif // QT_CONFIG(clipboard)

    openFile();

    connect(m_textEdit, &QPlainTextEdit::textChanged, this, [&](){
        maybeSetPrintingEnabled(hasContent());
    });

    connect(m_uiAssets.back, &QAction::triggered, m_textEdit, [&](){
        auto *bar = m_textEdit->verticalScrollBar();
        if (bar->value() > bar->minimum())
            bar->setValue(bar->value() - 1);
    });

    connect(m_uiAssets.forward, &QAction::triggered, m_textEdit, [&](){
        auto *bar = m_textEdit->verticalScrollBar();
        if (bar->value() < bar->maximum())
            bar->setValue(bar->value() + 1);
    });

    retranslate();
}

Empezamos incluyendo los archivos de cabecera necesarios para acceder a todas las clases que utiliza TxtViewer. También incluimos txtviewer.h.

QPrinter y QPrintDialog solo se incluyen si la compatibilidad con la impresión está habilitada en el sistema de compilación.

Ten en cuenta que estos encabezados no se incluyen directamente en mainwindow.h. Incluir encabezados de gran tamaño en otros archivos de encabezado puede afectar al rendimiento de la compilación. En este caso, no causaría problemas, pero es una buena práctica incluir solo los encabezados necesarios para mantener las dependencias al mínimo.

La implementación comienza con un destructor vacío. Podría omitirse por completo. Es una buena práctica implementarlo vacío para indicar a quienes lean el código que no es necesario realizar ninguna acción en el destructor.

Al destructor le sigue una función de inicialización que toma tres argumentos:

  • file, el puntero al archivo que se va a abrir y mostrar.
  • parent, que apunta al objeto ` QWidget ` en el que se colocará el editor.
  • mainWindow, que apunta a la ventana principal de la aplicación, donde se gestionan los menús y las barras de menú.

La función llama a la función de inicialización base de ` AbstractViewer`. Se crea un nuevo widget ` QPlainTextEdit `, que mostrará el contenido del archivo. A continuación, la función de configuración de ` TxtViewer` se conecta a la señal ` uiInitialized ` de la clase base.

La siguiente función devuelve la lista de tipos MIME que admite el visor de texto. Solo se admite texto sin formato.

La última función de inicialización añade componentes de la interfaz de usuario específicos del visor, como menús, iconos, botones y descripciones emergentes. Utiliza la funcionalidad proporcionada por AbstractViewer para asegurarse de que estos componentes se eliminen de la ventana principal de la aplicación, una vez que se muestre otro archivo con otro complemento de visor.

void TxtViewer::openFile()
{
    const QString type = tr("open");
    if (!m_file->open(QFile::ReadOnly | QFile::Text)) {
        statusMessage(tr("Cannot read file %1:\n%2.")
                      .arg(QDir::toNativeSeparators(m_file->fileName()),
                           m_file->errorString()), type);
        return;
    }

    QTextStream in(m_file.get());
#if QT_CONFIG(cursor)
    QGuiApplication::setOverrideCursor(Qt::WaitCursor);
#endif
    if (!m_textEdit->toPlainText().isEmpty()) {
        m_textEdit->clear();
        disablePrinting();
    }
    m_textEdit->setPlainText(in.readAll());
#if QT_CONFIG(cursor)
    QGuiApplication::restoreOverrideCursor();
#endif

    statusMessage(tr("File %1 loaded.")
                  .arg(QDir::toNativeSeparators(m_file->fileName())), type);
    maybeEnablePrinting();
}

openFile Abre un archivo, transfiere su contenido a QPlainTextEdit y muestra un mensaje de estado al usuario, dependiendo de si la apertura se ha realizado con éxito o no.

bool TxtViewer::hasContent() const
{
    return (!m_textEdit->toPlainText().isEmpty());
}

#ifdef DOCUMENTVIEWER_PRINTSUPPORT
void TxtViewer::printDocument(QPrinter *printer) const
{
    if (!hasContent())
        return;

    m_textEdit->print(printer);
}
#endif // DOCUMENTVIEWER_PRINTSUPPORT

bool TxtViewer::saveFile(QFile *file)
{
    QString errorMessage;

    QGuiApplication::setOverrideCursor(Qt::WaitCursor);
    if (file->open(QFile::WriteOnly | QFile::Text)) {
        QTextStream out(file);
        out << m_textEdit->toPlainText();
    } else {
        errorMessage = tr("Cannot open file %1 for writing:\n%2.")
                       .arg(QDir::toNativeSeparators(file->fileName())),
                            file->errorString();
    }
    QGuiApplication::restoreOverrideCursor();

    if (!errorMessage.isEmpty()) {
        statusMessage(errorMessage);
        return false;
    }

    statusMessage(tr("File %1 saved")
                  .arg(QDir::toNativeSeparators(file->fileName())));
    return true;
}

bool TxtViewer::saveDocumentAs()
{
    QFileDialog dialog(mainWindow());
    dialog.setWindowModality(Qt::WindowModal);
    dialog.setAcceptMode(QFileDialog::AcceptSave);
    if (dialog.exec() != QDialog::Accepted)
        return false;

    const QStringList &files = dialog.selectedFiles();
    if (files.isEmpty())
        return false;

    //newFile();
    m_file->setFileName(files.first());
    return saveDocument();
}

void TxtViewer::retranslate()
{
    if (toolBars().isEmpty())
        return;
    menus().at(0)->setTitle(tr("&Edit"));
    toolBars().at(0)->setWindowTitle(tr("Edit"));

    m_cutAct->setText(tr("Cu&t"));
    m_cutAct->setStatusTip(tr("Cut the current selection's contents to the clipboard"));
    m_copyAct->setText(tr("&Copy"));
    m_copyAct->setStatusTip(tr("Copy the current selection's contents to the clipboard"));
    m_pasteAct->setText(tr("&Paste"));
    m_pasteAct->setStatusTip(tr("Paste the clipboard's contents into the current selection"));
}

La siguiente función reimplementada indica a la aplicación principal si el complemento de visualización está mostrando contenido o no.

Si el sistema de compilación admite la impresión, la siguiente sección la implementa.

Las dos últimas reimplementaciones proporcionan la funcionalidad para guardar el archivo actual o guardarlo con un nuevo nombre.

Clase ImageViewer

ImageViewer muestra imágenes según lo admite QImageReader, utilizando un QLabel.

En el constructor, aumentamos el límite de asignación de ` QImageReader ` para permitir fotos de mayor tamaño:

ImageViewer::ImageViewer()
    : m_zoomInAct(new QAction(this)),
      m_zoomOutAct(new QAction(this)),
      m_resetZoomAct(new QAction(this)),
      m_formats(imageFormats())
{
    connect(this, &AbstractViewer::uiInitialized, this, &ImageViewer::setupImageUi);
    QImageReader::setAllocationLimit(1024); // MB

    m_zoomInAct->setIcon(QIcon::fromTheme(QIcon::ThemeIcon::ZoomIn));
    m_zoomInAct->setShortcut(QKeySequence::ZoomIn);
    connect(m_zoomInAct, &QAction::triggered, this, &ImageViewer::zoomIn);

    m_zoomOutAct->setIcon(QIcon::fromTheme(QIcon::ThemeIcon::ZoomOut));
    m_zoomOutAct->setShortcut(QKeySequence::ZoomOut);
    connect(m_zoomOutAct, &QAction::triggered, this, &ImageViewer::zoomOut);

    m_resetZoomAct->setIcon(QIcon::fromTheme(QIcon::ThemeIcon::ZoomFitBest));
    m_resetZoomAct->setShortcut(QKeySequence(Qt::ControlModifier | Qt::Key_0));
    connect(m_resetZoomAct, &QAction::triggered, this, &ImageViewer::resetZoom);
}

En la función openFile(), cargamos la imagen y determinamos su tamaño. Si es más grande que la pantalla, la reducimos al tamaño de la pantalla, manteniendo la relación de aspecto. Este cálculo debe realizarse en píxeles nativos, y es necesario establecer la relación de píxeles del dispositivo en el mapa de píxeles resultante para que se vea nítida:

void ImageViewer::openFile()
{
#if QT_CONFIG(cursor)
    QGuiApplication::setOverrideCursor(Qt::WaitCursor);
#endif
    const QString name = m_file->fileName();
    QImageReader reader(name);
    const QImage origImage = reader.read();
    if (origImage.isNull()) {
        statusMessage(tr("Cannot read file %1:\n%2.")
                      .arg(QDir::toNativeSeparators(name),
                           reader.errorString()), tr("open"));
        disablePrinting();
#if QT_CONFIG(cursor)
        QGuiApplication::restoreOverrideCursor();
#endif
        return;
    }

    clear();

    QImage image = origImage.colorSpace().isValid()
        ? origImage.convertedToColorSpace(QColorSpace::SRgb)
        : origImage;

    const auto devicePixelRatio = m_imageLabel->devicePixelRatioF();
    m_imageSize = QSizeF(image.size()) / devicePixelRatio;

    QPixmap pixmap = QPixmap::fromImage(image);
    pixmap.setDevicePixelRatio(devicePixelRatio);
    m_imageLabel->setPixmap(pixmap);

    const QSizeF targetSize = m_imageLabel->parentWidget()->size();
    if (m_imageSize.width() > targetSize.width()
        || m_imageSize.height() > targetSize.height()) {
        m_initialScaleFactor = qMin(targetSize.width() / m_imageSize.width(),
                                    targetSize.height() / m_imageSize.height());
    }
    m_maxScaleFactor = 3 * m_initialScaleFactor;
    m_minScaleFactor = m_initialScaleFactor / 3;
    doSetScaleFactor(m_initialScaleFactor);

    statusMessage(msgOpen(name, origImage));
#if QT_CONFIG(cursor)
    QGuiApplication::restoreOverrideCursor();
#endif

    maybeEnablePrinting();
}

Clase JsonViewer

JsonViewer muestra un archivo JSON en un ` QTreeView`. Internamente, carga el contenido de un archivo en un ` QJsonDocument ` y lo utiliza para rellenar un modelo de árbol personalizado con ` JsonItemModel`.

El complemento JSON Viewer muestra cómo implementar un modelo de elemento personalizado heredado de QAbstractItemModel. La clase JsonTreeItem proporciona una API básica para manipular datos JSON y propagarlos de vuelta a la QJsonDocument subyacente.

JsonViewer utiliza los objetos de nivel superior del documento como marcadores para la navegación. Se pueden añadir otros nodos (claves y valores) como marcadores adicionales, o eliminarlos de la lista de marcadores.

Clase PdfViewer

La clase PdfViewer (y su complemento) es una bifurcación del ejemplo «PDF Viewer Widget Example». Muestra cómo utilizar QScroller para hojear un documento con fluidez.

Otras clases relevantes

Clase HoverWatcher

La clase ` HoverWatcher ` establece un cursor personalizado al pasar el ratón por encima de un widget y lo restaura al retirarlo. Para evitar que se creen varias instancias de `HoverWatcher` para un mismo widget, se implementa como un singleton por widget.

HoverWatcher hereda de QObject y toma el QWidget al que supervisa como padre de la instancia. Instala un filtro de eventos para interceptar los eventos de paso del ratón sin consumirlos:

HoverWatcher::HoverWatcher(QWidget *watched)
    : QObject(watched), m_watched(watched)
{
    Q_ASSERT(watched);
    m_cursorShapes[Entered].emplace(Qt::OpenHandCursor);
    m_cursorShapes[MousePress].emplace(Qt::ClosedHandCursor);
    m_cursorShapes[MouseRelease].emplace(Qt::OpenHandCursor);
    // no default for Left => restore override cursor
    m_watched->installEventFilter(this);
}

La enumeración ` HoverAction ` enumera las acciones a las que reacciona `HoverWatcher`:

    enum HoverAction {
        Entered,
        MousePress,
        MouseRelease,
        Left,
        Ignore
    };

Las funciones estáticas crean observadores, comprueban su existencia para un ` QWidget` específico o desactivan un observador:

    static HoverWatcher *watcher(QWidget *watched);
    static const HoverWatcher *watcher(const QWidget *watched);
    static bool hasWatcher(QWidget *widget);
    static void dismiss(QWidget *watched);

Se puede establecer o desactivar una forma de cursor para cada `HoverAction`. Si no hay ninguna forma de cursor asociada, se restablece el cursor de la aplicación cuando se activa la acción.

public slots:
    void setCursorShape(HoverAction type, Qt::CursorShape shape);
    void unSetCursorShape(HoverAction type);

La propiedad ` mouseButtons ` contiene los botones del ratón que se deben tener en cuenta para una acción ` MousePress `:

    void setMouseButtons(Qt::MouseButtons buttons);
    void setMouseButton(Qt::MouseButton button, bool enable);

Las señales específicas de la acción se emiten tras procesar una acción:

signals:
    void entered();
    void mousePressed();
    void mouseReleased();
    void left();

Se emite una señal general que pasa la acción procesada como argumento:

void hoverAction(HoverAction action);
Clase `RecentFiles`

RecentFiles es un ` QStringList ` especializado en gestionar una lista de archivos abiertos recientemente.

RecentFiles dispone de ranuras para añadir un solo archivo o varios archivos de una sola vez. Se añade una entrada a la lista de archivos recientes si la ruta apunta a un archivo que existe y se puede abrir. Si un archivo ya se encuentra en la lista, se elimina de su posición original y se añade al principio.

public slots:
    void addFile(const QString &fileName) { addFile(fileName, EmitPolicy::EmitWhenChanged); }
    void addFiles(const QStringList &fileNames);

Los archivos se eliminan de la lista por nombre o por índice:

    void removeFile(const QString &fileName) { removeFile(m_files.indexOf(fileName)); }
    void removeFile(qsizetype index) {removeFile(index, RemoveReason::Other); }

Componentes que implementan el guardado y la restauración desde QSettings:

    void saveSettings(QSettings &settings, const QString &key) const;
    bool restoreFromSettings(QSettings &settings, const QString &key);

Al restaurar la configuración, se ignoran los archivos que no existen. La propiedad « maxFiles » establece el número máximo de archivos recientes que se pueden almacenar (el valor por defecto es 10).

qsizetype maxFiles();
void setMaxFiles(qsizetype maxFiles);

RecentFiles comprueba que un archivo se pueda leer antes de aceptarlo.

Clase RecentFileMenu

RecentFileMenu es un « QMenu », especializado en mostrar un objeto «RecentFiles» como submenú.

Su constructor toma un puntero a un « QObject » padre y un puntero a un objeto «RecentFiles», cuyo contenido visualizará. Su señal « fileOpened() », que se activa cuando el usuario selecciona un archivo reciente de la lista, pasa la ruta absoluta del archivo como argumento.

Nota: « RecentFileMenu » es destruido bien por su widget padre, bien por el objeto « RecentFiles » pasado a su constructor.

class RecentFileMenu : public QMenu
{
    Q_OBJECT

public:
    explicit RecentFileMenu(QWidget *parent, RecentFiles *recent);

signals:
    void fileOpened(const QString &fileName);
    ...
};

Traducciones

La interfaz de usuario de la aplicación está disponible en inglés y alemán. Qt selecciona automáticamente el idioma por defecto: alemán si el idioma del sistema es el alemán; en caso contrario, inglés. Además, el usuario puede cambiar el idioma en el menú « Help » > « Language ». Cada complemento, al igual que la aplicación principal, se encarga de forma independiente de cargar sus propias traducciones durante la ejecución.

Integración con CMake

El archivo CMakeLists.txt de nivel superior declara los idiomas incluidos.

qt_standard_project_setup(REQUIRES 6.8
    I18N_SOURCE_LANGUAGE en
    I18N_TRANSLATED_LANGUAGES de
)

El objetivo « documentviewer » define la aplicación principal. Almacena y carga las cadenas localizadas para el objetivo en los archivos docviewer_de.ts y docviewer_en.ts. Además, fusiona los respectivos archivos « qtbase translations » proporcionados por Qt en los archivos de traducción generados, de modo que los cuadros de diálogo de Qt, como el de impresión, también se traduzcan correctamente:

qt_add_translations(documentviewer
    SOURCE_TARGETS documentviewer abstractviewer
    TS_FILE_BASE docviewer
    MERGE_QT_TRANSLATIONS
    QT_TRANSLATION_CATALOGS qtbase
)

Cada « CMakeLists.txt » a nivel de complemento invoca « qt_add_translations » únicamente sobre los archivos fuente de ese complemento (SOURCE_TARGETS). Limitar el alcance de los archivos de traducción al objetivo del complemento evita que se vuelvan a analizar y traducir las fuentes de la aplicación principal y de otros complementos:

qt_add_translations(txtviewer
    SOURCE_TARGETS txtviewer
    TS_FILE_BASE txtviewer
)
Clase `Translator`

La clase ` Translator ` es un envoltorio de ` QTranslator ` de Qt que gestiona la internacionalización tanto de la aplicación principal como de cada complemento. Cada componente (aplicación principal y complementos) tiene su propia instancia de `Translator`, lo que permite cambiar de idioma de forma coordinada en toda la aplicación. Al iniciarse la aplicación o cuando el usuario selecciona un nuevo idioma, se invoca el método « Translator::install() ». Este método utiliza « QTranslator::load()» para cargar los archivos de traducción basándose en la propiedad « QLocale::uiLanguages()» y el nombre base en el sistema de recursos de Qt. Si no se encuentra ninguna traducción que coincida, se recurre al inglés.

void Translator::install()
{
    if (m_baseName.isEmpty()) {
        qWarning() << "The basename of the translation is not set. Ignoring.";
       return;
    }
    if (!m_translator.isEmpty())
        qApp->removeTranslator(&m_translator);

   if (m_translator.load(m_trLocale, m_baseName, "_"_L1, ":/i18n/"_L1)
        && qApp->installTranslator(&m_translator)) {
        qInfo() << "Loaded translation" << m_translator.filePath();
    } else {
        if (m_trLocale.language() != QLocale::English) {
            qWarning() << "Failed to load translation" << m_baseName <<
                   "para la configuración regional" << m_trLocale.name() << ". Se recurre a la traducción al inglés";
            setLanguage(QLocale::English);
        }
    }
}
Compatibilidad con complementos

La clase base AbstractViewer proporciona soporte para la traducción, de modo que cada complemento pueda gestionar sus propias traducciones de forma autónoma:

  • AbstractViewer::setTranslationBaseName(): inicializa un objeto Translator, establece su nombre base y lo instala para cargar las traducciones predeterminadas.
    void AbstractViewer::setTranslationBaseName(const QString &baseName)
    {
        m_translator.reset(new Translator);
        m_translator->setBaseName(baseName);
        m_translator->install();
    }
  • AbstractViewer::eventFilter(): instalado en la ventana principal de ` init()`, este método escucha los eventos ` QEvent::LanguageChange `. Cuando cambia la configuración regional, reinstala el traductor del complemento para el nuevo idioma y llama a ` retranslate() ` para actualizar todo el texto.
    bool AbstractViewer::eventFilter(QObject *, QEvent *event)
    {
        if (event->type() != QEvent::LanguageChange)
            return false;
    
        const QLocale locale;
        if (locale != m_currentLocale) {
            m_currentLocale = locale;
            if (m_translator) {
                m_translator->setLanguage(locale.language());
                m_translator->install();
            }
            retranslate();
        }
        return false;
    }
  • AbstractViewer::retranslate(): un método virtual que cada complemento implementa para volver a traducir sus propios textos de la interfaz de usuario. Por ejemplo, tal y como se ha reimplementado en ImageViewer:
        retranslate();
    }

Los widgets que pertenecen a un complemento y contienen cadenas traducibles pueden gestionar directamente QEvent::LanguageChange. Por ejemplo, ZoomSelector anula changeEvent() para volver a traducir los elementos de su cuadro combinado:

void ZoomSelector::changeEvent(QEvent *event)
{
    if (event->type() == QEvent::LanguageChange)
        retranslate();
    QComboBox::changeEvent(event);
}
Inicio de la aplicación
  • Aplicación principal: en main.cpp cargamos la traducción de la aplicación antes de mostrar la ventana:
        Translator mainTranslator;
        mainTranslator.setBaseName("docviewer"_L1);
        mainTranslator.install();
  • Complementos: cada complemento llama a ` AbstractViewer::setTranslationBaseName() ` en su función ` init() ` para inicializar un `Translator ` con el nombre de su archivo de traducción e instalar las traducciones del idioma actual.
    void ImageViewer::init(QFile *file, QWidget *parent, QMainWindow *mainWindow)
        ...
        setTranslationBaseName("imgviewer"_L1);
        ...
Cambio de idioma en tiempo de ejecución

El cambio de idioma en tiempo de ejecución puede activarse de dos maneras:

  1. Cambio del idioma de todo el sistema en tiempo de ejecución: el sistema operativo envía un evento « QEvent::LocaleChange » a la aplicación.
  2. Utilizando el menú « Help » > « Language »: al hacer clic en la opción « QMenu » se activa « MainWindow::onActionSwitchLanguage() », que establece la configuración regional predeterminada y envía un evento « QEvent::LocaleChange », para entrar en el mismo flujo que un cambio de configuración regional del sistema:
    void MainWindow::onActionSwitchLanguage(QLocale::Language lang)
    {
        QLocale::setDefault(QLocale(lang));
        QEvent event(QEvent::LocaleChange);
        QCoreApplication::sendEvent(this, &event);
    }

En ambos casos, MainWindow::changeEvent() gestiona los eventos. QEvent::LocaleChange instala el nuevo traductor y el QEvent::LanguageChange resultante vuelve a traducir la interfaz de usuario de la ventana principal. Los complementos reaccionan a través de sus filtros de eventos.

void MainWindow::changeEvent(QEvent *event)
{
    switch (event->type()) {
    case QEvent::LanguageChange:
        ui->retranslateUi(this);
        statusBar()->clearMessage();
        break;
    case QEvent::LocaleChange:
        m_translator.setLanguage(QLocale().language());
        m_translator.install();
        break;
    default:
        break;
    }

    QMainWindow::changeEvent(event);
}

Archivos fuente

Proyecto de ejemplo en code.qt.io

Véase también: Todos los ejemplos 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.