Android: Add documentation for QtQuickView class

Added Android classes page, since this is a Java class,
qdoc doesn't know how to generate its docs automatically,
so a custom layout is created manually here. Updated the qdoconf file to
include the QtQuickView source folder.

Task-number: QTBUG-120718
Change-Id: I5e4bc112536b63fae1c79d0035f2d742d0c7c2da
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
(cherry picked from commit 7318e939c57c5904517ff7f2563285d7a7fddd67)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 289112fc1a5da91da456721839f950cba371b32b)

5 files changed, 269 insertions, 1 deletions

diff --git a/src/qml/doc/src/external-resources.qdoc b/src/qml/doc/src/external-resources.qdoc
index 123b564f92..091df193a5 100644
--- a/src/qml/doc/src/external-resources.qdoc
+++ b/src/qml/doc/src/external-resources.qdoc
@@ -57,3 +57,15 @@
     \externalpage https://cmake.org/cmake/help/latest/command/install.html#files
     \title install(FILES)
 */
+/*!
+    \externalpage https://developer.android.com/reference/android/view/View
+    \title Android: View
+*/
+/*!
+    \externalpage https://developer.android.com/reference/java/security/InvalidParameterException
+    \title Android: InvalidParameterException
+*/
+/*!
+    \externalpage https://developer.android.com/reference/java/lang/ClassCastException
+    \title Android: ClassCastException
+*/
diff --git a/src/quick/doc/qtquick.qdocconf b/src/quick/doc/qtquick.qdocconf
index dd56e6f59a..e9fbc1af5c 100644
--- a/src/quick/doc/qtquick.qdocconf
+++ b/src/quick/doc/qtquick.qdocconf
@@ -64,7 +64,8 @@ depends += \
     ../../quickwidgets \
     ../../qmllocalstorage \
     ../../quicklayouts \
-    ../../labs
+    ../../labs \
+    ../../quick/jar/org/qtproject/qt/android
 
 # both have their own documentation project
 excludedirs += \
diff --git a/src/quick/doc/src/qtquick-android.qdoc b/src/quick/doc/src/qtquick-android.qdoc
new file mode 100644
index 0000000000..b21378565d
--- /dev/null
+++ b/src/quick/doc/src/qtquick-android.qdoc
@@ -0,0 +1,14 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qtquick-android-classes.html
+\title Qt Quick Android Classes
+\summary The Qt Quick module provides classes for embedding Qt Quick in Android Applications.
+
+  \note Classes under this module requires \l{Qt for Android}.
+
+  \annotatedlist qt_android_classes
+
+  For more information on Qt Quick module, see the \l{Qt Quick} module documentation.
+*/
diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc
index e04751ca4c..f9aa4a3256 100644
--- a/src/quick/doc/src/qtquick.qdoc
+++ b/src/quick/doc/src/qtquick.qdoc
@@ -137,6 +137,8 @@ To find out more about using the QML language, see the \l{Qt Qml} module documen
             \li \l{Qt Quick Shapes QML Types}{Shapes}
                    - provides types for rendering vector shapes in a Qt Quick scene.
         \endlist
+    \li \l {Qt Quick Android Classes}
+            - provides classes for using QML with Java/Kotlin Android APIs.
 \endlist
 
 \section1 Licenses and Attributions
