Revision control
Copy as Markdown
// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\title Document Viewer
\ingroup examples-widgets
\example demos/documentviewer
\examplecategory {Application Examples}
\meta {tag} {demo,widgets,mainwindow}
\brief A Widgets application to display and print JSON, text, and PDF files.
\image documentviewer_open.png
{Document viewer UI showing a 'Select Open Mode' pop-up}
\e{Document Viewer} demonstrates how to use a QMainWindow with static
and dynamic toolbars, menus, and actions. Additionally, it demonstrates
the following features in widget-based applications:
\list
\li Using QSettings to query and save user preferences,
and managing previously opened file history.
\li Controlling cursor behavior when hovering over widgets.
\li Creating dynamically loaded plugins.
\li Localizing the UI to different languages.
\endlist
\include examples-run.qdocinc
\section1 Creating an application and the main window
The application and its main window is constructed in \c main.cpp.
The main() function uses QCommandLineParser to process command line
arguments---\e help, \e version, and an optional positional
argument, \e file. If the user provided a path to a file when
launching the application, the main window opens it:
\quotefromfile demos/documentviewer/app/main.cpp
\skipto int main
\printuntil exec
\printline }
\section1 MainWindow class
The \c MainWindow class provides an application screen with menus,
actions, and a toolbar. It can open a file, automatically detecting its
content type. It also maintains a list of previously opened files, using
QSettings to store and reload settings when launched. The MainWindow
creates a suitable \e viewer for the opened file, based on its content type,
and provides support for printing a document.
MainWindow's constructor initializes the user interface created in Qt
Designer. The \c mainwindow.ui file provides a QTabWidget on the left,
showing bookmarks and thumbnails. On the right, there is a QScrollArea for
viewing file content.
\section1 ViewerFactory class
The \c ViewerFactory class manages viewers for known file types. These viewers
are implemented as plugins. When an instance of a ViewerFactory is created,
pointers to the view area and the main window are passed to the constructor:
\code
m_factory.reset(new ViewerFactory(ui->viewArea, this));
\endcode
ViewerFactory loads all available plugins on construction. It provides
a public API to query the loaded plugins, their names, and supported MIME
types:
\quotefromfile demos/documentviewer/app/viewerfactory.h
\skipto ViewerList
\printuntil QStringList supportedMimeTypes() const;
The \c viewer() function returns a pointer to the plugin suitable to open
the QFile passed as an argument:
\code
m_viewer = m_factory->viewer(file);
\endcode
If the application settings contain a section for the viewer, it's passed
to the viewer's virtual \c restoreState() function:
\quotefromfile demos/documentviewer/app/mainwindow.cpp
\skipto MainWindow::restoreViewerSettings
\printuntil restoreState
\printline }
Then, the standard UI assets are passed to the viewer and the main scroll
area is set to show the viewer's display widget:
\quotefromfile demos/documentviewer/app/mainwindow.cpp
\skipuntil bool MainWindow::openFile
\skipto m_viewer->initViewer
\printuntil }
\section1 AbstractViewer class
\c AbstractViewer provides a generalized API to view, save, and print a
document. Properties of both the document and the viewer can be queried:
\list
\li Does the document have content?
\li Has it been modified?
\li Is an overview (thumbnails or bookmarks) supported?
\endlist
AbstractViewer provides protected methods for derived classes to create
actions and menus on the main window. In order to display these
assets on the main window, they are parented to it. AbstractViewer is
responsible for removing and destroying the UI assets it creates. It
inherits from QObject to implement signals and slots.
\section2 Signals
\c {void uiInitialized();}
This signal is emitted after a viewer receives all necessary information
about UI assets on the main window.
\c {void printingEnabledChanged(bool enabled);}
This signal is emitted when document printing is either enabled or
disabled. This happens after a new document was successfully loaded,
or, for example, all content was removed.
\c {void showMessage(const QString &message, int timeout = 8000);}
This signal is emitted to display a status message to the user.
\c {void documentLoaded(const QString &fileName);}
This signal notifies the application that a document was successfully
loaded.
\section1 TxtViewer class
\c TxtViewer is a simple text viewer, inheriting from AbstractViewer.
It supports editing text files, copy/cut and paste, printing, and
saving changes.
\section2 Class Definition
\snippet demos/documentviewer/plugins/txtviewer/txtviewer.h interfacing
The class definition starts with the \c Q_OBJECT macro, which handles
signals and slots. It is followed by the \c Q_PLUGIN_METADATA and
\c Q_INTERFACES macros which are necessary to register the plugin.
The class inherits from \c ViewerInterface, which inherits from
\c AbstractViewer. The \c ViewerInterface class is used to provide an
interface between the main window application and the plugin.
\c QPluginLoader also requires the file txtviewer.json, which has to contain
the plugin's key:
\code
{ "Keys": [ "txtviewer" ] }
\endcode
The class defines no constructor, which means that only a standard
constructor without arguments is available. All other functions, including
the destructor, re-implement virtual functions of \c ViewerInterface. They
are used to exchange data, information, and instructions with the main
application.
\snippet demos/documentviewer/plugins/txtviewer/txtviewer.h classDefinition
\section2 TxtViewer Class Implementation
\snippet demos/documentviewer/plugins/txtviewer/txtviewer.cpp init
We start by including the header files necessary to access all classes used
by \c TxtViewer. We also include \c txtviewer.h.
\c QPrinter and \c QPrintDialog are only included if print support is
enabled on the compilation system.
Note that these headers are not included directly in \c mainwindow.h.
Including large headers in other header files can impact build performance.
In this case, it would not cause issues, but it is best practice to include
only the necessary headers to keep dependencies minimal.
The implementation starts with an empty destructor. It could be completely
omitted. It's good practice to implement it empty in order to point out to
code readers that nothing needs to be done in the destructor.
The destructor is followed by an initialization function, taking three
arguments:
\list
\li \c file, the pointer to the file to be opened and displayed.
\li \c parent, pointing to the \c QWidget inside which the editor shall be placed.
\li \c mainWindow, pointing to the application's main window, where menus and menu bars
are handled.
\endlist
The function calls the base init function of \c AbstractViewer. A new
QPlainTextEdit widget is created, which will display the file's contents.
Then, \c TxtViewer's setup function is connected to the base class'
\c uiInitialized signal.
The next function returns the list of mime types, which the text viewer
supports. Only plain text is supported.
The last initialization function adds viewer specific UI components like
menus, icons, buttons, and tooltips. It uses functionality provided by
\c AbstractViewer to make sure that these components are removed from the
application's main window, once another file is displayed with another
viewer plugin.
\snippet demos/documentviewer/plugins/txtviewer/txtviewer.cpp open
\c openFile opens a file, transfers its contents into the QPlainTextEdit,
and prints a status message for the user, depending on whether or not the
opening was successful.
\snippet demos/documentviewer/plugins/txtviewer/txtviewer.cpp infoPrintAndSave
The next re-implemented function tells the main application whether or not
the viewer plugin is actually displaying content.
If printing is supported on the compiling system, the next section
implements it.
The last two re-implementations provide functionality to save the current
file or to save it under a new name.
\section1 ImageViewer class
\c ImageViewer displays images as supported by QImageReader, using
a QLabel.
In the constructor, we increase the allocation limit of QImageReader to
allow for larger photos:
\snippet demos/documentviewer/plugins/imageviewer/imageviewer.cpp init
In the openFile() function, we load the image and determine its size.
If it is larger than the screen, we downscale it to screen size,
maintaining the aspect ratio. This calculation has to be done in native
pixels, and the device pixel ratio needs to be set on the resulting pixmap
for it to appear crisp:
\snippet demos/documentviewer/plugins/imageviewer/imageviewer.cpp open
\section1 JsonViewer class
\c JsonViewer displays a JSON file in a QTreeView. Internally, it loads
the contents of a file into a QJsonDocument and uses it to populate a
custom tree model with \c JsonItemModel.
The JSON viewer plugin demonstrates how to implement a custom item model
inherited from QAbstractItemModel. The \c JsonTreeItem class provides a
basic API for manipulating JSON data and propagating it back to the
underlying QJsonDocument.
JsonViewer uses the top-level objects of the document as bookmarks for
navigation. Other nodes (keys and values) can be added as additional
bookmarks, or removed from the bookmark list.
\section1 PdfViewer class
The \c PdfViewer class (and plugin) is a fork of the \l {PDF Viewer
Widget Example}. It demonstrates the use of QScroller to smoothly
flick through a document.
\section1 Other relevant classes
\section2 HoverWatcher class
The \c HoverWatcher class sets an override cursor when hovering the
mouse over a widget, restoring it upon departure. To prevent multiple
HoverWatcher instances being created for the same widget, it is
implemented as a singleton per widget.
HoverWatcher inherits from QObject and takes the QWidget it watches
as the instance's parent. It installs an event filter to intercept hover
events without consuming them:
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.cpp
\skipto HoverWatcher::HoverWatcher
\printuntil }
The \c HoverAction enum lists the actions that HoverWatcher reacts to:
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
\skipto enum HoverAction
\printuntil };
Static functions create watchers, check their existence for a specific
QWidget, or dismiss a watcher:
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
\skipto static HoverWatcher
\printuntil static void dismiss
A cursor shape can be set or unset for each HoverAction. If there is
no associated cursor shape, the application's override cursor is
restored when the action is triggered.
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
\skipto public slots
\printuntil void unSetCursorShape
The \c mouseButtons property holds the mouse buttons to consider for a
\c MousePress action:
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
\skipuntil public slots
\skipto setMouseButtons
\printuntil setMouseButton(
Action-specific signals are emitted after processing an action:
\quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h
\skipto signals
\printuntil left();
A general signal is emitted which passes the processed action as an
argument:
\code
void hoverAction(HoverAction action);
\endcode
\section2 RecentFiles class
\c RecentFiles is a QStringList that is specialized to manage a list of
recently opened files.
RecentFiles has slots to add either a single file or multiple files in one
go. An entry is added to the list of recent files if the path points to a
file that exists and can be opened. If a file is already in the list, it
is removed from its original position and added to the top.
\quotefromfile demos/documentviewer/app/recentfiles.h
\skipto public slots
\printuntil addFiles
Files are removed from the list either by name or by index:
\quotefromfile demos/documentviewer/app/recentfiles.h
\skipuntil public slots
\skipto removeFile
\printuntil qsizetype index
Slots that implement saving and restoring from QSettings:
\quotefromfile demos/documentviewer/app/recentfiles.h
\skipuntil public slots
\skipto saveSettings
\printuntil restoreFromSettings
When restoring settings, nonexistent files are ignored. The \c maxFiles
property holds the maximum amount of recent files to store (default is
10).
\code
qsizetype maxFiles();
void setMaxFiles(qsizetype maxFiles);
\endcode
\c {RecentFiles} verifies that a file can be read before
accepting it.
\section2 RecentFileMenu class
\c {RecentFileMenu} is a QMenu, specialized to display a
\l{RecentFiles class}{RecentFiles} object as a submenu.
Its constructor takes a pointer to a parent QObject and a pointer to a
RecentFiles object, the content of which it will visualize.
Its \c fileOpened() signal, triggered when the user selects a recent file
from the list, passes the absolute path to the file as an argument.
\note \c {RecentFileMenu} is destroyed either by its parent widget, or by the
\c {RecentFiles} object passed to its constructor.
\quotefromfile demos/documentviewer/app/recentfilemenu.h
\skipto class RecentFileMenu
\printuntil void fileOpened
\dots
\skipuntil RecentFiles
\printline }
\section1 Translations
The application's user interface is available in English and German.
The default language is auto-selected by Qt: German if the system
language is German; otherwise, English. Also, the user can switch
the language in the \uicontrol Help > \uicontrol Language menu.
Each plugin, as well as the main application, is independently
responsible for loading its own translations during runtime.
\section2 CMake integration
The top-level CMakeLists.txt declares the shipped languages.
\quotefromfile demos/documentviewer/CMakeLists.txt
\skipto qt_standard_project_setup
\printuntil )
The \c documentviewer target defines the main application. It
stores and loads the localized strings for the target in
docviewer_de.ts and docviewer_en.ts files. Furthermore,
it merges the respective \c{qtbase translations} provided by
Qt into the generated translation files, so that
also Qt dialogs like the print dialog are properly translated:
\quotefromfile demos/documentviewer/app/CMakeLists.txt
\skipto qt_add_translations(documentviewer
\printuntil )
Each plugin level \c CMakeLists.txt invokes \c qt_add_translations only
on that plugin's source files (\c SOURCE_TARGETS).
Scoping the translation files to the plugin target prevents re-scanning
and retranslating the sources of the main application and other plugins:
\quotefromfile demos/documentviewer/plugins/txtviewer/CMakeLists.txt
\skipto qt_add_translations(txtviewer
\printuntil )
\section2 Translator class
The \c Translator class is a wrapper around Qt's \l QTranslator that manages
internationalization for both the main application and each plugin. Each
component (main application and plugins) has its own Translator instance,
enabling coordinated language switching across the entire application.
At startup or when the user selects a new language, \c Translator::install()
is called. This method uses \l QTranslator::load() to load translation files
based on the QLocale::uiLanguages() and the basename in the Qt resource system.
If no matching translation is found, it falls back to English.
\quotefromfile demos/documentviewer/app/translator.cpp
\skipto void Translator::install
\printuntil /^\}/
\section2 Plugin support
The \c AbstractViewer base class provides translation support so each plugin
can manage its own translations autonomously:
\list
\li \c AbstractViewer::setTranslationBaseName(): initializes a \c Translator
object, sets its basename, and installs it to load the default translations.
\quotefromfile demos/documentviewer/app/abstractviewer.cpp
\skipto setTranslationBaseName
\printuntil }
\li \c AbstractViewer::eventFilter(): installed on the main window in
\c init(), this method listens for \l QEvent::LanguageChange events. When the
locale has changed, it reinstalls the plugin's translator for the new language
and calls \c retranslate() to refresh all text.
\quotefromfile demos/documentviewer/app/abstractviewer.cpp
\skipto eventFilter
\printuntil /^\}/
\li \c AbstractViewer::retranslate(): a virtual method that each plugin implements
to retranslate its own UI texts. For instance, as reimplemented in ImageViewer:
\quotefromfile demos/documentviewer/plugins/imageviewer/imageviewer.cpp
\skipto retranslate
\printuntil }
\endlist
Widgets that are owned by a plugin and contain translatable strings can
handle \l QEvent::LanguageChange directly. For example, \c ZoomSelector
overrides \c changeEvent() to retranslate its combo box items:
\quotefromfile demos/documentviewer/plugins/pdfviewer/zoomselector.cpp
\skipto ZoomSelector::changeEvent
\printuntil /^\}/
\section2 Application startup
\list
\li \e{Main application}: in \c main.cpp we load the application's translation
before showing the window:
\quotefromfile demos/documentviewer/app/main.cpp
\skipto Translator mainTranslator;
\printuntil mainTranslator.install();
\li \e Plugins: each plugin calls \c AbstractViewer::setTranslationBaseName()
in its \c init() function to initialize a \l{Translator class}{Translator} with
their translation file name and install the translations of the current language.
\quotefromfile demos/documentviewer/plugins/imageviewer/imageviewer.cpp
\skipto ImageViewer::init(
\printuntil init
\dots
\skipto setTranslation
\printline setTranslation
\dots
\endlist
\section2 Runtime language switching
Runtime language switching can be triggered in two ways:
\list 1
\li Switching the language of the whole system at runtime:
The operating system sends a \l QEvent::LocaleChange event to the
application.
\li Using the menu \uicontrol Help > \uicontrol Language:
Clicking on the \c QMenu item triggers \c MainWindow::onActionSwitchLanguage(),
which sets the default locale and posts a \l QEvent::LocaleChange event,
to enter the same flow as a system locale change:
\quotefromfile demos/documentviewer/app/mainwindow.cpp
\skipto void MainWindow::onActionSwitchLanguage
\printuntil }
\endlist
In both cases, \c MainWindow::changeEvent() handles the events.
\l QEvent::LocaleChange installs the new translator, and the resulting
\l QEvent::LanguageChange retranslates the main window UI.
Plugins react via their event filters.
\quotefromfile demos/documentviewer/app/mainwindow.cpp
\skipto void MainWindow::changeEvent
\printuntil /^\}/
\section1 Source files
\sa {All Qt examples}
*/