From 86febcac3f27b48908917c821af1e4abe14314d1 Mon Sep 17 00:00:00 2001 From: Nicholas Bennett Date: Mon, 31 Oct 2022 14:30:20 +0200 Subject: Docs: Add Android platform documentation How it works page, host environment variables page, and relevant CMake information page added. Fixes: QTBUG-107704 Change-Id: I823d3f9d97f49e79da867660bd4cd41a8378266a Reviewed-by: Assam Boudjelthia (cherry picked from commit 23d41aaf79d37e6a7012edfbec879d92429ea28c) --- doc/config/images/nmvurCcsWos.jpg | Bin 0 -> 39810 bytes doc/config/qtdoc.qdocconf | 8 +-- doc/images/qt_android_architecture.png | Bin 0 -> 20029 bytes .../platforms/android/android-CMake-variables.qdoc | 34 +++++++++++++ .../android/android-envoirnment-variables.qdoc | 44 ++++++++++++++++ .../platforms/android/android-how-it-works.qdoc | 56 +++++++++++++++++++++ 6 files changed, 138 insertions(+), 4 deletions(-) create mode 100644 doc/config/images/nmvurCcsWos.jpg create mode 100644 doc/images/qt_android_architecture.png create mode 100644 doc/src/platforms/android/android-CMake-variables.qdoc create mode 100644 doc/src/platforms/android/android-envoirnment-variables.qdoc create mode 100644 doc/src/platforms/android/android-how-it-works.qdoc diff --git a/doc/config/images/nmvurCcsWos.jpg b/doc/config/images/nmvurCcsWos.jpg new file mode 100644 index 00000000..bc8a4766 Binary files /dev/null and b/doc/config/images/nmvurCcsWos.jpg differ diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf index 5236dc2f..858c2809 100644 --- a/doc/config/qtdoc.qdocconf +++ b/doc/config/qtdoc.qdocconf @@ -63,10 +63,10 @@ qhp.QtDoc.subprojects.examples.selectors = fake:example qhp.QtDoc.subprojects.examples.sortPages = true # Add an image used in example manifests to qhp, as well as thumbnails for YouTube links -{HTML.extraimages,qhp.QtDoc.extraFiles} += \ - images/qt-codesample.png \ - images/yIv0vO8B7tQ.jpg \ - images/5OiIqFTjUZI.jpg +{HTML.extraimages,DocBook.extraimages,qhp.QtDoc.extraFiles} += images/qt-codesample.png \ + images/yIv0vO8B7tQ.jpg \ + images/5OiIqFTjUZI.jpg \ + images/nmvurCcsWos.jpg # Add an .html file with sidebar content, used in the online style HTML.stylesheets += style/qt5-sidebar.html diff --git a/doc/images/qt_android_architecture.png b/doc/images/qt_android_architecture.png new file mode 100644 index 00000000..54d18c6c Binary files /dev/null and b/doc/images/qt_android_architecture.png differ diff --git a/doc/src/platforms/android/android-CMake-variables.qdoc b/doc/src/platforms/android/android-CMake-variables.qdoc new file mode 100644 index 00000000..998ecf97 --- /dev/null +++ b/doc/src/platforms/android/android-CMake-variables.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page android-build-environment-variables.html +\title Qt for Android: CMake +\brief Information regarding CMake and Android platform APIs. +\ingroup androidplatform + +This page lists information regarding CMake and Qt for Android platform support. + +\section1 Variables affecting the build process + + \list + \li \l{QT_ANDROID_PACKAGE_SOURCE_DIR} + \li \l{QT_ANDROID_EXTRA_LIBS} + \li \l{QT_ANDROID_EXTRA_PLUGINS} + \endlist + +\section2 Variables affecting Gradle + \list + \li \l{QT_ANDROID_MIN_SDK_VERSION} + \li \l{QT_ANDROID_TARGET_SDK_VERSION} + \li \l{QT_ANDROID_SDK_BUILD_TOOLS_REVISION} + \endlist + +\section2 Variables affecting the Android app manifest file + \list + \li \l{QT_ANDROID_VERSION_CODE} + \li \l{QT_ANDROID_VERSION_NAME} + \li \l{QT_ANDROID_APPLICATION_ARGUMENTS} + \endlist + +*/ diff --git a/doc/src/platforms/android/android-envoirnment-variables.qdoc b/doc/src/platforms/android/android-envoirnment-variables.qdoc new file mode 100644 index 00000000..6f285be6 --- /dev/null +++ b/doc/src/platforms/android/android-envoirnment-variables.qdoc @@ -0,0 +1,44 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page android-environment-variables.html +\title Environment Variables Used by Qt for Android +\brief Lists some useful environment variables used by the Qt For Android toolchain. +\ingroup androidplatform + +\section1 Enabling or disabling workarounds + +Qt Android uses some environment variables to enable/disable certain workarounds: +\section2 Commonly used variables +\list + \li QT_ANDROID_NO_EXIT_CALL: In some cases, an Android app might not be able + to safely clean all threads while calling \c exit() and crash. This is because + there are C++ threads running and destroying these without joining them + terminates an application. These threads cannot be joined because it's not + possible to know if they are running. + This flag avoids calling \c exit() and lets the Android system handle this, + at the cost of not attempting to run global destructors. + \li QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT: Allows + the hiding of predictive text suggestions, mainly from password fields. Certain + devices don’t handle this properly. + \li QT_ANDROID_ENABLE_RIGHT_MOUSE_FROM_LONG_PRESS: Interprets a long touch press + as a right mouse click event. + \li QT_ANDROID_DISABLE_ACCESSIBILITY: Disable \l{Assistive Tools}{Accessibility}. + This prevents the processing of accessibility events. +\endlist + +\section2 Less commonly used variables +\list + \li QT_ANDROID_FONT_LOCATION: Sets a custom path for system fonts. + \li QT_ANDROID_MAX_ASSETS_CACHE_SIZE: cache size for assets under the + assets folder. + \li QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND + \li QT_ANDROID_RASTER_IMAGE_DEPTH + \li QT_ANDROID_MINIMUM_MOUSE_DOUBLE_CLICK_DISTANCE +\endlist + +\note Though related, these are not the same as CMake commands or variables used +by Qt For Android, see \l{Qt for Android: CMake} + +*/ diff --git a/doc/src/platforms/android/android-how-it-works.qdoc b/doc/src/platforms/android/android-how-it-works.qdoc new file mode 100644 index 00000000..0ec8db1c --- /dev/null +++ b/doc/src/platforms/android/android-how-it-works.qdoc @@ -0,0 +1,56 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page android-how-it-works.html +\title Qt for Android: How It Works +\brief An overview of architecture, toolchain, and other useful information. +\ingroup androidplatform + + +If you're a developer looking for a high level overview of how Qt supports the +Android platform, this page is for you. + +The video from the 2021 Qt World Summit gives an overview of Qt for Android. + +\youtube nmvurCcsWos "A picture of an agenda that links to a YouTube video" + +\section1 Architecture + +\section2 Activities +The implementation of Qt for Android is made up of three main parts, +and the glue in between: + +\list + \li Qt Core + \li the Android QPA plugin + \li The Java Android code +\endlist + +\image qt_android_architecture.png "An overview Qt for Android's Architecture" + +\list + \li The default entry point for a Qt app is the QtActivity, which upon + starting, will call the QtActivityLoader which will try to load the + application by calling the QtActivityDelegate. + \li QtActivityDelegate will make the necessary calls to load the Qt + libraries and the main app library with the help of QtNative. + \li QtNative handles the various Java operations that don’t need to be + exposed, such as: loading the libraries and handling files. + \li The QtActivityDelegate also handles the different listeners and input + handlers and propagate them from Java to Qt. +\endlist + +\section2 Services + +The architecture here is similar to that of Activities, but with services +specific classes. + +For information on how Qt supports Services in Android see \l{Android Services}. + +\section1 Build configuration + +For more information on configuration Qt for Android Builds see +\l{Environment Variables Used by Qt for Android} and \{Qt for Android: CMake}. + +*/ -- cgit v1.2.1