// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example demos/documentviewer/plugins/txtviewer
    \title Qt Widgets - Text Viewer Plugin Example
    \examplecategory {Graphics & Multimedia}
    \ingroup examples-mainwindow

    \brief A widget example with menus, toolbars and a status bar.

    The Text Viewer example is a text editor built around QPlainTextEdit,
    in the form of a plugin for a general-purpose \l {Document Viewer}.

    \image txtviewer_screenshot.png

    All of the code for the Text Viewer example is in the \c TxtViewer class,
    which inherits \c AbstractViewer. \c AbstractViewer provides the framework
    for interaction between a viewer and the main window. The application provides
    \uicontrol{File}, \uicontrol{Edit}, and \uicontrol{Help} entries in the menu
    bar.

    The status bar at the bottom of the main window shows a message provided by
    the application to its user.

    Recently opened files are shown in the \uicontrol{File} menu.
    The example can only load one file at a time.

    \section1 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

    \snippet demos/documentviewer/plugins/txtviewer/txtviewer.h classDefinition

    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.

    No functionality is implemented to save and restore settings.
    The \c supportsOverview function always returns \c false, which tells the main
    application that no window for thumbnail navigation has to be displayed.

    \section1 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.

    You might wonder why we don't include these headers in \c mainwindow.h and
    be done with it. The reason is that including multiple large headers from another
    header file can rapidly degrade performance. Here, it wouldn't do any harm,
    but it's still generally a good idea to include only the header files that are
    strictly necessary from another header file.

    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 AbstractViwer.
    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' 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.
*/