Add example to show how to work with activities and handle their result

Task-number: QTBUG-83038
Change-Id: I87a631551c3c6fbb22eaaf56acad6b8ae87f4560
Reviewed-by: Tarja Sundqvist <tarja.sundqvist@qt.io>
Reviewed-by: BogDan Vatra <bogdan@kdab.com>
(cherry picked from commit 85b2ea13da75303371ef8f82d5c0a079fa437904)
Reviewed-by: Ville Voutilainen <ville.voutilainen@qt.io>

13 files changed, 691 insertions, 2 deletions

diff --git a/examples/androidextras/androidextras.pro b/examples/androidextras/androidextras.pro
index 80d1186..4ac3b2d 100644
--- a/examples/androidextras/androidextras.pro
+++ b/examples/androidextras/androidextras.pro
@@ -5,11 +5,13 @@ android {
         SUBDIRS += \
             notification \
             jnimessenger \
-            services
+            services \
+            customactivity
 
         EXAMPLE_FILES += \
             notification \
             jnimessenger \
-            services
+            services \
+            customactivity
     }
 }
diff --git a/examples/androidextras/customactivity/activityhandler.cpp b/examples/androidextras/customactivity/activityhandler.cpp
new file mode 100644
index 0000000..2d7b172
--- /dev/null
+++ b/examples/androidextras/customactivity/activityhandler.cpp
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#include "activityhandler.h"
+
+#include <QAndroidIntent>
+
+const int REQUEST_CODE = 123;
+const jint RESULT_OK = QAndroidJniObject::getStaticField<jint>("android/app/Activity", "RESULT_OK");
+ActivityHandler *ActivityHandler::m_instance = nullptr;
+
+ActivityHandler::ActivityHandler(QObject *parent) : QObject(parent)
+{
+    m_instance = this;
+}
+
+void ActivityHandler::showSecondActivity()
+{
+    QAndroidIntent activityIntent(QtAndroid::androidActivity().object(),
+                                  "org/qtproject/example/activityhandler/CustomActivity");
+
+    QtAndroid::startActivity(
+            activityIntent.handle(), REQUEST_CODE,
+            [this](int requestCode, int resultCode, const QAndroidJniObject &data) {
+                activityReceiver(requestCode, resultCode, data);
+            });
+}
+
+void ActivityHandler::activityReceiver(int requestCode, int resultCode, const QAndroidJniObject &data)
+{
+    if (requestCode == REQUEST_CODE) {
+        if (resultCode == RESULT_OK) {
+            const QAndroidJniObject key = QAndroidJniObject::fromString("message");
+            const QAndroidJniObject message = data.callObjectMethod(
+                    "getStringExtra", "(Ljava/lang/String;)Ljava/lang/String;", key.object());
+            if (message.isValid())
+                emit ActivityHandler::instance()->receiveFromActivityResult(message.toString());
+        } else {
+            emit ActivityHandler::instance()->receiveFromActivityResult("Rejected!");
+        }
+    }
+}
diff --git a/examples/androidextras/customactivity/activityhandler.h b/examples/androidextras/customactivity/activityhandler.h
new file mode 100644
index 0000000..3dba71e
--- /dev/null
+++ b/examples/androidextras/customactivity/activityhandler.h
@@ -0,0 +1,73 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#ifndef MULTIACTIVITY_H
+#define MULTIACTIVITY_H
+
+#include <QtAndroid>
+
+class ActivityHandler : public QObject
+{
+    Q_OBJECT
+
+public:
+    ActivityHandler(QObject *parent = nullptr);
+    static ActivityHandler *instance() { return m_instance; }
+
+    Q_INVOKABLE void showSecondActivity();
+    void activityReceiver(int requestCode, int resultCode, const QAndroidJniObject &data);
+
+signals:
+    void receiveFromActivityResult(const QString &message);
+
+private:
+    static ActivityHandler *m_instance;
+};
+
+#endif // MULTIACTIVITY_H
diff --git a/examples/androidextras/customactivity/android/AndroidManifest.xml b/examples/androidextras/customactivity/android/AndroidManifest.xml
new file mode 100644
index 0000000..c78a9f4
--- /dev/null
+++ b/examples/androidextras/customactivity/android/AndroidManifest.xml
@@ -0,0 +1,92 @@
+<?xml version="1.0"?>
+<manifest package="org.qtproject.example.activityhandler" xmlns:android="http://schemas.android.com/apk/res/android" android:versionName="-- %%INSERT_VERSION_NAME%% --" android:versionCode="-- %%INSERT_VERSION_CODE%% --" android:installLocation="auto">
+    <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="28"/>
+
+    <!-- The following comment will be replaced upon deployment with default permissions based on the dependencies of the application.
+         Remove the comment if you do not require these default permissions. -->
+    <!-- %%INSERT_PERMISSIONS -->
+
+    <!-- The following comment will be replaced upon deployment with default features based on the dependencies of the application.
+         Remove the comment if you do not require these default features. -->
+    <!-- %%INSERT_FEATURES -->
+
+    <supports-screens android:largeScreens="true" android:normalScreens="true" android:anyDensity="true" android:smallScreens="true"/>
+
+    <application android:hardwareAccelerated="true" android:name="org.qtproject.qt5.android.bindings.QtApplication" android:label="-- %%INSERT_APP_NAME%% --" android:extractNativeLibs="true">
+        <activity android:configChanges="orientation|uiMode|screenLayout|screenSize|smallestScreenSize|layoutDirection|locale|fontScale|keyboard|keyboardHidden|navigation|mcc|mnc|density" android:name="org.qtproject.qt5.android.bindings.QtActivity" android:label="-- %%INSERT_APP_NAME%% --" android:screenOrientation="unspecified" android:launchMode="singleTop">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+
+            <!-- Application arguments -->
+            <!-- meta-data android:name="android.app.arguments" android:value="arg1 arg2 arg3"/ -->
+            <!-- Application arguments -->
+
+            <meta-data android:name="android.app.lib_name" android:value="-- %%INSERT_APP_LIB_NAME%% --"/>
+            <meta-data android:name="android.app.qt_sources_resource_id" android:resource="@array/qt_sources"/>
+            <meta-data android:name="android.app.repository" android:value="default"/>
+            <meta-data android:name="android.app.qt_libs_resource_id" android:resource="@array/qt_libs"/>
+            <meta-data android:name="android.app.bundled_libs_resource_id" android:resource="@array/bundled_libs"/>
+            <!-- Deploy Qt libs as part of package -->
+            <meta-data android:name="android.app.bundle_local_qt_libs" android:value="-- %%BUNDLE_LOCAL_QT_LIBS%% --"/>
+
+            <!-- Run with local libs -->
+            <meta-data android:name="android.app.use_local_qt_libs" android:value="-- %%USE_LOCAL_QT_LIBS%% --"/>
+            <meta-data android:name="android.app.libs_prefix" android:value="/data/local/tmp/qt/"/>
+            <meta-data android:name="android.app.load_local_libs_resource_id" android:resource="@array/load_local_libs"/>
+            <meta-data android:name="android.app.load_local_jars" android:value="-- %%INSERT_LOCAL_JARS%% --"/>
+            <meta-data android:name="android.app.static_init_classes" android:value="-- %%INSERT_INIT_CLASSES%% --"/>
+            <!-- Used to specify custom system library path to run with local system libs -->
+            <!-- <meta-data android:name="android.app.system_libs_prefix" android:value="/system/lib/"/> -->
+            <!--  Messages maps -->
+            <meta-data android:value="@string/ministro_not_found_msg" android:name="android.app.ministro_not_found_msg"/>
+            <meta-data android:value="@string/ministro_needed_msg" android:name="android.app.ministro_needed_msg"/>
+            <meta-data android:value="@string/fatal_error_msg" android:name="android.app.fatal_error_msg"/>
+            <meta-data android:value="@string/unsupported_android_version" android:name="android.app.unsupported_android_version"/>
+            <!--  Messages maps -->
+
+            <!-- Splash screen -->
+            <!-- Orientation-specific (portrait/landscape) data is checked first. If not available for current orientation,
+                 then android.app.splash_screen_drawable. For best results, use together with splash_screen_sticky and
+                 use hideSplashScreen() with a fade-out animation from Qt Android Extras to hide the splash screen when you
+                 are done populating your window with content. -->
+            <!-- meta-data android:name="android.app.splash_screen_drawable_portrait" android:resource="@drawable/logo_portrait" / -->
+            <!-- meta-data android:name="android.app.splash_screen_drawable_landscape" android:resource="@drawable/logo_landscape" / -->
+            <!-- meta-data android:name="android.app.splash_screen_drawable" android:resource="@drawable/logo"/ -->
+            <!-- meta-data android:name="android.app.splash_screen_sticky" android:value="true"/ -->
+            <!-- Splash screen -->
+
+            <!-- Background running -->
+            <!-- Warning: changing this value to true may cause unexpected crashes if the
+                          application still try to draw after
+                          "applicationStateChanged(Qt::ApplicationSuspended)"
+                          signal is sent! -->
+            <meta-data android:name="android.app.background_running" android:value="false"/>
+            <!-- Background running -->
+
+            <!-- auto screen scale factor -->
+            <meta-data android:name="android.app.auto_screen_scale_factor" android:value="false"/>
+            <!-- auto screen scale factor -->
+
+            <!-- extract android style -->
+            <!-- available android:values :
+                * default - In most cases this will be the same as "full", but it can also be something else if needed, e.g., for compatibility reasons
+                * full - useful QWidget & Quick Controls 1 apps
+                * minimal - useful for Quick Controls 2 apps, it is much faster than "full"
+                * none - useful for apps that don't use any of the above Qt modules
+                -->
+            <meta-data android:name="android.app.extract_android_style" android:value="minimal"/>
+            <!-- extract android style -->
+        </activity>
+
+        <activity android:process=":custom_activity" android:name=".CustomActivity" android:label="-- %%INSERT_APP_NAME%% --">
+            <!-- android:process=":qt" is needed to force the service to run on a separate process than the Activity -->
+          <meta-data android:name="android.app.lib_name" android:value="-- %%INSERT_APP_LIB_NAME%% --"/>
+        </activity>
+
+    <!-- For adding service(s) please check: https://wiki.qt.io/AndroidServices -->
+
+    </application>
+
+</manifest>
diff --git a/examples/androidextras/customactivity/android/res/layout/second_activity.xml b/examples/androidextras/customactivity/android/res/layout/second_activity.xml
new file mode 100644
index 0000000..0c07790
--- /dev/null
+++ b/examples/androidextras/customactivity/android/res/layout/second_activity.xml
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/relativeLayout"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical"
+    android:padding="20dp">
+
+    <TextView
+        android:id="@+id/blackboard_text"
+        android:layout_width="match_parent"
+        android:layout_height="350dp"
+        android:layout_gravity="center"
+        android:gravity="center"
+        android:singleLine="false"
+        android:text="@string/hello_second_activity"
+        android:textAlignment="center"
+        android:textSize="60sp" />
+
+    <Button
+        android:id="@+id/backButton"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/go_back"
+        android:layout_gravity="center_vertical|center_horizontal" />
+</LinearLayout>
diff --git a/examples/androidextras/customactivity/android/res/values/strings.xml b/examples/androidextras/customactivity/android/res/values/strings.xml
new file mode 100644
index 0000000..0b65e8f
--- /dev/null
+++ b/examples/androidextras/customactivity/android/res/values/strings.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Qt Android Multi-Activity</string>
+    <string name="hello_second_activity">Hello Second Activity</string>
+    <string name="go_back">Go back</string>
+</resources>
diff --git a/examples/androidextras/customactivity/android/src/org/qtproject/example/activityhandler/CustomActivity.java b/examples/androidextras/customactivity/android/src/org/qtproject/example/activityhandler/CustomActivity.java
new file mode 100644
index 0000000..b2502e9
--- /dev/null
+++ b/examples/androidextras/customactivity/android/src/org/qtproject/example/activityhandler/CustomActivity.java
@@ -0,0 +1,78 @@
+ /****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+package org.qtproject.example.activityhandler;
+
+import android.app.Activity;
+import android.content.Intent;
+import android.os.Bundle;
+import android.view.View;
+import android.widget.Button;
+
+ public class CustomActivity extends Activity {
+
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.second_activity);
+
+        Button backButton = (Button) findViewById(R.id.backButton);
+        backButton.setOnClickListener(new View.OnClickListener() {
+
+            @Override
+            public void onClick(View view) {
+                Intent resultIntent = new Intent();
+                resultIntent.putExtra("message", "Back button clicked.");
+                setResult(Activity.RESULT_OK, resultIntent);
+                finish();
+            }
+        });
+    }
+}
diff --git a/examples/androidextras/customactivity/customactivity.pro b/examples/androidextras/customactivity/customactivity.pro
new file mode 100644
index 0000000..5c5b1e8
--- /dev/null
+++ b/examples/androidextras/customactivity/customactivity.pro
@@ -0,0 +1,27 @@
+QT += quick androidextras
+
+DEFINES += QT_DEPRECATED_WARNINGS
+
+CONFIG += c++11
+
+HEADERS += \
+    activityhandler.h
+
+SOURCES += \
+        activityhandler.cpp \
+        main.cpp
+
+RESOURCES += qml.qrc
+
+target.path = $$[QT_INSTALL_EXAMPLES]/androidextras/customactivity
+INSTALLS += target
+
+android {
+    DISTFILES += \
+        android/AndroidManifest.xml \
+        android/src/org/qtproject/example/activityhandler/CustomActivity.java \
+        android/res/layout/second_activity.xml \
+        android/res/values/strings.xml
+
+    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android
+}
diff --git a/examples/androidextras/customactivity/doc/src/qtandroidextras-example-customactivity.qdoc b/examples/androidextras/customactivity/doc/src/qtandroidextras-example-customactivity.qdoc
new file mode 100644
index 0000000..ad075e6
--- /dev/null
+++ b/examples/androidextras/customactivity/doc/src/qtandroidextras-example-customactivity.qdoc
@@ -0,0 +1,134 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Android Custom Activity
+    \ingroup examples-qtandroidextras
+    \example customactivity
+    \brief Demonstrates working with custom Android activities.
+
+    \image customactivity.png
+
+    This example demonstrates how to create an Android Activity and run it from
+    your Qt application. The activity is composed of a Java class and an Android
+    XML layout which is started from the main app. The activity can send back data
+    after finishing which can be used in QML.
+
+    When you click the \uicontrol{"Start custom Android activity"} button, the
+    activity is started, and the activity has a text view and a button to exit.
+    The activity can either use the button or the back gesture to go back.
+
+    \include examples-run.qdocinc
+
+    \section1 Create Activity Class
+
+    Define an Android class called \c CustomActivity in the CustomActivity.java
+    file as follows:
+
+    \quotefromfile customactivity/android/src/org/qtproject/example/activityhandler/CustomActivity.java
+    \skipto package
+    \printuntil /^\}/
+
+    The Activity's layout is defined at \e {customactivity/android/res/layout/second_activity.xml}.
+
+    To use this Activity, it must be defined in the \e AndroidManifest.xml file
+    as follows:
+
+    \quotefromfile customactivity/android/AndroidManifest.xml
+    \skipto :custom_activity
+    \printuntil </activity>
+
+    \note To use any native JNI calls, you must extend \c QtActivity instead of
+    \c Activity.
+
+    \section1 Start the Activity
+
+    To start an Activity from Qt, you need to create an intent using \l{QAndroidIntent},
+    then call \l{QtAndroid::startActivity} providing the intent, a custom request
+    code, and a callback function. The latter is called after the activity has
+    finished. You can start the activity as follows:
+
+    \quotefromfile customactivity/activityhandler.cpp
+    \skipto showSecondActivity
+    \printuntil });
+    \printline }
+
+    Then, define the callback function that is called directly after the activity
+    is done:
+
+    \quotefromfile customactivity/activityhandler.cpp
+    \skipto ActivityHandler::activityReceiver
+    \printuntil }
+
+    \note You can first check that the \c requestCode and \c resultCode are correct.
+
+    To connect C++ with QML, add an instance of the C++ class that is handling
+    the JNI logic as a QML property in the \e main.cpp file:
+
+    \quotefromfile customactivity/main.cpp
+    \skipto ActivityHandler
+    \printuntil setContextProperty
+
+    Then, add a \l Connections element to watch for messages from C++ in the
+    \e main.qml file:
+
+    \quotefromfile customactivity/main.qml
+    \skipto Connections
+    \printuntil /^\ {4}\}/
+
+    And set the \c onClicked for the \uicontrol{"Start custom Android activity"}
+    button to:
+
+    \quotefromfile services/common/main.qml
+    \skipto onClicked
+    \printline onClicked
+
+    \sa {Qt for Android}, {Qt Android Extras}
+*/
diff --git a/examples/androidextras/customactivity/main.cpp b/examples/androidextras/customactivity/main.cpp
new file mode 100644
index 0000000..4c1ab3d
--- /dev/null
+++ b/examples/androidextras/customactivity/main.cpp
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#include "activityhandler.h"
+
+#include <QGuiApplication>
+#include <QQmlApplicationEngine>
+#include <QQmlContext>
+
+int main(int argc, char *argv[])
+{
+    QGuiApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
+    QGuiApplication app(argc, argv);
+    QQmlApplicationEngine engine;
+    const QUrl url(QStringLiteral("qrc:/main.qml"));
+
+    ActivityHandler *activityHandler = new ActivityHandler(&app);
+    engine.rootContext()->setContextProperty(QLatin1String("activityHandler"), activityHandler);
+
+    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
+                     &app, [url](QObject *obj, const QUrl &objUrl) {
+        if (!obj && url == objUrl)
+            QCoreApplication::exit(-1);
+    }, Qt::QueuedConnection);
+    engine.load(url);
+
+    return app.exec();
+}
diff --git a/examples/androidextras/customactivity/main.qml b/examples/androidextras/customactivity/main.qml
new file mode 100644
index 0000000..75f8ff3
--- /dev/null
+++ b/examples/androidextras/customactivity/main.qml
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtAndroidExtras module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import QtQuick 2.14
+import QtQuick.Window 2.14
+import QtQuick.Controls 2.14
+
+Window {
+    id: window
+    visible: true
+    width: 640
+    height: 480
+    title: qsTr("Qt Activity handler")
+
+    property string status: "Return status: "
+    Text {
+        id: resultText
+        anchors.verticalCenter: parent.verticalCenter
+        anchors.horizontalCenter: parent.horizontalCenter
+        font.pointSize: 20
+        text: status + "not started"
+    }
+
+    Button {
+        text: "Start custom Android activity"
+        anchors.verticalCenterOffset: 100
+        anchors.verticalCenter: parent.verticalCenter
+        anchors.horizontalCenter: parent.horizontalCenter
+        onClicked: activityHandler.showSecondActivity()
+    }
+
+    Connections {
+        target: activityHandler
+        function onReceiveFromActivityResult(message) {
+            resultText.text = status + message
+        }
+    }
+}
diff --git a/examples/androidextras/customactivity/qml.qrc b/examples/androidextras/customactivity/qml.qrc
new file mode 100644
index 0000000..5f6483a
--- /dev/null
+++ b/examples/androidextras/customactivity/qml.qrc
@@ -0,0 +1,5 @@
+<RCC>
+    <qresource prefix="/">
+        <file>main.qml</file>
+    </qresource>
+</RCC>
diff --git a/src/androidextras/doc/images/customactivity.png b/src/androidextras/doc/images/customactivity.png
new file mode 100644
index 0000000..4b01a0a
--- /dev/null
+++ b/src/androidextras/doc/images/customactivity.png