diff options
Diffstat (limited to 'examples/demos/documentviewer/doc/src/documentviewer.qdoc')
| -rw-r--r-- | examples/demos/documentviewer/doc/src/documentviewer.qdoc | 296 |
1 files changed, 145 insertions, 151 deletions
diff --git a/examples/demos/documentviewer/doc/src/documentviewer.qdoc b/examples/demos/documentviewer/doc/src/documentviewer.qdoc index f153b6f6..ddcee81b 100644 --- a/examples/demos/documentviewer/doc/src/documentviewer.qdoc +++ b/examples/demos/documentviewer/doc/src/documentviewer.qdoc @@ -5,298 +5,292 @@ \title Document Viewer \ingroup examples-widgets \example demos/documentviewer + \meta {tag} {demo,widgets,mainwindow} \brief A Widgets application to display and print JSON, text, and PDF files. - Demonstrates various features to use in widget applications: + + \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, query and save user preferences, manage file histories and - \li Controllinh cursor behavior when hovering over widgets. - \li Writing and dynamically loading plugins. + \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. \endlist \image documentviewer_open.png - \meta {tag} {demo,widgets,mainwindow} - \e{Document Viewer} demonstrates how to use a QMainWindow with static - and dynamic tool bars, menus and actions. - - The MainWindow class provides a common application screen with general menus, - actions and a tool bar. It provides functionality to open a file, determine the - content type and keep a list of previously opened files. It stores information - in QSettings and reads settings when launched. - Depending on the opened file's content type, it creates a suitable viewer to - display it and provide printing functionality. - \section1 Creating an executable + \section1 Creating an application and the main window - To create an executable, we use a standard main.cpp file. - First, we set the application's organization name: + 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 QApplication::set - \endsection1 + \printuntil exec + \printline } - \section1 Creating an application and showing the main window - - \quotefromfile demos/documentviewer/app/main.cpp - \skipto QApplication app - \printuntil } - \endsection1 - \section1 The MainWindow class + \section1 MainWindow class - The class constructor initializes the user interface created in Qt Designer. - It links the actions for opening a file and the about dialog to their implementation. + 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. - \quotefromfile demos/documentviewer/app/mainwindow.cpp - \skipto ui->setupUi - \printuntil triggered + 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. - The \c mainwindow.ui file provides a QTabWidget on the left, where bookmarks and thumbnails - can be displayed. It provides a QScrollArea on the right, where the viewed file contents are - \printuntil showMenu); - If a file is opened, the {File} class (inheriting from {QFile}) automatically determines - the FileType used in this application. If no valid file type could be established, the user - is asked, if it should be opened as plain text. + \section1 ViewerFactory class - The \c ViewerFactory class is used to manage file type specific viewers, implemented as plugins. - When an instance of \c ViewerFactory is created, pointers to view area and QMainWindow have - to be passed to the constructor. + 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 - \c ViewerFactory loads all available plugins when constructed. It provides public APIs to - query about loaded plugins, their names, and supported mime types. + 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 method \c viewer returns the pointer to the plugin suitable to open the QFile passed - as an argument. + 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 is passed to the viewer's - virtual restoreState method. Afterwards, the standard UI assets are passed to the viewer - and it's display widget is displayed in the main scroll area. + 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 void MainWindow::openFile \skipto m_viewer->initViewer \printuntil } - \endsection1 - - \section1 The ViewerFactory class - The only static method of the class takes a file, the widget where the viewed content is to be - displayed, the main window and the user questions. - Depending on the file's mime type, it creates an appropriate document viewer. - \quotefromfile demos/documentviewer/app/mainwindow.cpp - \skipto AbstractViewer - \printuntil } - \endsection1 + \section1 AbstractViewer class - \section1 The 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: - The class provides a generalized API to view and browse through a document, save and print it. - Properties of the document and the viewer itself can be queried: Does the document have content? - Has it been modified? Is an overview (thumbnails or bookmarks) supported? - The viewer's state can be saved to and restored from a QByteArray, which the application can - access to store in its settings. + \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 classes inheriting from it, 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 takes responsibility to remove and destroy the UI assets it - created. It inherits from QObject to provide access to signals and slots. + 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();} - \code - void uiInitialized(); - \endcode + This signal is emitted after a viewer receives all necessary information + about UI assets on the main window. - The signal is emitted when AbstractViewer has received all necessary information about UI - assets on the main window. + \c {void printingEnabledChanged(bool enabled);} - \code - void printingEnabledChanged(bool enabled); - \endcode + 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. - This signal is emitted when document printing has been enabled or disabled, e.g. because a new - document has been successfully loaded or all content has been removed. + \c {void printStatusChanged(AbstractViewer::PrintStatus status);} - \code - void printStatusChanged(AbstractViewer::PrintStatus status); - \endcode + After starting the printing process, this signal notifies about changes in + its progress. - When printing has been started, this signal notifies about the printing progress. + \c {void documentLoaded(const QString &fileName);} - \code - void documentLoaded(const QString &fileName); - \endcode - \endsection2 + 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. - The signal notifies the application that a document has been loaded successfully. - \endsection1 - \section1 The TextViewer class + \section1 JsonViewer class - A simple text viewer, inheriting from AbstractViewer. - It features editing text files, copy/cut and paste, printing and saving changes. + \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. - \section1 The JsonViewer class + 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. - The plugin class displays a JSON file in a QTreeView. - It loads a file into a QJsonDocument, used to populate a custom tree model with - JsonItemModel. - This part of the JSON viewer demonstrates, how to implement custom item models inheriting from - QAbstractItemModel. The JsonTreeItem class provides 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. A QLineEdit is used as a + search field to navigate through the JSON tree. - JsonViewer uses the toplevel objects as bookmarks for navigation. Other nodes (keys or - values) can be added as additional bookmarks or removed from the bookmark list. - A QLineEdit is used as a search field to navigate through the JSON tree. - \endsection1 - \section1 The PdfViewer class - This plugin is a fork of the QPdfViewerWidgets example. - It demonstrates the use of QScroller to smoothly flick through the document. + \section1 PdfViewer class - \section1 The TxtViewer class - This plugin is a simple a text editor, to show how a user interface is written in pure C++. - \endsection1 + 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 Additional classes for application features - \section2 The HoverWatcher class + \section1 Other relevant classes - The class can be used to set override cursors when the mouse is hovering over a widget and - to restore them upon departure. - In order to prevent multiple HoverWatcher instances created for the same widget, it is + \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 the QWidget watched becomes the instance's parent. - An event filter is used to intercept the hover events without consuming them. + 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 actions watched are represented in an enum. + The \c HoverAction enum lists the actions that HoverWatcher reacts to: \quotefromfile demos/documentviewer/plugins/pdfviewer/hoverwatcher.h \skipto enum HoverAction \printuntil }; - Static methods create watchers, check their existence for a specific QWidget or dismiss - a watcher. + 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 specified or unset for each HoverAction. If no cursor shape is - specified for an action, the application's override cursor will be restored when it occurs. + 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 mouseButtons property specifies, which mouse buttons to consider for the MousePress action. + 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 when an action has been processed. + 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. + A general signal is emitted which passes the processed action as an + argument: \code void hoverAction(HoverAction action); \endcode - \endsection2 - \section2 The {RecentFiles} class + \section2 RecentFiles class - The class is a QStringList, specialized to manage a list of recently opened files. + \c RecentFiles is a QStringList that is specialized to manage a list of + recently opened files. \quotefromfile demos/documentviewer/app/recentfiles.cpp \skipto RecentFiles::RecentFiles \printuntil } - It provides slots to add a single or multiple files, by passing their path or a list - of paths as an argument. A file is added, if the path leads to a valid file. - If a file already exists in the list of recent files, it is removed from its original position - and added on the top. + 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 can be removed by name or by index. + Files are removed from the list either by name or by index: \quotefromfile demos/documentviewer/app/recentfiles.h \skipuntil public slots \skipto removeFile - \printuntil addFiles + \printuntil qsizetype index - Slots are available to save and restore from {QSettings}. - Files restored from settings are ignored, if they no longer exist. + Slots that implement saving and restoring from QSettings: \quotefromfile demos/documentviewer/app/recentfiles.h \skipuntil public slots \skipto saveSettings \printuntil restoreFromSettings - The maxFiles property manages the maximum amount of recent files to be remebered (default: 10). + 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 - {RecentFiles} verifies a file can be opened in {openMode}, before adding it. + \c {RecentFiles} verifies that a file can be opened in \c {openMode} before + accepting it. \code void setOpenMode(QIODevice::OpenMode mode); QIODevice::OpenMode openMode() const; \endcode - \endsection2 - \section2 The {RecentFileMenu} class + \section2 RecentFileMenu class - The {RecentFileMenu} class is a QMenu, specialized as a submenu to display a \l{RecentFiles} - object as a submenu. + \c {RecentFileMenu} is a QMenu, specialized to display a + \l{RecentFiles class}{RecentFiles} object as a submenu. - Its constructor takes a parent widget, usually and QAction or a QMenu. - Its fileOpened signal passes a QString argument with the absolute file name, when the - application user has selected a recent file from the list. + 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 - A {RecentFileMenu} is deleted either with its parent widget, or with the RecentFiles object - passed to its constructor. + \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 - \skipuntil class RecentFileMenu + \skipto class RecentFileMenu \printuntil void fileOpened - - \endsection2 - \endsection1 - + \dots + \skipuntil RecentFiles + \printline } */ |