Adds documentation for the qml_in_kotlin_based_android_projects exampleHEADdev

Documented the qml_in_kotlin_based_android_projects example in the
same .qdoc file as the qml_in_java_based_projects example.

Added snippets tags to MainActivity.kt.

Added support for code snippets from .kt files in qtquick.qdocconf.

Fixes: QTBUG-123423
Pick-to: 6.7
Change-Id: I5ac4d231bf77a23b4083ca26712949d66c2483c1
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>

2 files changed, 112 insertions, 24 deletions

diff --git a/examples/platforms/android/doc/src/qml_in_java_based_android_project.qdoc b/examples/platforms/android/doc/src/qml_in_android_studio_projects.qdoc
index 177699d1e1..be1fa8b7a2 100644
--- a/examples/platforms/android/doc/src/qml_in_java_based_android_project.qdoc
+++ b/examples/platforms/android/doc/src/qml_in_android_studio_projects.qdoc
@@ -2,44 +2,73 @@
 // 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.
+    \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 project that utilize the \l {Qt Quick View Android Class}{QtQuickView} API.
+    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-based
-    Android applications.
+    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:
+    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
 
-    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:
+    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:
+    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 imported QML component we first need to implement
+    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}:
+    \l [Qt Quick View Android Class]{public interface StatusChangeListener}{StatusChangeListener}.
+
+    For a Java-based project:
 
     \code
     public class MainActivity extends AppCompatActivity implements
@@ -48,21 +77,44 @@
     }
     \endcode
 
-    Then, define an override for the \l [Qt Quick View Android Class]{public interface StatusChangeListener}{StatusChangeListener} callback
-    function \c onStatusChanged():
+    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()}:
+    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},
+    \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
@@ -73,11 +125,17 @@
     methods.
 
     The root object of the QML component's background color is set when a click
-    event of a Android button occurs:
+    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
 
-    With the \l [Qt Quick View Android Class]{public void setProperty(String propertyName, Object value)}{QtQuickView.setProperty()}
+    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.
 
@@ -94,10 +152,16 @@
     declared in the QML component root object.
 
     Here we connect a signal listener to the \c onClicked()  signal of the
-    QML component:
+    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
@@ -107,8 +171,14 @@
     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.
diff --git a/examples/platforms/android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt b/examples/platforms/android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt
index 339eea40fe..4ec1591709 100644
--- a/examples/platforms/android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt
+++ b/examples/platforms/android/qml_in_kotlin_based_android_project/app/src/main/java/com/example/qml_in_kotlin_based_android_project/MainActivity.kt
@@ -25,32 +25,43 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
         QtQuickView.STATUS_ERROR to "ERROR",
         QtQuickView.STATUS_NULL to "NULL"
     )
+    //! [onCreate]
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
+        //! [binding]
         m_binding = ActivityMainBinding.inflate(layoutInflater)
         val view = m_binding.root
         setContentView(view)
+        //! [binding]
 
         m_binding.signalSwitch.setOnClickListener { switchListener() }
 
+        //! [m_qmlView]
         m_qmlView = 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]
         val params: ViewGroup.LayoutParams = FrameLayout.LayoutParams(
             ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT
         )
         m_binding.qmlFrame.addView(m_qmlView, params)
+        //! [layoutParams]
 
         m_binding.changeColorButton.setOnClickListener { onClickListener() }
 
         // Check target device orientation on launch
         handleOrientationChanges()
     }
-
+    //! [onCreate]
     override fun onConfigurationChanged(newConfig: Configuration) {
         super.onConfigurationChanged(newConfig)
         handleOrientationChanges()
@@ -80,7 +91,7 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
         m_binding.qmlFrame.layoutParams = qmlFrameLayoutParams
         m_binding.kotlinLinear.layoutParams = linearLayoutParams
     }
-
+    //! [onClickListener]
     private fun onClickListener() {
         // Set the QML view root object property "colorStringFormat" value to
         // color from Colors.getColor()
@@ -94,6 +105,7 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
         // Display the QML View background color in a view
         m_binding.colorBox.setBackgroundColor(Color.parseColor(qmlBackgroundColor))
     }
+    //! [onClickListener]
 
     private fun switchListener() {
         // Disconnect QML button signal listener if switch is On using the saved signal listener Id
@@ -101,7 +113,9 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
         if (m_binding.signalSwitch.isChecked) {
             Log.v(TAG, "QML button onClicked signal listener disconnected")
             m_binding.switchText.setText(R.string.connect_qml_button_signal_listener)
+            //! [disconnect qml signal listener]
             m_qmlView!!.disconnectSignalListener(m_qmlButtonSignalListenerId)
+            //! [disconnect qml signal listener]
         } else {
             Log.v(TAG, "QML button onClicked signal listener connected")
             m_binding.switchText.setText(R.string.disconnect_qml_button_signal_listener)
@@ -115,6 +129,7 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
         }
     }
 
+    //! [onStatusChanged]
     override fun onStatusChanged(status: Int) {
         Log.v(TAG, "Status of QtQuickView: $status")
 
@@ -126,6 +141,7 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
 
         // 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_binding.signalSwitch.isChecked) {
             m_qmlButtonSignalListenerId = m_qmlView!!.connectSignalListener(
                 "onClicked", Any::class.java
@@ -134,5 +150,7 @@ class MainActivity : AppCompatActivity(), QtQuickView.StatusChangeListener {
                 m_binding.kotlinLinear.setBackgroundColor(Color.parseColor(m_colors.getColor()))
             }
         }
+        //! [qml signal listener]
     }
+    //! [onStatusChanged]
 }