Adds documentation for the qml_in_kotlin_based_android_projects example
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>
This commit is contained in:
Konsta Alajärvi
parent
68b2bab607
commit
947986009d
|
|
@ -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.
|
||||
|
|
@ -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]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -69,3 +69,8 @@
|
|||
\externalpage https://developer.android.com/reference/java/lang/ClassCastException
|
||||
\title Android: ClassCastException
|
||||
*/
|
||||
/*!
|
||||
\externalpage https://developer.android.com/topic/libraries/view-binding
|
||||
\title Android: View binding
|
||||
*/
|
||||
|
||||
|
|
|
|||
|
|
@ -97,7 +97,8 @@ imagedirs += images
|
|||
|
||||
excludefiles += ../util/qquickpropertychanges_p.h
|
||||
examples.fileextensions += "*.qm" \
|
||||
"*.java"
|
||||
"*.java" \
|
||||
"*.kt"
|
||||
|
||||
manifestmeta.thumbnail.names += "QtQuick/QML Dynamic View Ordering Tutorial*"
|
||||
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@
|
|||
}
|
||||
\endcode
|
||||
|
||||
For a more detailed example, see \l {QML in Java-Based Android Projects}.
|
||||
For a more detailed example, see \l {QML in Android Studio Projects}.
|
||||
|
||||
\section1 Constructors
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue