Adds documentation for the qml_in_java_based_android_projects example

Added a qdoc file to the top folder and edited the qtquick.qdocconf
file to include it as src and for snippets.

Task-number: QTBUG-122964
Change-Id: I581e369b0682804729a98288164492ac1c604194
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
(cherry picked from commit 0b594fb3ba2d6b8ac80ec6f09744866a2abe80df)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 139 insertions, 7 deletions

diff --git a/examples/platforms/android/doc/images/portrait_java.png b/examples/platforms/android/doc/images/portrait_java.png
new file mode 100644
index 0000000000..266f0a2709
--- /dev/null
+++ b/examples/platforms/android/doc/images/portrait_java.png
diff --git a/examples/platforms/android/doc/src/qml_in_java_based_android_project.qdoc b/examples/platforms/android/doc/src/qml_in_java_based_android_project.qdoc
new file mode 100644
index 0000000000..177699d1e1
--- /dev/null
+++ b/examples/platforms/android/doc/src/qml_in_java_based_android_project.qdoc
@@ -0,0 +1,116 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page qml-in-java-based-android-projects-example.html
+    \title QML in Java-Based Android Projects
+    \brief Uses a \l {Qt Quick View Android Class}{QtQuickView} to embed a QML component into a Java-based Android project.
+    \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 project 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-based
+    Android applications.
+
+    \image portrait_java.png
+
+    First, we look at the \c MainActivity's onCreate() method:
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java onCreate
+
+    Where an instance of \l {Qt Quick View Android Class}{QtQuickView} named
+    \c m_qmlView is created by giving it the Java application Context,URI of
+    the QML project's \c main.qml file and the name of the QML project's main
+    library as parameters:
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java m_qmlView
+
+    \c m_qmlView is then added to Android FrameLayout ViewGroup with
+    appropriate layout parameters:
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java layoutParams
+
+    \section1 Interacting with the QML component
+
+    To interact with the imported 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}:
+
+    \code
+    public class MainActivity extends AppCompatActivity implements
+    QtQuickView.StatusChangeListener{
+        ...
+    }
+    \endcode
+
+    Then, define an override for the \l [Qt Quick View Android Class]{public interface StatusChangeListener}{StatusChangeListener} callback
+    function \c onStatusChanged():
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java 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()}:
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java 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 a Android button occurs:
+
+    \snippet android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java onClickListener
+
+    With the \l [Qt Quick View Android Class]{public void setProperty(String propertyName, 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:
+
+    \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
+
+    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.
+
+    \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
+
+    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.
+
+*/
diff --git a/examples/platforms/android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java b/examples/platforms/android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java
index a1d22ec67e..e7aee43c55 100644
--- a/examples/platforms/android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java
+++ b/examples/platforms/android/qml_in_java_based_android_project/app/src/main/java/com/example/qml_in_java_based_android_project/MainActivity.java
@@ -45,6 +45,7 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
     private SwitchCompat m_switch;
     private View m_box;
 
+    //! [onCreate]
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -58,24 +59,29 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
 
         m_switch = findViewById(R.id.switch1);
         m_switch.setOnClickListener(view -> switchListener());
-
+        //! [m_qmlView]
         m_qmlView = new QtQuickView(this, "qrc:/qt/qml/qml_in_android_view/main.qml",
                 "qml_in_android_view");
+        //! [m_qmlView]
+
         // Set status change listener for m_qmlView
         // listener implemented below in OnStatusChanged
+        //! [setStatusChangeListener]
         m_qmlView.setStatusChangeListener(this);
+        //! [setStatusChangeListener]
+        //! [layoutParams]
         ViewGroup.LayoutParams params = new FrameLayout.LayoutParams(
                 ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT);
         m_qmlFrameLayout = findViewById(R.id.qmlFrame);
         m_qmlFrameLayout.addView(m_qmlView, params);
-
+        //! [layoutParams]
         Button button = findViewById(R.id.button);
         button.setOnClickListener(view -> onClickListener());
 
         // Check target device orientation on launch
         handleOrientationChanges();
     }
-
+    //! [onCreate]
     @Override
     public void onConfigurationChanged(@NonNull Configuration newConfig) {
         super.onConfigurationChanged(newConfig);
@@ -107,6 +113,7 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
         m_androidControlsLayout.setLayoutParams(linearLayoutParams);
     }
 
+    //! [onStatusChanged]
     @Override
     public void onStatusChanged(int status) {
         Log.i(TAG, "Status of QtQuickView: " + status);
@@ -119,6 +126,7 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
 
         // Connect signal listener to "onClicked" signal from main.qml
         // addSignalListener returns int which can be used later to identify the listener
+        //! [qml signal listener]
         if (status == QtQuickView.STATUS_READY && !m_switch.isChecked()) {
             m_qmlButtonSignalListenerId = m_qmlView.connectSignalListener("onClicked", Object.class,
                     (String signal, Object o) -> {
@@ -127,8 +135,10 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
             });
 
         }
+        //! [qml signal listener]
     }
-
+    //! [onStatusChanged]
+    //! [onClickListener]
     public void onClickListener() {
         // Set the QML view root object property "colorStringFormat" value to
         // color from Colors.getColor()
@@ -142,6 +152,7 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
         // Display the QML View background color in a view
         m_box.setBackgroundColor(Color.parseColor(qmlBackgroundColor));
     }
+    //! [onClickListener]
 
     public void switchListener() {
         TextView text = findViewById(R.id.switchText);
@@ -150,7 +161,9 @@ public class MainActivity extends AppCompatActivity implements QtQuickView.Statu
         if (m_switch.isChecked()) {
             Log.i(TAG, "QML button onClicked signal listener disconnected");
             text.setText(R.string.connect_qml_button_signal_listener);
+            //! [disconnect qml signal listener]
             m_qmlView.disconnectSignalListener(m_qmlButtonSignalListenerId);
+            //! [disconnect qml signal listener]
         } else {
             Log.i(TAG, "QML button onClicked signal listener connected");
             text.setText(R.string.disconnect_qml_button_signal_listener);
diff --git a/src/quick/doc/qtquick.qdocconf b/src/quick/doc/qtquick.qdocconf
index e9fbc1af5c..10615d82d0 100644
--- a/src/quick/doc/qtquick.qdocconf
+++ b/src/quick/doc/qtquick.qdocconf
@@ -65,7 +65,8 @@ depends += \
     ../../qmllocalstorage \
     ../../quicklayouts \
     ../../labs \
-    ../../quick/jar/org/qtproject/qt/android
+    ../../quick/jar/org/qtproject/qt/android \
+    ../../../examples/platforms
 
 # both have their own documentation project
 excludedirs += \
@@ -77,7 +78,8 @@ exampledirs += \
     ../../qmlmodels/doc/snippets \
     ../../quickcontrols/doc/snippets \
     snippets \
-    ../../../tests/auto/quick/doc
+    ../../../tests/auto/quick/doc \
+    ../../../examples/platforms
 
 imagedirs += images
 
@@ -93,7 +95,8 @@ imagedirs += images
     ../../plugins
 
 excludefiles += ../util/qquickpropertychanges_p.h
-examples.fileextensions += "*.qm"
+examples.fileextensions += "*.qm" \
+                           "*.java"
 
 manifestmeta.thumbnail.names += "QtQuick/QML Dynamic View Ordering Tutorial*"