Revision control

++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \page android-how-it-works.html
++ \title How Qt for Android Works
++ \brief An overview of how a Qt for Android app works under the hood and its architecture.
++ \ingroup explanations-platforms
++ \previouspage android-getting-started.html
++ \nextpage android-building.html
++
++ If you're a developer looking for a high-level overview of how Qt supports the
++ Android platform, this page is for you.
++
++ \section1 Starting the Qt Application
++
++ Similar to native Android apps, Qt main Activity's \l {Android: Activity onCreate()}{onCreate()}
++ is called early on when the app is started and the Activity is created. That's
++ where most of the initialization of the Android \l {Qt Platform Abstraction} (QPA)
++ takes place. The most important parts are:
++
++ \list
++ \li Loading Qt and the main application's libraries.
++ \li Initializing the delegates which takes care of initializing the rendering
++ surfaces and the top level layout, as well as registering various listeners
++ like input, display, touch handlers, among others.
++ \endlist
++
++ When loading the Qt libraries, the JavaVM is cached while \l QtCore is first loaded.
++ This is done under the \l {Android: JNI_OnLoad()}{JNI_OnLoad()} function, which is
++ called synchronously when a library is loaded using \l {Android: System load()}{System.load()}
++ call. Every Qt module might have an implementation for this function to do some
++ module-specific initialization, like registering native JNI methods.
++
++ Once all Qt modules libraries are loaded, Qt loads the Android QPA plugin and the
++ main application library. After the top level \c QtLayout layout has finished
++ inflating its content, the Qt application's \c {main()} handle is located and
++ invoked. That will start the C++ Qt application and usually start the main event loop.
++
++ \section1 The Android QPA
++
++ The \l {Qt Platform Abstraction}{Android QPA} is responsible for gluing the Android
++ (Java/Kotlin) side with the native Qt (C++) side. It handles the various event
++ and signal propagation both to and from Qt to Android. That responsibility spans
++ signal handling, touch events, UI elements, and rendering, etc. This layer is also
++ responsible for app startup initialization and cleanup upon app exit or destruction.
++
++ \section2 Threads
++
++ With Qt for Android apps, Qt usually has two threads of interest. The first is the
++ \c QtThread that Qt starts. The second one is the Android UI thread.
++
++ \section3 QtThread
++
++ This thread is implemented and started by the Qt app first before, for example,
++ loading the libraries. This thread is called \c qtMainLoopThread. All the following
++ operations are executed under this thread:
++
++ \list
++ \li Qt library loading.
++ \li Operations done inside \l {Android: JNI_OnLoad()}{JNI_OnLoad()}.
++ \li Starting the native application.
++ \li The execution of \c {main()}.
++ \endlist
++
++ \section3 Android UI Thread
++
++ Similar to Android apps, operations that affect the UI are expected to run in the UI
++ thread. Qt does that under the hood for any internal calls that are expected
++ to run in the UI. Also, Qt offers an API
++ \l {QNativeInterface::QAndroidApplication::runOnAndroidMainThread()}{runOnAndroidMainThread()}
++ to run operations under this thread from C++ code. Using this API, Qt manages when
++ the calls are directly posted to the thread if the app is active, or queued if the app
++ is paused or in the background.
++
++ \section2 Architecture
++
++ //! The diagram is designed using https://www.drawio.com.
++ //! To modify it import this svg file and edit on top of it.
++ \image qt-android-architecture.drawio.svg "An overview Qt for Android's Architecture"
++
++
++ \section1 Qt Classes
++
++ These next sections go through the various Qt for Android classes and their functionality
++ and role in Qt applications.
++
++ \section2 The Public Java Bindings
++
++ These classes are public classes that wrap the internal implementation details of the
++ user-facing classes like \l {Android: Activity}{Activity}, \l {Android: Service}{Service}
++ and \l {Android: Application}{Application}. These classes are used by default for Qt
++ Android apps and referred to in the Android manifest file. The build system and
++ deployment tools take care of including them in the build.
++
++ Users can use these classes to change or extend the default behavior. For example, QtActivity
++ extends \c Activity and implements the logic needed to load the Qt libraries or handle events
++ and native calls between Android and Qt.
++
++ Extending \c QtActivity is generally needed if you need to have Qt's implementation for
++ various events and calls between Qt and Android. Otherwise, extending \c Activity should work.
++
++ To add custom user-defined logic under \l {Android: Activity onCreate()}{onCreate()},
++ you can use the following:
++
++ \code
++ public class MyActivity extends QtActivity
++ {
++ @Override
++ protected void onCreate(Bundle bundle)
++ {
++ // code before Qt is initialized
++ super.onCreate(bundle);
++ // code after Qt is initialized
++ }
++ }
++ \endcode
++
++ \note You must edit the \l {Qt for Android Manifest File Configuration}{AndroidManifest.xml}
++ file to use your custom \l {Android: Activity}{Activity} or binding class,
++ otherwise, the default one will still be used.
++
++ \section3 Setting a Theme
++
++ When extending \l{The Public Java Bindings}{QtActivity}, you can set a specific Android theme using
++ \l {Android: Activity setTheme()}{setTheme()}. However, that call must precede
++ the call to the parent class's \l {Android: Activity onCreate()}{onCreate()} for
++ it to take effect since Qt sets the theme by default. For example, you can use:
++
++ \code
++ @Override
++ protected void onCreate(Bundle bundle)
++ {
++ setTheme(android.R.style.Theme_DeviceDefault_DayNight);
++ super.onCreate(bundle);
++ }
++ \endcode
++
++ By default, for Android 10 and later, Qt sets the theme
++ \l {Android: Theme_DeviceDefault_DayNight Style}{Theme_DeviceDefault_DayNight Style},
++ and \l {Android: Theme_Holo_Light Style}{Theme_Holo_Light Style} for earlier versions.
++
++ \section3 Append an Application Parameter
++
++ To append an extra application parameter, that is an argument that's passed to
++ the application's \c (main()) function from Java/Kotlin, you can do the following
++ after extending \l {The Public Java Bindings}{QtActivity}:
++
++ \code
++ @Override
++ protected void onCreate(Bundle bundle)
++ {
++ appendApplicationParameters("--flag value");
++ super.onCreate(bundle);
++ }
++ \endcode
++
++ This is similar to using the CMake variable \l {QT_ANDROID_APPLICATION_ARGUMENTS} directly.
++ Parameters passed using either method accept spaces or tabs as separators, and the final
++ list of parameters passed to the application are parsed using \l {QProcess::splitCommand}.
++
++ \section2 Loading Qt Libraries with QtLoader
++
++ Every Qt for Android app needs to ensure every native Qt or 3rd party library is first
++ loaded before invoking any functionality from those modules. The build system keeps
++ a list of various Qt library dependencies, the QPA plugin, the main app library, and any
++ third-party library under the application's \l {Java/Kotlin Code}{libs.xml}
++ resource file. Once all the prerequisite steps mentioned in the sections below
++ are done, the libraries are loaded using \l {Android: System load()}{System.load()}.
++
++ \section3 The Class Loader
++
++ The class loader object is set early on by the \c QtLoader before loading Qt libraries
++ or initializing the delegates. This is because the class loader is used by \l QJniObject
++ to find Java classes and is required to do any JNI call with \l QJniObject.
++
++ \section3 Setting Environment Variables and Application Parameters
++
++ Before loading the libraries, Qt has to ensure environment variables are passed as metadata
++ in the Android manifest to set. This step enables the initialization of some modules
++ based on the configuration flags set as manifest meta-data. Some of this meta-data is also
++ propagated to the application parameters list that is passed to the application when it's started.
++
++ \section3 setActivity(), setContext() and setService()
++
++ Various Qt modules might need to do some initialization work from the Java side
++ that requires having the context of the \l {Android: Activity}{Activity} or
++ \l {Android: Service}{Service}. Those modules then implement a static method
++ that takes an \l {Android: Activity}{Activity}, Service or Context as a parameter:
++
++ \code
++ void setActivity(Activity activity)
++ {
++ m_activity = activity;
++ // Other logic
++ }
++ \endcode
++
++ Then, the \c QtLoader invokes these methods with the parent context of the loader
++ just before loading the native shared libraries.
++
++ \section1 How Qt for Android Handles the Android Activity Life-cycle
++
++ Qt for Android does not provide an API to directly handle the Android activity
++ life-cycle callbacks such as onCreate(), onStart(), onResume(), onPause(),
++ onStop(), and onDestroy(). Instead, it handles these under the hood for the user.
++ The behavior is outlined in the following sections.
++
++ \note These life-cycle events are translated to the
++ \l{QGuiApplication::applicationStateChanged} signal.
++
++ \section2 Context Handling
++
++ \l {QNativeInterface::QAndroidApplication}{QAndroidApplication} can provide the Android
++ \l{Android: Context}{Context} as a \c QJniObject, essential for interacting with the Android
++ system. This context can be an Activity or a Service. If there is an Activity, it will be the
++ most recently started Activity, regardless of whether there are Services. If there is
++ only Services, it will be the most recently started Service.
++
++ \note Qt for Android does not support multiple Activites.
++
++ \section2 Callbacks
++
++ The QtActivityBase class is designed to keep the implementation details of an
++ Activity’s various functionalities private within the Qt for Android package.
++ This class is a mediator between the Android life-cycle and the Qt framework,
++ translating Android life-cycle callbacks into signals and operations to which
++ the Qt application can respond.
++
++ \section3 onCreate()
++
++ When the Activity is created, QtActivityBase initializes the Qt
++ environment. This includes loading the Qt libraries, setting up the class loader
++ that QJniObject uses, parsing the app’s metadata, and preparing the Qt
++ application for execution. It ensures that all necessary initialization specific
++ to the Activity is handled.
++
++ \section3 onStart()
++
++ Calls Android's Activity.OnStart().
++
++ \section3 onResume()
++
++ When the Activity moves to the foreground, QtActivityBase resumes the Qt
++ application. It ensures that paused processes or operations continue and the
++ application is again ready for user interaction. It will re-register the display
++ manager listener stopped by onPause().
++
++ \section3 onPause()
++
++ If another activity partially obscures the Activity, QtActivityBase pauses
++ the Qt application. It will save the application state or release resources that
++ are not needed while the application is not in the foreground.
++
++ \section3 onStop()
++
++ When the Activity is no longer visible, QtActivityBase stops the Qt
++ application, which involves more extensive state saving and resource release,
++ preparing the application for potential destruction.
++
++ \note The QtThread is suspended at this point.
++
++ \section3 onDestroy()
++
++ If the Activity is finished or being destroyed by the
++ system, QtActivityBase cleans up all resources associated with the
++ Qt application. It ensures a proper shutdown and that all necessary cleanup
++ operations are performed.
++
++ This integration allows developers to focus on building their Qt application
++ without worrying about the intricacies of the Android life-cycle, as
++ QtActivityBase manages these complexities under the hood.
++
++ \section1 Splash Screen Management
++
++ \l {QNativeInterface::QAndroidApplication}{QAndroidApplication} can hide the splash screen
++ with a fade effect, which can be timed with the application’s startup sequence, typically
++ after onCreate().
++
++ \section1 More About Qt for Android
++
++ 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"
++
++ */