diff --git a/examples/platforms/android/doc/images/portrait_java.png b/examples/platforms/android/doc/images/portrait_java.png index 85c6522409..99ecfd52c2 100644 Binary files a/examples/platforms/android/doc/images/portrait_java.png and b/examples/platforms/android/doc/images/portrait_java.png differ diff --git a/examples/platforms/android/doc/images/qtabstractlistmodel_portrait.png b/examples/platforms/android/doc/images/qtabstractlistmodel_portrait.png index f4dd7de6e0..90d2cc2c93 100644 Binary files a/examples/platforms/android/doc/images/qtabstractlistmodel_portrait.png and b/examples/platforms/android/doc/images/qtabstractlistmodel_portrait.png differ diff --git a/examples/platforms/android/doc/src/qtquick_for_android_studio_projects.qdoc b/examples/platforms/android/doc/src/qtquick_for_android_studio_projects.qdoc index 742156c306..88e963ba79 100644 --- a/examples/platforms/android/doc/src/qtquick_for_android_studio_projects.qdoc +++ b/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 - with the \l {Qt Tools for Android Studio} plugin - and Java and Kotlin projects that use the QML project as a View by - utilizing the \l {Qt Quick View Android Class}{QtQuickView} API. + This example contains a QML project you can import into Android Studio + with the \l {Qt Tools for Android Studio} plugin. There are Java and Kotlin + projects that use the QML project as a View by utilizing 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- and Kotlin-based Android applications. + For more information on how QML works, see \l {Qt Qml}. This + documentation focuses on how a QML component is embedded into + 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 + + + + + + + \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 - QML component is clicked. - That signal is then received by this listener and the background + The \c onClicked() signal is emitted every time the button on the QML component is clicked. + This listener then receives that signal, 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. */ diff --git a/examples/platforms/android/qtquickview_java/app/src/main/java/com/example/qtquickview_java/MainActivity.java b/examples/platforms/android/qtquickview_java/app/src/main/java/com/example/qtquickview_java/MainActivity.java index 4c135beb15..dfa5ce4d5e 100644 --- a/examples/platforms/android/qtquickview_java/app/src/main/java/com/example/qtquickview_java/MainActivity.java +++ b/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; diff --git a/examples/platforms/android/qtquickview_kotlin/app/src/main/java/com/example/qtquickview_kotlin/MainActivity.kt b/examples/platforms/android/qtquickview_kotlin/app/src/main/java/com/example/qtquickview_kotlin/MainActivity.kt index e6eee7157b..f44974b434 100644 --- a/examples/platforms/android/qtquickview_kotlin/app/src/main/java/com/example/qtquickview_kotlin/MainActivity.kt +++ b/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 diff --git a/src/quick/doc/src/android/qtquick-for-android-main().qdocinc b/src/quick/doc/src/android/qtquick-for-android-main().qdocinc new file mode 100644 index 0000000000..35eb223ead --- /dev/null +++ b/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 + #include + + 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 + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + return app.exec(); + } + \endcode diff --git a/src/quick/doc/src/android/qtquick-for-android.qdoc b/src/quick/doc/src/android/qtquick-for-android.qdoc index 5a2ac59b68..be3cc4617e 100644 --- a/src/quick/doc/src/android/qtquick-for-android.qdoc +++ b/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 diff --git a/src/quick/doc/src/android/running-qtquick-for-android-examples.qdocinc b/src/quick/doc/src/android/running-qtquick-for-android-examples.qdocinc index 0d09faf26f..52c16fd913 100644 --- a/src/quick/doc/src/android/running-qtquick-for-android-examples.qdocinc +++ b/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-\platforms\android\ \endcode + These projects are already configured to use a version of the + \l{Qt Gradle Plugin} compatible with this Qt version. diff --git a/src/quick/doc/src/qtquick-android.qdoc b/src/quick/doc/src/qtquick-android.qdoc index 8cc45cbfbc..8c3dbd2a2c 100644 --- a/src/quick/doc/src/qtquick-android.qdoc +++ b/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} diff --git a/src/quick/doc/src/qtquick-external-resources.qdoc b/src/quick/doc/src/qtquick-external-resources.qdoc new file mode 100644 index 0000000000..c5472e9e63 --- /dev/null +++ b/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 +*/