Visualisateur de documents

Une application Widgets pour afficher et imprimer des fichiers JSON, texte et PDF.

L'interface utilisateur de la visionneuse de documents affiche une fenêtre contextuelle "Sélectionner le mode d'ouverture".

Document Viewer montre comment utiliser un site QMainWindow avec des barres d'outils statiques et dynamiques, des menus et des actions. En outre, il démontre les fonctionnalités suivantes dans les applications basées sur des widgets :

  • Utilisation de QSettings pour interroger et enregistrer les préférences de l'utilisateur et gérer l'historique des fichiers précédemment ouverts.
  • Contrôle du comportement du curseur lors du survol des widgets.
  • Création de plugins chargés dynamiquement.
  • Localisation de l'interface utilisateur dans différentes langues.

Exécution de l'exemple

Pour exécuter l'exemple à partir de Qt Creatorouvrez le mode Welcome et sélectionnez l'exemple à partir de Examples. Pour plus d'informations, voir Qt Creator: Tutoriel : Construire et exécuter.

Création d'une application et de la fenêtre principale

L'application et sa fenêtre principale sont construites à l'adresse main.cpp. La fonction main() utilise QCommandLineParser pour traiter les arguments de la ligne de commande - help, version et un argument de position facultatif, file. Si l'utilisateur a fourni un chemin d'accès à un fichier lors du lancement de l'application, la fenêtre principale l'ouvre :

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();
}

Classe MainWindow

La classe MainWindow fournit un écran d'application avec des menus, des actions et une barre d'outils. Elle peut ouvrir un fichier en détectant automatiquement son type de contenu. Elle maintient également une liste des fichiers précédemment ouverts, en utilisant QSettings pour stocker et recharger les paramètres au moment du lancement. La fenêtre principale crée une visionneuse adaptée au fichier ouvert, en fonction de son type de contenu, et permet d'imprimer un document.

Le constructeur de MainWindow initialise l'interface utilisateur créée dans Qt Designer. Le fichier mainwindow.ui comporte une fenêtre QTabWidget sur la gauche, qui affiche des signets et des vignettes. À droite, une fenêtre QScrollArea permet de visualiser le contenu d'un fichier.

Classe ViewerFactory

La classe ViewerFactory gère les visionneuses pour les types de fichiers connus. Ces visionneuses sont implémentées sous forme de modules d'extension. Lorsqu'une instance de ViewerFactory est créée, les pointeurs vers la zone de visualisation et la fenêtre principale sont transmis au constructeur :

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

ViewerFactory charge tous les plugins disponibles lors de la construction. Il fournit une API publique pour interroger les plugins chargés, leurs noms et les types MIME pris en charge :

    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 fonction viewer() renvoie un pointeur vers le plugin approprié pour ouvrir la fenêtre QFile passée en argument :

m_viewer = m_factory->viewer(file);

Si les paramètres de l'application contiennent une section pour le visualiseur, celle-ci est transmise à la fonction virtuelle restoreState() du visualiseur :

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);
}

Ensuite, les éléments standard de l'interface utilisateur sont transmis au visualiseur et la zone de défilement principale est définie pour afficher le widget d'affichage du visualiseur :

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

La classe AbstractViewer

AbstractViewer fournit une API généralisée pour visualiser, enregistrer et imprimer un document. Les propriétés du document et de la visionneuse peuvent être interrogées :

  • Le document a-t-il un contenu ?
  • A-t-il été modifié ?
  • Une vue d'ensemble (vignettes ou signets) est-elle possible ?

AbstractViewer fournit des méthodes protégées pour les classes dérivées afin de créer des actions et des menus sur la fenêtre principale. Afin d'afficher ces éléments sur la fenêtre principale, ils lui sont rattachés par un lien de parenté. AbstractViewer est responsable de la suppression et de la destruction des éléments d'interface utilisateur qu'il crée. Il hérite de QObject pour implémenter les signaux et les slots.

Signaux

void uiInitialized();

Ce signal est émis après qu'un visualiseur a reçu toutes les informations nécessaires sur les éléments d'interface utilisateur de la fenêtre principale.

void printingEnabledChanged(bool enabled);

Ce signal est émis lorsque l'impression de documents est activée ou désactivée. Cela se produit lorsqu'un nouveau document a été chargé avec succès ou, par exemple, lorsque tout le contenu a été supprimé.

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

Ce signal est émis pour afficher un message d'état à l'utilisateur.

void documentLoaded(const QString &fileName);

Ce signal informe l'application qu'un document a été chargé avec succès.

La classe TxtViewer

TxtViewer est une simple visionneuse de texte, héritant de AbstractViewer. Elle permet d'éditer des fichiers texte, de copier/couper et coller, d'imprimer et d'enregistrer les modifications.

La classe ImageViewer

ImageViewer affiche des images, comme le prévoit QImageReader, en utilisant un QLabel.

Dans le constructeur, nous augmentons la limite d'allocation de QImageReader pour permettre l'utilisation de photos plus grandes :

