// 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 {QAndroidApplication::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 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,
to add custom user-defined logic under \l {Android: Activity onCreate()}{onCreate()},
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 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(bubdle);
}
\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(bubdle);
}
\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 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 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"

*/
