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

/*!

    \example demos/qtjennydemo
    \title QtJenny: Generating C++ proxy classes to access Android APIs
    \ingroup qtquickdemos
    \brief Demo showcasing the use of QtJenny.
    \meta {tag} {demo,qtjenny,generator,android}
    \examplecategory {Application Examples}
    \examplecategory {Mobile}

    \borderedimage qtjennydemo_overview.png

    \section1 Overview

    This demo showcases the use of \l {Maven Central: QtJenny}{QtJenny} and
    uses it to generate C++ proxy classes to access Android APIs from C++ code.
    The generated C++ classes are used in the demo to perform actions
    such as adjusting the volume and brightness, activating and deactivating
    \l {Android: wake lock} {wake locks}, sending notifications and triggering
    vibrations. These actions are part of Android APIs that Qt doesn't
    implement.

    Generating C++ classes using QtJenny removes the need to write
    \l {Android: JNI} {JNI} code manually.

    \section1 How it works

    The demo contains two parts, a Qt project called \c qtjenny_consumer and
    an Android Studio project called \c qtjenny_generator. The \c qtjenny_consumer
    contains the application UI and the code using the generated C++ headers.
    The \c qtjenny_generator contains the class annotations and \c Gradle
    configurations for QtJenny.

    To launch the demo, you need to run the \c qtjenny_consumer project.
    During the \c CMake configuration of \c qtjenny_consumer the code
    generation is triggered automatically by a call to execute a \c gradlew
    task in the \c qtjenny_generator project directory.

    \snippet demos/qtjennydemo/CMakeLists.txt 0

    \section2 Generating the C++ headers

    Generation of the C++ headers starts when \c qtjenny_generator is built,
    this triggers an annotation processor that processes the annotations in
    \c GenerateCppCode.kt.

    \snippet demos/qtjennydemo/qtjenny_generator/app/src/main/java/org/qtproject/qt/qtjenny_generator/GenerateCppCode.kt 1

    The annotation processor then generates the C++ headers in the
    \c qtjenny_output directory. Those C++ headers contain the needed JNI
    boilerplate code to access the Android APIs used in this demo.

    The app level \c build.gradle script in \c qtjenny_generator specifies the
    arguments for \l {Android: Kapt compiler plugin}{kapt} which QtJenny
    implements. These arguments are parsed in the QtJenny compiler and used
    in the generation process.

    \snippet demos/qtjennydemo/qtjenny_generator/app/build.gradle 2

    \section2 Using the generated C++ headers in the Qt Quick application

    The \c qtjenny_consumer is the Qt Quick Application that uses the C++ headers
    generated by the \c qtjenny_generator. We include the generated headers in
    \c backend.h file and use them in \c backend.cpp to access various Android
    APIs.

    The app's UI consists of one \c Main.qml file, which contain the following
    controls and actions.

    \section3 Wake locks

    You can activate and deactivate either full or partial wake locks, using
    \l {Switch} {Switches}. When checked they invoke a function in
    \c backend.cpp which activates the wake lock and set the wake lock status
    text.

    \snippet demos/qtjennydemo/Main.qml 3

    Setting partial wake lock uses the \c WakeLockProxy class that connects
    to \c PowerManager.WakeLock Android API. Setting full wake lock is done
    by using \c WindowProxy that connects to \c Window Android API.

    \section3 Vibrate

    You can trigger a vibration using the \c vibrate function in \c backend.cpp,
    that uses \c VibrationEffectProxy, \c VibratorManagerProxy and
    \c VibratorProxy classes to perform the vibration.

    \section3 Notifications

    Sending a notification is handled in the \c notify function in
    \c backend.cpp, with use of the \c NotificationManagerProxy class.

    The notification is already created during the \c Backend class
    initialization in \c createNotification function.

    \section3 Adjusting the brightness

    Adjsting brightness is handled in the \c adjustBrightness function in
    \c backend.cpp, with the use of \c IntentProxy, \c SettingsProxy,
    \c SystemProxy, \c ContextProxy, \c LayoutParamsProxy and
    \c WindowProxy classes.

    \section3 Adjusting the volume

    Adjusting volume is handled in the \c adjustVolume function in
    \c backend.cpp, with the use of \c GlobalProxy and \c AudioManagerProxy
    classes.
*/