ImageViewer::ImageViewer() : m_formats(imageFormats())
{
    connect(this, &AbstractViewer::uiInitialized, this, &ImageViewer::setupImageUi);
    QImageReader::setAllocationLimit(1024); // MB
}

Dans la fonction openFile(), nous chargeons l'image et déterminons sa taille. Si elle est plus grande que l'écran, nous la réduisons à la taille de l'écran, en conservant le rapport hauteur/largeur. Ce calcul doit être effectué en pixels natifs, et le rapport de pixel de l'appareil doit être défini sur la pixmap résultante pour qu'elle apparaisse nette :

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();
}

Classe JsonViewer

JsonViewer affiche un fichier JSON dans une page QTreeView. En interne, elle charge le contenu d'un fichier dans une page QJsonDocument et l'utilise pour remplir un modèle d'arbre personnalisé à l'aide de la page JsonItemModel.

Le plugin JSONViewer montre comment mettre en œuvre un modèle d'élément personnalisé hérité de QAbstractItemModel. La classe JsonTreeItem fournit une API de base pour la manipulation des données JSON et leur propagation vers le modèle sous-jacent QJsonDocument.

JsonViewer utilise les objets de premier niveau du document comme signets pour la navigation. D'autres nœuds (clés et valeurs) peuvent être ajoutés en tant que signets supplémentaires ou supprimés de la liste des signets.

Classe PdfViewer

La classe PdfViewer (et le plugin) est un dérivé du PDF Viewer Widget Example. Elle démontre l'utilisation de QScroller pour parcourir un document en douceur.

Autres classes pertinentes

Classe HoverWatcher

La classe HoverWatcher définit un curseur de substitution lorsque la souris passe au-dessus d'un widget, et le rétablit lorsqu'elle quitte le widget. Afin d'éviter la création de plusieurs instances de HoverWatcher pour le même widget, elle est implémentée en tant que singleton par widget.

HoverWatcher hérite de QObject et prend le QWidget qu'il surveille comme parent de l'instance. Il installe un filtre d'événements pour intercepter les événements de survol sans les consommer :

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);
}

L'énumération HoverAction dresse la liste des actions auxquelles HoverWatcher réagit :

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

Les fonctions statiques créent des observateurs, vérifient leur existence pour une adresse QWidget spécifique ou suppriment un observateur :

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

Une forme de curseur peut être définie ou non pour chaque HoverAction. S'il n'y a pas de forme de curseur associée, le curseur prioritaire de l'application est rétabli lorsque l'action est déclenchée.

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

La propriété mouseButtons contient les boutons de souris à prendre en compte pour une action MousePress:

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

Des signaux spécifiques à l'action sont émis après le traitement d'une action :

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

Un signal général est émis, qui prend l'action traitée comme argument :

void hoverAction(HoverAction action);
La classe RecentFiles

RecentFiles est une classe QStringList spécialisée dans la gestion d'une liste de fichiers récemment ouverts.

RecentFiles dispose d'emplacements permettant d'ajouter un seul fichier ou plusieurs fichiers en une seule fois. Une entrée est ajoutée à la liste des fichiers récents si le chemin d'accès pointe vers un fichier qui existe et peut être ouvert. Si un fichier figure déjà dans la liste, il est supprimé de sa position initiale et ajouté au début de la liste.

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

Les fichiers sont retirés de la liste soit par leur nom, soit par leur index :

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

Les emplacements qui permettent de sauvegarder et de restaurer à partir de QSettings:

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

Lors de la restauration des paramètres, les fichiers inexistants sont ignorés. La propriété maxFiles contient la quantité maximale de fichiers récents à stocker (10 par défaut).

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

RecentFiles vérifie qu'un fichier peut être lu avant de l'accepter.

La classe RecentFileMenu

RecentFileMenu est une classe QMenu, spécialisée dans l'affichage d'un objet RecentFiles sous forme de sous-menu.

Son constructeur prend un pointeur vers un parent QObject et un pointeur vers un objet RecentFiles, dont il visualisera le contenu. Son signal fileOpened(), déclenché lorsque l'utilisateur sélectionne un fichier récent dans la liste, prend en argument le chemin absolu du fichier.

Remarque : RecentFileMenu est détruit soit par son widget parent, soit par l'objet RecentFiles transmis à son constructeur.