diff --git a/src/quick/jar/org/qtproject/qt/android/QtQuickView.qdoc b/src/quick/jar/org/qtproject/qt/android/QtQuickView.qdoc
new file mode 100644
index 0000000000..833964cdaf
--- /dev/null
+++ b/src/quick/jar/org/qtproject/qt/android/QtQuickView.qdoc
@@ -0,0 +1,239 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+
+/*!
+    \page qtquickview-android-class.html
+    \title Qt Quick View Android Class
+    \ingroup qt_android_classes
+    \brief Allows you to add QML content to your Android app as a View.
+    \techpreview
+    \since 6.7
+
+    The QtQuickView class lets you easily add QML content to your Android app as
+    a \l {Android: View}{View}.
+
+    \target QtQuickView
+    \table
+    \row
+        \li Class:
+        \li QtQuickView
+    \row
+        \li Package Name:
+        \li org.qtproject.qt.android
+    \row
+        \li Extends:
+        \li org.qtproject.qt.android.QtView
+
+            – org.qtproject.qt.android.QtLayout
+
+            –– android.view.ViewGroup
+    \endtable
+
+    \section1 Detailed description
+
+    The QtQuickView class lets you easily add QML content to your Android app as
+    a \l {Android: View}{View}. \c QtQuickView instantiates a \l QQuickView with
+    a given QML component source (a local or network file) and embeds it to itself.
+    You can add it to your Android app's layout as with any other View. \c QtQuickView
+    is a good choice when you want to extend your non-Qt Android app with QML content but
+    do not want to make the entire app using the Qt framework. It brings the power
+    of Qt Quick into your Android app, making it possible to use various Qt Quick
+    APIs in Android apps.
+
+    A typical use of the class:
+
+    \code
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_main);
+        ...
+
+        QtQuickView qmlView = new QtQuickView(this, "qrc:/qt/qml/target/main.qml", "target");
+        qmlView.setStatusChangeListener(status -> {
+            Log.i(TAG, "QML loading status changed to " + status);
+        });
+
+        // Add QML to your layout
+        layout.addView(qmlView, params);
+        ...
+    }
+    \endcode
+
+    For a more detailed example, see \l {QML in Java-Based Android Projects}.
+
+    \section1 Constructors
+
+    \section2 public QtQuickView(Context parent, String qmlUri, String appName)
+
+    Creates a QtQuickView to load and render a QML component. Instantiating a
+    QtQuickView will load the Qt libraries, including the app library specified
+    by \e appName. Then, it creates a QQuickView that loads the QML source specified
+    by \e qmlUri.
+
+    \section3 Parameters
+
+    \list
+        \li \b context: the parent Context.
+        \li \b qmlUri: the URI of the main QML file.
+        \li \b appName: the name of the Qt app library to load and start.
+            This corresponds to the target name set in the Qt app's CMakeLists.txt.
+    \endlist
+
+    \section3 Throws
+
+    Throws a \l {Android: InvalidParameterException}{InvalidParameterException} if
+    a parameter is invalid.
+
+    \section2 public QtQuickView(Context context, String qmlUri, String appName, String[] qmlImportPaths)
+
+    Creates a QtQuickView to load and view a QML component. Instantiating a
+    QtQuickView will load the Qt libraries, including the app library specified
+    by \e appName. Then, it creates a QQuickView that loads the QML source specified
+    by \e qmlUri. This overload accepts an array of strings \e qmlImportPaths in the
+    case where the QML application should load QML modules from custom paths.
+
+    \section3 Parameters
+
+    \list
+        \li \b context: the parent Context.
+        \li \b qmlUri: the URI of the main QML file.
+        \li \b appName: the name of the Qt app library to load and start.
+            This corresponds to the target name set in the Qt app's CMakeLists.txt.
+        \li \b qmlImportPaths: an array of strings for additional import paths to
+            be passed to.
+    \endlist
+
+    \section3 Throws
+
+    Throws a \l {Android: InvalidParameterException}{InvalidParameterException} if
+    a parameter is invalid.
+
+    \section1 Interfaces
+
+    \section2 public interface SignalListener<T>
+    \target SignalListener
+
+    Invoked on the Android UI thread when the signal has been emitted.
+
+    \section3 Parameters
+
+    \list
+        \li \b signalName: literal signal name
+        \li \b value: the value delivered by the signal or null if the signal is
+         without a parameter.
+    \endlist
+
+    \section2 public interface StatusChangeListener
+    \target StatusChangeListener
+
+    Invoked on the Android UI thread when the QML component status has changed.
+
+    \section3 Parameters
+
+    \list
+        \li \b status: The current status.
+    \endlist
+
+    \section1 Fields
+
+    \section2 Status values
+    \target Status values
+
+    The status can be \e STATUS_NULL, \e STATUS_READY, \e STATUS_LOADING or
+    \e STATUS_ERROR. For more information, see \l {QQuickView::Status}.
+
+    \section1 Methods
+
+    \section2 public void setProperty(String propertyName, Object value)
+    \target setProperty()
+
+    Sets the value of an existing property on the QML root object. The supported
+    types are \c Integer, \c Double, \c Float, \c Boolean, and \c String. These
+    types get converted to their corresponding QML types int, double/float, bool,
+    and string. This function does not add properties to the QML root object if
+    they do not exist.
+
+    \section3 Parameters
+    \list
+        \li \b propertyName: the name of the existing root object property to set its value
+        \li \b value: the value of the property
+    \endlist
+
+    \section2 public <T extends Object> T getProperty(String propertyName)
+    \target getProperty()
+
+    Gets the value of an existing property of the QML root object. The supported
+    return types are \e Integer, \e Double, \e Float, \e Boolean, and \e String.
+    These types get converted from their corresponding QML types int, double/float,
+    bool, and string.
+
+    \section3 Parameters
+    \list
+        \li \b propertyName: the name of the existing root object property.
+    \endlist
+
+    \section3 Returns
+
+    If the property does not exist or the status of the QML component is
+    anything other than \l {Status values}{STATUS_READY}, this function will return null.
+
+    \section3 Throws
+
+    Throws a \l {Android: ClassCastException}{ClassCastException} if type casting fails.
+
+    \section2 public <T> int addSignalListener(String signalName, Class<T> argType, SignalListener<T> listener)
+    \target  addSignalListener()
+
+    Associates a \l {SignalListener} with a signal of the QML root object.
+
+    \section3 Parameters
+    \list
+        \li \b signalName: the name of the root object signal.
+        \li \b argType: the Class type of the signal argument.
+        \li \b listener: an instance of the SignalListener interface.
+    \endlist
+
+    \section3 Returns
+
+    A \c {Connection ID} between signal and listener or the existing connection
+    ID if there is an existing connection between the same signal and listener.
+    Returns a negative value if the signal does not exist on the QML root object.
+
+    \section2 public boolean removeSignalListener(int signalListenerId)
+
+    Stops a \l {SignalListener} with a given id obtained from \l addSignalListener()
+    call, from listening to a signal.
+
+    \section3 Parameters
+    \list
+        \li \b signalListenerId: the connection ID.
+    \endlist
+
+    \section3 Returns
+    \e True if the connection ID is valid and has been successfully removed,
+    otherwise returns false.
+
+    \section2 public int getStatus()
+    \target getStatus()
+
+    Gets the \l {Status values}{status} of the QML component.
+
+    \section3 Returns
+
+    \e STATUS_READY when the QML is ready. Invoking methods that operate on the QML
+        root object, such as \l {setProperty()}, \l {getProperty()}, and
+        \l {addSignalListener()}, would succeed \b only if the current status is
+        \c STATUS_READY. It can also return other \l {Status values}{status} values
+        representing the status of the underlying QQuickView instance.
+
+    \section2 public void setStatusChangeListener(StatusChangeListener listener)
+
+    Sets a \l {StatusChangeListener} to listen to status changes.
+
+    \section3 Parameters
+
+    \list
+        \li \b listener: an instance of a \l {StatusChangeListener} interface.
+    \endlist
+*/