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

/*!
    \page qml-in-android-studio-projects-example.html
    \title QML in Android Studio Projects
    \brief Uses a \l {Qt Quick View Android Class}{QtQuickView}
    to embed a QML component into Android projects.
    \ingroup qtquickexamples

    \section1 Overview

    This example contains a QML project that you can import into Android Studio
    with the \l {Qt Tools for Android Studio} plugin
    and Java and Kotlin projects that utilize the
    \l {Qt Quick View Android Class}{QtQuickView} API.

    For more information on how QML works, see the \l {Qt Qml}. This
    documentation will focus on how a QML component is embedded into
    Java- and Kotlin-based Android applications.

    \image portrait_java.png

    First, we look at the \c MainActivity's onCreate() method of the Java
    and Kotlin projects.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java onCreate

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt onCreate

    \note in the Kotlin project we use \l {Android: View binding}{View binding}
    to access the UI components of the application:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt binding

    Inside the \c onCreate() method, an instance of
    \l {Qt Quick View Android Class}{QtQuickView} named
    \c m_qmlView is created by giving it the Java/Kotlin application Context,
    URI of the QML project's \c main.qml file and the name of the QML project's
    main library as parameters.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java m_qmlView

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt m_qmlView

    \c m_qmlView is then added to Android FrameLayout ViewGroup with
    appropriate layout parameters.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java layoutParams

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt layoutParams

    \section1 Interacting with the QML component

    To interact with the embedded QML component we first need to implement
    the \l {Qt Quick View Android Class}{QtQuickView} public interface
    \l [Qt Quick View Android Class]{public interface StatusChangeListener}{StatusChangeListener}.

    For a Java-based project:

    \code
    public class MainActivity extends AppCompatActivity implements
    QtQuickView.StatusChangeListener{
        ...
    }
    \endcode

    IFor a Kotlin-based project:

    \code
    class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener{
        ...
    }
    \endcode

    Then, define an override for the
    \l [Qt Quick View Android Class]{public interface StatusChangeListener}{StatusChangeListener}
    callback function \c onStatusChanged().

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java onStatusChanged

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt onStatusChanged

    Then, set that listener to listen for status changes of \c m_qmlView
    with the \l [Qt Quick View Android Class]{public void setStatusChangeListener(StatusChangeListener listener)}{setStatusChangeListener()}.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java setStatusChangeListener

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt setStatusChangeListener

    The overridden callback function \c onStatusChanged() receives
    \c StatusChanged() signal containing the current
    \l [Qt Quick View Android Class]{Status values}{Status value} of the
    \c m_qmlView. If this
    \l [Qt Quick View Android Class]{Status values}{Status value}
    is confirmed to be
    \l [Qt Quick View Android Class]{Status values}{STATUS_READY},
    we can start interacting with the QML view.

    \section1 Getting and setting QML view property values

    Getting and setting QML view property values happens through the
    \l [Qt Quick View Android Class]{public <T extends Object> T getProperty(String propertyName)}{QtQuickView.getProperty()}
    and \l [Qt Quick View Android Class]{public void setProperty(String propertyName, Object value)}{QtQuickView.setProperty()}
    methods.

    The root object of the QML component's background color is set when a click
    event of an Android button occurs.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java onClickListener

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt onClickListener

    With the \l [Qt Quick View Android Class]{public void setProperty(StringpropertyName, Object value)}{QtQuickView.setProperty()}
    method we set the "colorStringFormat" property value to a random color
    value that is fetched from the project's \c Colors.java class.

    The \l [Qt Quick View Android Class]{public <T extends Object> T getProperty (String propertyName)}{QtQuickView.getProperty()}{QtQuickView.getProperty()}
    method is used here to fetch the current background color of the root
    object of the QML component and then show it to the user on the Android
    side of the application.

    \section1 Signal listeners

    \l {Qt Quick View Android Class}{QtQuickView} class offers a
    connectSignalListener() and disconnectSignalListener() methods which are
    used to connect and disconnect a signal listener to a signal that is
    declared in the QML component root object.

    Here we connect a signal listener to the \c onClicked()  signal of the
    QML component.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java qml signal listener

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt qml signal listener

    The \c onClicked() signal is emitted every time the button on the QML UI is
    clicked. That signal is then received by this listener and the background
    color of the layout holding the Android side of the application is set to
    a random color value fetched from the project's \c Colors.java class.

    The \l [Qt Quick View Android Class]{public <T> int addSignalListener(String signalName, Class<T> argType, SignalListener<T> listener)}{QtQuickView.connectSignalListener()}
    returns a unique signal listener id which we store and use later to
    identify and disconnect the listener.

    For a Java-based project:

    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java disconnect qml signal listener

    For a Kotlin-based project:

    \snippet android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt disconnect qml signal listener

    Here, the previously connected signal listener is disconnected using the
    \l [Qt Quick View Android Class]{public boolean removeSignalListener(int signalListenerId)}{QtQuickView.disconnectSignalListener()}
    method by giving it the unique signal listener id.

*/
