Docs: Update Qt Quick for Android Example documentation

-Fixed the path to the example.

-Reduced the example image resolution to improve the layout.

-Explained that the QML is defined in main.qml and second.qml.

-Include XML layout snippets and info.

-Added the imports for the qml types to the snippets and explained them.

-Added a link to the Qt Academy course.

Fixes: QTBUG-138219
Pick-to: 6.10
Change-Id: I9d59bc1b5b63a3d6a8230cdd83b99efd886744d5
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>

examples/platforms/android/doc/src/qtquick_for_android_studio_projects.qdoc

@@ -8,20 +8,81 @@
     to embed Qt Quick content in Android projects.
     \ingroup qtquickexamples
 
+    \image portrait_java.png
+
     \include running-qtquick-for-android-examples.qdocinc
 
     \section1 Overview
 
-    This example contains a QML project that you can import into Android Studio
+    This example contains a QML project you can import into Android Studio
-    with the \l {Qt Tools for Android Studio} plugin
+    with the \l {Qt Tools for Android Studio} plugin. There are Java and Kotlin
-    and Java and Kotlin projects that use the QML project as a View by
+    projects that use the QML project as a View by utilizing the
-    utilizing the \l {Qt Quick View Android Class}{QtQuickView} API.
+    \l {Qt Quick View Android Class}{QtQuickView} API.
 
-    For more information on how QML works, see the \l {Qt Qml}. This
+    For more information on how QML works, see \l {Qt Qml}. This
-    documentation will focus on how a QML component is embedded into
+    documentation focuses on how a QML component is embedded into
-    Java- and Kotlin-based Android applications.
+    Android Applications using Java or Kotlin.
 
-    \image portrait_java.png
+    \include qtquick-for-android-main().qdocinc
+
+    \section1 Setting up the layout
+
+    For both Java and Kotlin projects, we need to set up the layout for the \l{QtQuickView}s in
+    \c app/src/main/res/layout/activity_main.xml.
+
+    Inside the \c LinearLayout, we set up two FrameLayouts for each \l QtQuickView.
+
+    \badcode
+     <FrameLayout
+        android:id="@+id/firstQmlFrame"
+        android:layout_width="match_parent"
+        android:layout_height="0dp"
+        android:layout_weight="1">
+    </FrameLayout>
+
+    <FrameLayout
+        android:id="@+id/secondQmlFrame"
+        android:layout_width="match_parent"
+        android:layout_height="0dp"
+        android:layout_weight="1">
+    </FrameLayout>
+
+    \endcode
+
+    The \c id is what is referred to in the Kotlin or Java-coded MainActivity.
+
+    \section1 Importing automatically generated QML Type Java classes
+
+    The Java classes for our QML types are generated when the Qt Quick project is
+    built. These must be imported before we can use them in our MainActivity.
+
+    \if defined(onlinedocs)
+        \tab {import}{tab-java}{Java}{checked}
+        \tab {import}{tab-kotlin}{Kotlin}{}
+        \tabcontent {tab-java}
+    \else
+        For a Java-based project:
+    \endif
+
+    \snippet android/qtquickview_java/app/src/main/java/com/example/qtquickview_java/MainActivity.java qmlTypeImports
+
+    \if defined(onlinedocs)
+        \endtabcontent
+        \tabcontent {tab-kotlin}
+    \else
+        For a Kotlin-based project:
+    \endif
+
+    \snippet android/qtquickview_kotlin/app/src/main/java/com/example/qtquickview_kotlin/MainActivity.kt qmlTypeImports
+
+    \if defined(onlinedocs)
+        \endtabcontent
+    \endif
+
+    \note See the \l{QT_ANDROID_GENERATE_JAVA_QTQUICKVIEW_CONTENTS} CMake
+    variable for further information on Java code generation of QML components.
+
+    \section1 MainActivity's onCreate() method
 
     First, we look at the \c MainActivity's onCreate() method of the Java
     and Kotlin projects.
@@ -85,7 +146,6 @@
     The \c QtQuickView instances are added to the Android layout with appropriate layout
     parameters.
 
-
     \if defined(onlinedocs)
         \tab {layoutParams}{tab-java}{Java}{checked}
         \tab {layoutParams}{tab-kotlin}{Kotlin}{}
@@ -333,14 +393,14 @@
 
     The \c QtQuickViewContent class offers a
     \c connectSignalListener() and \c disconnectSignalListener() methods which
-    are used to connect and disconnect signal listener between signals that are
+    are used to connect and disconnect signal listeners between signals that are
     declared in the QML component root object.
     The \c QtQuickViewContent.connectSignalListener() returns a unique signal
-    listener id which we store and use later to identify and disconnect the
+    listener ID, which we store and use later to identify and disconnect the
     listener.
 
     Here we connect a signal listener to the \c onClicked()  signal of the
-    QML component.
+    QML component:
 
     \if defined(onlinedocs)
         \tab {signal_listener}{tab-java}{Java}{checked}
@@ -365,15 +425,14 @@
         \endtabcontent
     \endif
 
-    The \c onClicked() signal is emitted every time the button on the
+    The \c onClicked() signal is emitted every time the button on the QML component is clicked.
-    QML component is clicked.
+    This listener then receives that signal, and the background
-    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 \c Colors.java class.
 
     Next, the signal listener is disconnected using the
     \c QtQuickViewContent.disconnectSignalListener()
-    method by giving it the unique signal listener id.
+    method by giving it the unique signal listener ID.
 
     \if defined(onlinedocs)
         \tab {qml_signal_listener}{tab-java}{Java}{checked}
@@ -397,4 +456,8 @@
     \if defined(onlinedocs)
         \endtabcontent
     \endif
