Update Annotated URL example

This patch updates Annotated Url NFC example to support automatic
application startup, when running on Android. The example documentation
is also extended to cover this case.

Task-number: QTBUG-94033
Change-Id: Iec94e5e97bc13e5083842838c78f4e988d8c5f70
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

10 files changed, 161 insertions, 20 deletions

diff --git a/examples/nfc/annotatedurl/CMakeLists.txt b/examples/nfc/annotatedurl/CMakeLists.txt
index 6a40dc85..7e3e54f2 100644
--- a/examples/nfc/annotatedurl/CMakeLists.txt
+++ b/examples/nfc/annotatedurl/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Nfc)
 find_package(Qt6 COMPONENTS Widgets)
 
 qt_add_executable(annotatedurl
+    MANUAL_FINALIZATION
     annotatedurl.cpp annotatedurl.h
     main.cpp
     mainwindow.cpp mainwindow.h mainwindow.ui
@@ -34,6 +35,15 @@ target_link_libraries(annotatedurl PUBLIC
     Qt::Widgets
 )
 
+if(ANDROID)
+    set_property(TARGET annotatedurl
+        APPEND PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
+        ${CMAKE_CURRENT_SOURCE_DIR}/android
+    )
+endif()
+
+qt_finalize_target(annotatedurl)
+
 install(TARGETS annotatedurl
     RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
     BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
diff --git a/examples/nfc/annotatedurl/android/AndroidManifest.xml b/examples/nfc/annotatedurl/android/AndroidManifest.xml
new file mode 100644
index 00000000..b5db49c9
--- /dev/null
+++ b/examples/nfc/annotatedurl/android/AndroidManifest.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0"?>
+<manifest package="org.qtproject.example.annotatedurl" xmlns:android="http://schemas.android.com/apk/res/android" android:versionName="-- %%INSERT_VERSION_NAME%% --" android:versionCode="-- %%INSERT_VERSION_CODE%% --" android:installLocation="auto">
+    <!-- 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.qt.android.bindings.QtApplication" android:label="-- %%INSERT_APP_NAME%% --" android:extractNativeLibs="true" android:requestLegacyExternalStorage="true">
+        <activity android:configChanges="orientation|uiMode|screenLayout|screenSize|smallestScreenSize|layoutDirection|locale|fontScale|keyboard|keyboardHidden|navigation|mcc|mnc|density" android:name="org.qtproject.qt.android.bindings.QtActivity" android:label="-- %%INSERT_APP_NAME%% --" android:screenOrientation="unspecified" android:launchMode="singleTask">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
+                <category android:name="android.intent.category.DEFAULT"/>
+                <data android:mimeType="text/plain"/>
+            </intent-filter>
+
+            <!-- Application arguments -->
+            <meta-data android:name="android.app.arguments" android:value="-- %%INSERT_APP_ARGUMENTS%% --"/>
+            <!-- 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 -->
+
+            <!-- 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="default"/>
+            <!-- extract android style -->
+    </activity>
+
+    <!-- For adding service(s) please check: https://wiki.qt.io/AndroidServices -->
+
+    </application>
+
+</manifest>
diff --git a/examples/nfc/annotatedurl/annotatedurl.cpp b/examples/nfc/annotatedurl/annotatedurl.cpp
index 4e8c420e..5bb602e5 100644
--- a/examples/nfc/annotatedurl/annotatedurl.cpp
+++ b/examples/nfc/annotatedurl/annotatedurl.cpp
@@ -65,15 +65,9 @@
 #include <QtCore/QUrl>
 
 AnnotatedUrl::AnnotatedUrl(QObject *parent)
-:   QObject(parent)
+    : QObject(parent),
+      manager(new QNearFieldManager(this))
 {
-    manager = new QNearFieldManager(this);
-    if (!manager->isEnabled()) {
-        qWarning() << "NFC not enabled";
-        return;
-    }
-
-    manager->startTargetDetection(QNearFieldTarget::NdefAccess);
     connect(manager, &QNearFieldManager::targetDetected,
             this, &AnnotatedUrl::targetDetected);
     connect(manager, &QNearFieldManager::targetLost,
@@ -85,6 +79,16 @@ AnnotatedUrl::~AnnotatedUrl()
 
 }
 
+void AnnotatedUrl::startDetection()
+{
+    if (!manager->isEnabled()) {
+        qWarning() << "NFC not enabled";
+        return;
+    }
+
+    manager->startTargetDetection(QNearFieldTarget::NdefAccess);
+}
+
 void AnnotatedUrl::targetDetected(QNearFieldTarget *target)
 {
     if (!target)
diff --git a/examples/nfc/annotatedurl/annotatedurl.h b/examples/nfc/annotatedurl/annotatedurl.h
index 3a71f604..59ada47a 100644
--- a/examples/nfc/annotatedurl/annotatedurl.h
+++ b/examples/nfc/annotatedurl/annotatedurl.h
@@ -69,6 +69,8 @@ public:
     explicit AnnotatedUrl(QObject *parent = 0);
     ~AnnotatedUrl();
 
+    void startDetection();
+
 signals:
     void annotatedUrl(const QUrl &url, const QString &title, const QPixmap &pixmap);
 
diff --git a/examples/nfc/annotatedurl/annotatedurl.pro b/examples/nfc/annotatedurl/annotatedurl.pro
index e2bb7c06..c13ce0c6 100644
--- a/examples/nfc/annotatedurl/annotatedurl.pro
+++ b/examples/nfc/annotatedurl/annotatedurl.pro
@@ -13,5 +13,12 @@ HEADERS  += mainwindow.h \
 
 FORMS    += mainwindow.ui
 
+android {
+    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android
+
+    DISTFILES += \
+        android/AndroidManifest.xml
+}
+
 target.path = $$[QT_INSTALL_EXAMPLES]/nfc/annotatedurl
 INSTALLS += target
diff --git a/examples/nfc/annotatedurl/doc/images/annotatedurl.png b/examples/nfc/annotatedurl/doc/images/annotatedurl.png
index 01130ecd..39f2c66e 100644
--- a/examples/nfc/annotatedurl/doc/images/annotatedurl.png
+++ b/examples/nfc/annotatedurl/doc/images/annotatedurl.png
diff --git a/examples/nfc/annotatedurl/doc/images/annotatedurl2.png b/examples/nfc/annotatedurl/doc/images/annotatedurl2.png
index 2ea6f12f..bb6208e9 100644
--- a/examples/nfc/annotatedurl/doc/images/annotatedurl2.png
+++ b/examples/nfc/annotatedurl/doc/images/annotatedurl2.png
diff --git a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
index db165852..c3c3d525 100644
--- a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
+++ b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
@@ -38,27 +38,35 @@ image/* MIME record, and one or more localized Text records.
 This is the initial state of the example:
 \image annotatedurl.png
 
-In this example the NFC Tag used contains a text record. The UI
-gets updated accordingly to:
+In this example the NFC Tag used contains a text record and an URI record.
+The UI gets updated accordingly to:
 
 \image annotatedurl2.png
 
+When the screen is tapped, the URL will be opened in the browser.
+
 \section1 AnnotatedUrl Class Definition
 
-The \c AnnotatedUrl class wraps the \c QNearFieldManager, the class
-providing the NFC Tag detection functionality. NDEF messages are read
-by the QNearFieldManager and forwarded to a handler contained in the
+The \c AnnotatedUrl class wraps \l QNearFieldManager, the class providing
+the NFC Tag detection functionality. NDEF messages are read by
+\l QNearFieldManager and forwarded to a handler contained in the
 \c AnnotatedUrl class. After parsing the NDEF message the class emits
-the signal AnnotatedUrl::annotatedUrl(const QUrl &url, const QString
-&title, const QPixmap &pixmap). The UI reacts to the signal displaying
+the \c annotatedUrl() signal. The UI reacts to the signal displaying
 the contents of the NDEF message.
 
 \snippet annotatedurl/annotatedurl.h 0
 
+\note The \c startDetection() method is used to defer the actual tag detection
+until all the connections between the UI and NFC-related logic are established.
+This is important when the application is automatically started once an NFC tag
+is touched. Such usecase is currently supported on Android.
+
+\snippet annotatedurl/main.cpp 0
+
 \section1 AnnotatedUrl Handler Implementation
 
-NFC messages read by the \c QNearFieldManager are forwarded to
-AnnotatedUrl::handleMessage.
+NFC messages read by the \l QNearFieldManager are forwarded to
+\c {AnnotatedUrl::handleMessage}.
 
 \snippet annotatedurl/annotatedurl.cpp handleMessage 1
 
@@ -66,7 +74,6 @@ Because NFC messages are composed of several NDEF records, looping
 through all of the records allows the extraction of the 3 parameters
 to be displayed in the UI: the Uri, the Title and the Pixmap:
 
-
 \snippet annotatedurl/annotatedurl.cpp handleMessage 2
 \snippet annotatedurl/annotatedurl.cpp handleMessage 3
 
@@ -75,6 +82,30 @@ corresponding signal is emitted so that the UI can handle it.
 
 \snippet annotatedurl/annotatedurl.cpp handleMessage 4
 
+\section1 Automatic Application Startup
+
+Android supports automatic application startup when the NDEF tag is touched.
+See \l {Qt NFC on Android} for the required changes to the Android manifest
+file.
+
+Introduction of a custom AndroidManifest.xml requires special steps on the
+build system side.
+
+\section2 Building with qmake
+
+When using qmake, the following needs to be added to the \c {.pro} file:
+
+\quotefromfile annotatedurl/annotatedurl.pro
+\skipto android {
+\printuntil }
+
+\section2 Building with CMake
+
+When using CMake, the following needs to be added to the \c CMakeLists.txt:
+
+\quotefromfile annotatedurl/CMakeLists.txt
+\skipto if(ANDROID)
+\printuntil endif()
 
 \include examples-run.qdocinc
 
diff --git a/examples/nfc/annotatedurl/main.cpp b/examples/nfc/annotatedurl/main.cpp
index 9ce6c1b9..d0f68eb2 100644
--- a/examples/nfc/annotatedurl/main.cpp
+++ b/examples/nfc/annotatedurl/main.cpp
@@ -57,17 +57,19 @@
 
 #include <QtWidgets/QApplication>
 
+//! [0]
 int main(int argc, char *argv[])
 {
     QApplication a(argc, argv);
     MainWindow mainWindow;
-
     AnnotatedUrl annotatedUrl;
 
     QObject::connect(&annotatedUrl, &AnnotatedUrl::annotatedUrl,
                      &mainWindow, &MainWindow::displayAnnotatedUrl);
 
+    annotatedUrl.startDetection();
     mainWindow.show();
 
     return a.exec();
 }
+//! [0]
diff --git a/examples/nfc/annotatedurl/mainwindow.h b/examples/nfc/annotatedurl/mainwindow.h
index 9cfb6e7f..36ad9944 100644
--- a/examples/nfc/annotatedurl/mainwindow.h
+++ b/examples/nfc/annotatedurl/mainwindow.h
@@ -77,7 +77,7 @@ public slots:
     void displayAnnotatedUrl(const QUrl &url, const QString &title, const QPixmap &pixmap);
 
 protected:
-    void mouseReleaseEvent(QMouseEvent *event);
+    void mouseReleaseEvent(QMouseEvent *event) override;
 
 private:
     Ui::MainWindow *ui;