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

/*!
    \example flatstyle
    \keyword Qt Quick Controls - Flat Style
    \title Qt Quick Controls - Flat Style
    \keyword Qt Quick Controls 2 - Flat Style
    \ingroup qtquickcontrols-examples
    \examplecategory {Graphics}
    \brief A QML app using Qt Quick Controls and QML modules
    with customized controls.

    \e Flat Style shows how to integrate customized controls into Qt Quick Designer.
    The example uses a pure QML module to define constants in a singleton. For the
    declarative parts of the UI, \c .ui.qml files are used. These can be edited
    visually in Qt Quick Designer.

    \image qtquickcontrols-flatstyle.png
       {Application with customized flat style controls and theme options}

    \section1 QML Module for Theming

    The example contains a QML module called \c Theme, which consists of a QML
    singleton with the same name.
    To ensure the module is found by QML, we add the import directory to the import
    paths of the engine in \c main.cpp.

    \code
    ...
    engine.addImportPath(":/imports");
    ...
    \endcode

    To ensure the code model and Qt Quick Designer can find the module, we add the following
    line to \e flatstyle.pro.

    \code
    QML_IMPORT_PATH = $$PWD/imports
    \endcode

    All colors, font parameters, and size constants that are used in this example
    are defined as properties in the singleton called \e Theme.qml.
    Usually such attribute values are defined as constants as they are not suppose to change at run time.
    In this example, we allow the user to change some attributes like the main color, the size parameter,
    and some font parameters while the application is running.

    Defining these attribute values in a singleton makes it easy to maintain and change them.
    This pattern makes it easy to implement theming.

    \section1 QML Module for Custom Controls

    The \c Flat module contains a style for a couple of controls that implement a custom look and feel.
    This style is set as the style for the application in \c qtquickcontrols2.conf.

    The example uses the states of a Qt Quick Item to implement the different states of a control.
    This has the advantage that we can define the custom look in Qt Quick Designer and we can easily
    verify the different states of a control.
    To edit the indicator of a switch in Qt Quick Designer we can open Switch.qml and then enter the implementation
    of the indicator called \c switchHandle using the combo box on the top next to the combo box for the open documents.

    \image qtquickcontrols-flatstyle-creator.png
       {Qt Quick Designer showing switch handle states and properties}

    The application itself is just a simple form that allows the user to adjust a couple of parameters of the custom controls.
    The user can choose another main color, set the font to bold or underline, and increase the size of the controls by
    toggling a switch.

    \e MainForm.ui.qml is just the pure declarative definition of the form, while \e flatstyle.qml instantiates the form
    and implements the logic.

    \include examples-run.qdocinc
*/