class RecentFileMenu : public QMenu
{
    Q_OBJECT

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

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

Traductions

L'interface utilisateur de l'application est disponible en anglais et en allemand. La langue par défaut est sélectionnée automatiquement par Qt : German si la langue du système est l'allemand ; sinon, c'est l'anglais. L'utilisateur peut également changer de langue dans le menu Help > Language. Chaque plugin, ainsi que l'application principale, est indépendamment responsable du chargement de ses propres traductions pendant l'exécution.

Intégration de CMake

Le fichier CMakeLists.txt de premier niveau déclare les langages livrés.

qt_standard_project_setup(REQUIRES 6.8
    I18N_SOURCE_LANGUAGE en
    I18N_TRANSLATED_LANGUAGES de
)

La cible documentviewer définit l'application principale. Elle stocke et charge les chaînes localisées pour la cible dans les fichiers docviewer_de.ts et docviewer_en.ts. En outre, il fusionne les qtbase translations respectifs fournis par Qtt dans les fichiers de traduction générés, de sorte que les dialogues Qt tels que le dialogue d'impression sont également correctement traduits :

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

Chaque niveau de plugin CMakeLists.txt invoque qt_add_translations uniquement sur les fichiers sources de ce plugin (SOURCE_TARGETS). Le fait d'adapter les fichiers de traduction à la cible du plugin permet d'éviter de scanner et de retraduire les sources de l'application principale et des autres plugins :

qt_add_translations(txtviewer
    SOURCE_TARGETS txtviewer
    TS_FILE_BASE txtviewer
)
Classe de traducteur

La classe Translator est une enveloppe autour de QTranslator de Qt qui gère l'internationalisation à la fois pour l'application principale et pour chaque plugin. Chaque composant (application principale et plugins) possède sa propre instance de Translator, ce qui permet de coordonner le changement de langue dans l'ensemble de l'application. Au démarrage ou lorsque l'utilisateur sélectionne une nouvelle langue, Translator::install() est appelé. Cette méthode utilise QTranslator::load() pour charger les fichiers de traduction en fonction de QLocale::uiLanguages() et du nom de base dans le système de ressources Qt. Si aucune traduction correspondante n'est trouvée, l'anglais est rétabli.

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 <<
                   "pour la locale"<< m_trLocale.name()<< ". Retrouver la traduction anglaise"; setLanguage(QLocale::English) ; } }
Support des plugins

La classe de base AbstractViewer fournit trois méthodes permettant à chaque plugin de gérer sa propre traduction :

  • AbstractViewer::setTranslationBaseName()La classe de base Translator: initialise un objet , définit son nom de base et l'installe pour charger les traductions par défaut.
    void AbstractViewer::setTranslationBaseName(const QString &baseName)
    {
        m_translator.reset(new Translator);
        m_translator->setBaseName(baseName);
        m_translator->install();
    }
  • AbstractViewer::updateTranslation()La classe de base retranslate() appelle install() sur le traducteur existant pour installer les nouvelles traductions, puis appelle pour actualiser tout le texte.
    void AbstractViewer::updateTranslation(QLocale::Language lang)
    {
        if (m_translator) {
            m_translator->setLanguage(lang);
            m_translator->install();
            retranslate();
        }
    }
  • AbstractViewer::retranslate()Méthode virtuelle : méthode virtuelle que chaque plugin implémente pour retraduire ses propres textes d'interface utilisateur. Par exemple, telle que réimplémentée dans ImageViewer :
    void ImageViewer::retranslate()
    {
        m_toolBar->setWindowTitle(tr("Images"));
        m_zoomInAct->setText(tr("Zoom &In"));
        m_zoomOutAct->setText(tr("Zoom &Out"));
        m_resetZoomAct->setText(tr("Reset Zoom"));
    }
Démarrage de l'application
  • Application principale: sur main.cpp, nous chargeons la traduction de l'application avant d'afficher la fenêtre :
        Translator mainTranslator;
        mainTranslator.setBaseName("docviewer"_L1);
        mainTranslator.install();
  • Plugins: chaque plugin appelle AbstractViewer::setTranslationBaseName() dans sa fonction init() pour initialiser un traducteur avec le nom de son fichier de traduction et installer les traductions de la langue courante.
    void ImageViewer::init(QFile *file, QWidget *parent, QMainWindow *mainWindow)
        ...
        setTranslationBaseName("imgviewer"_L1);
        ...
Changement de langue en cours d'exécution

Le changement de langue en cours d'exécution peut se faire de deux manières :

  1. En utilisant le menu Help > Language: Cliquer sur l'élément QMenu déclenche MainWindow::onActionSwitchLanguage(), qui installera la nouvelle langue et retraduira l'application principale et les plugins :
    void MainWindow::onActionSwitchLanguage(QLocale::Language lang)
    {
        m_translator.setLanguage(lang);
        m_translator.install();
        ui->retranslateUi(this);
        const auto viewerList = m_factory->viewers();
        for (AbstractViewer *viewer : viewerList)
            viewer->updateTranslation(lang);
        statusBar()->clearMessage();
    }
  2. En changeant la langue de l'ensemble du système au moment de l'exécution : L'application peut réagir en écoutant les événements et en appelant MainWindow::onActionSwitchLanguage() sur l'événement QEvent::LocaleChange.
    void MainWindow::changeEvent(QEvent *event)
    {
        if (event->type() == QEvent::LocaleChange)
            onActionSwitchLanguage(QLocale::system().language());
    
        QMainWindow::changeEvent(event);
    }

Fichiers sources

Exemple de projet @ code.qt.io

Voir aussi Tous les exemples de Qt.

© 2025 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.