+
+     If you haven't already, check out the
+     \l{Qt Academy: Embedding Qt Quick 3D Content in an Android App} course that introduces the
+     tools and APIs referenced in this example.
 */

examples/platforms/android/qtquickview_java/app/src/main/java/com/example/qtquickview_java/MainActivity.java

@@ -15,8 +15,10 @@ import android.widget.TextView;
 import org.qtproject.qt.android.QtQmlStatus;
 import org.qtproject.qt.android.QtQmlStatusChangeListener;
 import org.qtproject.qt.android.QtQuickView;
+//! [qmlTypeImports]
 import org.qtproject.example.qtquickview.QmlModule.Main;
 import org.qtproject.example.qtquickview.QmlModule.Second;
+//! [qmlTypeImports]
 import org.qtproject.qt.android.QtQuickViewContent;
 import java.util.HashMap;
 import java.util.Map;

examples/platforms/android/qtquickview_kotlin/app/src/main/java/com/example/qtquickview_kotlin/MainActivity.kt

@@ -10,8 +10,10 @@ import android.widget.CompoundButton
 import android.widget.FrameLayout
 import androidx.appcompat.app.AppCompatActivity
 import com.example.qtquickview_kotlin.databinding.ActivityMainBinding
+//! [qmlTypeImports]
 import org.qtproject.example.qtquickview.QmlModule.Main
 import org.qtproject.example.qtquickview.QmlModule.Second
+//! [qmlTypeImports]
 import org.qtproject.qt.android.QtQmlStatus
 import org.qtproject.qt.android.QtQmlStatusChangeListener
 import org.qtproject.qt.android.QtQuickView

src/quick/doc/src/android/qtquick-for-android-main().qdocinc

@@ -0,0 +1,38 @@
+\section1 Changes in \c main() are required by Qt Quick for Android APIs
+
+    A typical Qt Quick application's main.cpp appears like this:
+    \code
+    #include <QGuiApplication>
+    #include <QQmlApplicationEngine>
+
+    int main(int argc, char *argv[])
+    {
+        QGuiApplication app(argc, argv);
+
+        QQmlApplicationEngine engine;
+        QObject::connect(
+            &engine,
+            &QQmlApplicationEngine::objectCreationFailed,
+            &app,
+            []() { QCoreApplication::exit(-1); },
+            Qt::QueuedConnection);
+        engine.loadFromModule("MyQtQuickProject", "Main");
+
+        return app.exec();
+    }
+    \endcode
+
+    In \c main() we don't need to create a QML Engine or load any QML
+    that will be handled later by the Qt Quick View APIs.
+    All that we need is in \c main() is:
+
+    \code
+    #include <QGuiApplication>
+
+    int main(int argc, char *argv[])
+    {
+        QGuiApplication app(argc, argv);
+
+        return app.exec();
+    }
+    \endcode

src/quick/doc/src/android/qtquick-for-android.qdoc

@@ -64,7 +64,8 @@
     app to embed QML.
     //! TODO: Update links to Java API docs when published
     \list
-        \li \l{Qt Quick View Android Class}
+        \li \l{QtQuickView}
+        \li \l{QtQuickViewContent}
         \li \l{QtAbstractItemModel Android Class}
         \li \l{QtAbstractListModel Android Class}
         \li \l{interface QtQmlStatusChangeListener} (which uses the QtQmlStatus enum)
@@ -82,6 +83,8 @@
         \li \l{Using QtAbstractItemModel in Android Studio Projects}
     \endlist
 
+    \include qtquick-for-android-main().qdocinc
+
     \section2 Running Qt Quick for Android examples
 
     \include running-qtquick-for-android-examples.qdocinc

src/quick/doc/src/android/running-qtquick-for-android-examples.qdocinc

@@ -1,9 +1,13 @@
+    \section1 Qt Quick for Android API examples are Android Studio Projects
 
     The Qt Quick for Android API examples are provided as Android Studio projects.
     The project folders are found in your Qt install location.
 
     For example, under the default Windows install path, they are found here:
-    \badcode \QtVersion
+
-        C:\Qt\Examples\Qt-/1\platforms\android
+    \badcode
+        C:\Qt\Examples\Qt-<patch-release-number>\platforms\android\<example-name>
     \endcode
 
+    These projects are already configured to use a version of the
+    \l{Qt Gradle Plugin} compatible with this Qt version.

src/quick/doc/src/qtquick-android.qdoc

@@ -6,12 +6,14 @@
     \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}.
+    \note Classes under this module require \l{Qt for Android}.
 
     \annotatedlist qt_android_classes
 
     \note For a complete list of Android Java classes, see \l{Android Classes}.
 
+    \include running-qtquick-for-android-examples.qdocinc
+
     Examples:
     \list
         \li \l{Qt Quick for Android Studio Projects}

src/quick/doc/src/qtquick-external-resources.qdoc

@@ -0,0 +1,17 @@
+// Copyright (C) 2025 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \externalpage https://www.qt.io/academy/course-catalog#embedding-qt-quick-3d-content-in-an-android-app
+    \title Qt Academy: Embedding Qt Quick 3D Content in an Android App
+*/
+
+/*!
+    \externalpage https://code.qt.io/cgit/qt/qtdeclarative.git/tree/src/quick/platform/android/jar/src/org/qtproject/qt/android/QtQuickView.java?h=6.10
+    \title QtQuickView
+*/
+
+/*!
+    \externalpage https://code.qt.io/cgit/qt/qtdeclarative.git/tree/src/quick/platform/android/jar/src/org/qtproject/qt/android/QtQuickViewContent.java?h=6.10
+    \title QtQuickViewContent
+*/