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

/*!
    \example common/graphprinting
    \meta tags {Graphs, GraphsView, LineSeries, Bars3D}
    \examplecategory {Data Visualization}
    \title Graph Printing
    \ingroup qtgraphs_qmlexamples
    \ingroup qtgraphs_qmlexamples_3D
    \brief Printing a 2D or 3D graph.

    The \e {Graph Printing} example demonstrates how to print or export to PDF
    2D and 3D graphs.

    \image graphprinting-example.webp
           {2D line graph with PDF export and print controls}

    \include examples-run.qdocinc

    \section1 GraphPrinter class

    The printing functionality is implemented in the \c GraphPrinter class. The
    class exposes these functions:

    \list
        \li The \c generatePDF function, which works as follows.
            \list
                \li Sets up the output PDF file.

                    The function instantiates \l QPdfWriter with a "graph.pdf" file
                    pointed in the specified folder. The function also specifies the
                    options for the exported PDF file: \e title, \e resolution, \e {page size},
                    and \e margins.

                    \snippet common/graphprinting/graphprinter.cpp 0
                \li Sets up image processing.

                    The static helper \c paintImage function draws the image
                    captured from QML onto an instance of the
                    \l QPaintDevice class:


                    The function creates a \l QPainter referring to the device.

                    To ensure the graph is printed correctly, it is scaled to the
                    painter's viewport size with the original aspect ratio.

                    The painter's rendering hint is set to lossless image rendering.
                    After this, the function draws the image to the PDF file.

                    \snippet common/graphprinting/graphprinter.cpp 1

                    Since \l QPdfWriter and \l QPrinter inherit \l QPaintDevice,
                    the helper function can be called from the \c generatePDF function
                    and the \c print function explained below.
            \endlist

            The function returns a status message to be displayed in the application's
            message dialog, including the full path to the exported file.
        \li The \c getPrinters function returns a list of available printers.

            \snippet common/graphprinting/graphprinter.cpp 3
        \li The \c print function, which works like the \c generatePDF function,
            but creates a \l QPainter referring a \l QPrinter instance:

            \snippet common/graphprinting/graphprinter.cpp 2

            The function returns a status message to be displayed in the application's
            message dialog.
    \endlist

    \section1 Application setup

    In addition to the application setup code, the \c {main.cpp} file contains
    code that creates a new instance of the \l {GraphPrinter class} and makes
    it reachable from the QML code.

    \snippet common/graphprinting/main.cpp 0

    \section1 Setting up the layout and image capture

    The 2D and 3D graphs are laid out in a Stacklayout. Users can navigate it
    with a TabBar.

    \snippet common/graphprinting/qml/graphprinting/Main.qml 0

    The FileDialog component is used to choose the PDF file to be written.
    This component has no visual representation in the
    application layout, but its API is accessible from the current QML file.

    \snippet common/graphprinting/qml/graphprinting/Main.qml 1.1

    A custom printing dialog is created for selecting a printer, and is triggered
    with the \inlineimage common/graphprinting/qml/graphprinting/print.svg {Printer icon} button.
    The Dialog retrieves the list of available printers and displays them in a
    list view.

    \snippet common/graphprinting/qml/graphprinting/Main.qml 2.1
    \dots 0
    \snippet common/graphprinting/qml/graphprinting/Main.qml 2.2

    The \inlineimage common/graphprinting/qml/graphprinting/documents.svg {Document icon} button triggers the
    PDF export.

    When either PDF export or printing is triggered, the following code is executed:

    \list
        \li Capture an image using the \c grabToImage method.
            The current graph is the Stacklayout's item at the current index.
        \li In the \c grabToImage parameters, we specify the callback as the
            \c generatePDF or \c print function in the \c GraphPrinter class.

            PDF export:
            \snippet common/graphprinting/qml/graphprinting/Main.qml 3.1

            Print:
            \snippet common/graphprinting/qml/graphprinting/Main.qml 3.2

            For the size, the code makes the image render at 4x the actual
            resolution. For 3D graphs, the item must also be expanded
            for the duration of printing:

            \snippet common/graphprinting/qml/graphprinting/Main.qml 3.3
    \endlist
*/
