Qt for Android の仕組み

Qt が Android プラットフォームをどのようにサポートしているのか、その概要を知りたい開発者の方は、このページをご覧ください。

Qt アプリケーションの開始

Androidのネイティブアプリと同様に、Qt main ActivityのonCreate()は、アプリが開始され、Activityが作成されると、早い段階で呼び出されます。ここで、AndroidQt Platform Abstraction（QPA）の初期化のほとんどが行われます。最も重要な部分は次のとおりです：

• Qt とメインアプリケーションのライブラリのロード。
• レンダリングサーフェスとトップレベルレイアウトの初期化、および入力、表示、タッチハンドラなどのさまざまなリスナーの登録を行うデリゲートの初期化。

Qtライブラリをロードする際、QtCore が最初にロードされる間にJavaVMがキャッシュされます。これはJNI_OnLoad()関数の下で行われ、System.load()コールを使ってライブラリがロードされるときに同期的に呼び出される。すべてのQtモジュールは、ネイティブJNIメソッドの登録など、モジュール固有の初期化を行うために、この関数の実装を持っているかもしれません。

すべての Qt モジュール ライブラリがロードされると、Qt は Android QPA プラグインとメイン アプリケーション ライブラリをロードします。トップレベルQtLayout レイアウトのコンテンツが膨張し終わると、Qt アプリケーションのmain() ハンドルの場所が特定され、呼び出されます。これで C++ Qt アプリケーションが起動し、通常はメイン・イベント・ループが開始します。

Android QPA

Android QPAは、Android（Java/Kotlin）側とネイティブQt（C++）側を接続する役割を果たします。QtからAndroidへの、またAndroidからQtへの様々なイベントやシグナルの伝搬を処理します。その責任は、シグナル処理、タッチイベント、UI要素、レンダリングなど多岐にわたります。このレイヤーは、アプリの起動時の初期化や、アプリの終了時や破棄時のクリーンアップも担当します。

スレッド

Qt for Androidアプリでは、Qtには通常2つのスレッドがあります。1つ目はQtが起動するQtThread 。もう1つはAndroid UIスレッドです。

QtThread

このスレッドはQtアプリによって実装され、ライブラリをロードする前などに最初に起動されます。このスレッドはqtMainLoopThread と呼ばれます。以下の処理はすべてこのスレッドで実行されます：

• Qtライブラリのロード。
• JNI_OnLoad()内で行われる処理。
• ネイティブ・アプリケーションの起動。
• main() の実行。

Android UIスレッド

Androidアプリと同様に、UIに影響を与える操作はUIスレッドで実行されることが期待されています。Qtは、UIで実行されることが期待される内部コールのために、フードの下でそれを行います。また、Qt は C++ コードからこのスレッドで操作を実行するための APIrunOnAndroidMainThread() を提供しています。このAPIを使用することで、Qtは、アプリがActiveであれば呼び出しが直接スレッドにポストされるタイミングを管理し、アプリが一時停止中またはバックグラウンドであればキューに入れられます。

アーキテクチャ

Qt クラス

次のセクションでは、さまざまな Qt Android クラスとその機能、Qt アプリケーションでの役割について説明します。

パブリックJavaバインディング

これらのクラスは、アクティビティ、サービス、アプリケーションのようなユーザー向けクラスの内部実装の詳細をラップするパブリッククラスです。これらのクラスは Qt Android アプリでデフォルトで使用され、Android マニフェスト ファイルで参照されます。ビルドシステムとデプロイツールは、ビルドにこれらのクラスを含めるようにします。

ユーザーはこれらのクラスを使用して、デフォルトの動作を変更または拡張できます。たとえば、onCreate() の下にユーザー定義のカスタム・ロジックを追加するには、以下を使用します：

public class MyActivity extends QtActivity
{
    @Override
    protected void onCreate(Bundle bundle)
    {
        // code before Qt is initialized
        super.onCreate(bundle);
        // code after Qt is initialized
    }
}

テーマの設定

QtActivityを拡張する場合、setTheme()を使用して特定のAndroidテーマを設定できます。ただし、Qtはデフォルトでテーマを設定するため、親クラスのonCreate()を呼び出す前にテーマを設定する必要があります。例えば

@Override
protected void onCreate(Bundle bundle)
{
    setTheme(android.R.style.Theme_DeviceDefault_DayNight);
    super.onCreate(bundle);
}

Android 10 以降のデフォルトでは、Qt はテーマTheme_DeviceDefault_DayNight Style を設定し、それ以前のバージョンではTheme_Holo_Light Styleを設定します。

アプリケーションパラメータを追加する

Java/Kotlin からアプリケーションの(main()) 関数に渡される引数であるアプリケーションパラメータを追加するには、QtActivity を拡張した後で次のようにします：

@Override
protected void onCreate(Bundle bundle)
{
    appendApplicationParameters("--flag value");
    super.onCreate(bundle);
}

これは、CMake変数QT_ANDROID_APPLICATION_ARGUMENTSを直接使用するのと似ています。どちらの方法で渡されたパラメータも、区切り文字としてスペースまたはタブを使用できます。アプリケーションに渡されたパラメータの最終リストは、QProcess::splitCommand を使用して解析されます。

QtLoader による Qt ライブラリのロード

すべての Qt Android アプリは、ネイティブ Qt ライブラリまたはサードパーティ・ライブラリが、それらのモジュールから機能を呼び出す前に、最初にロードされていることを確認する必要があります。ビルドシステムは、アプリケーションのlibs.xmlリソースファイルの下に、様々な Qt ライブラリの依存関係、QPA プラグイン、メインアプリライブラリ、サードパーティライブラリのリストを保持します。以下のセクションで説明する前提条件がすべて完了すると、System.load() を使用してライブラリがロードされます。

クラス・ローダー

クラスローダオブジェクトは、Qt ライブラリのロードやデリゲートの初期化を行う前に、QtLoader によって初期設定されます。これは、クラス・ローダーがQJniObject 、Javaクラスを見つけるために使用され、QJniObject でJNIコールを行う際に必要となるためです。

環境変数とアプリケーション・パラメーターの設定

ライブラリをロードする前に、Qt は環境変数が Android マニフェストのメタデータとして渡され、設定されていることを確認する必要があります。このステップにより、マニフェストのメタデータとして設定された設定フラグに基づいて、いくつかのモジュールの初期化が可能になります。このメタデータの一部は、アプリケーションの起動時に渡されるアプリケーション パラメータ リストにも反映されます。

setActivity()、setContext()、および setService()。

様々なQtモジュールが、Activityや Serviceのコンテキストを必要とする初期化作業をJava側から行う必要があるかもしれません。それらのモジュールは、アクティビティ、サービス、またはコンテキストをパラメータとして受け取る静的メソッドを実装します：

void setActivity(Activity activity)
{
    m_activity = activity;
    // Other logic
}

そして、QtLoader 、ネイティブ共有ライブラリをロードする直前に、ローダーの親コンテキストでこれらのメソッドを呼び出します。

Qt for Android が Android Activity のライフサイクルを処理する方法

Qt for Androidは、onCreate()、onStart()、onResume()、onPause()、onStop()、onDestroy()といったAndroidアクティビティのライフサイクル・コールバックを直接処理するAPIを提供していません。その代わりに、これらの処理をユーザーのために裏で行います。動作の概要は以下のセクションで説明します。

コンテキスト処理

QAndroidApplication Androidシステムとの対話に不可欠なAndroidコンテキストを QJniObject 。このコンテキストは、アクティビティまたはサービスになります。アクティビティがある場合は、サービスの有無にかかわらず、最も最近開始されたアクティビティとなる。サービスしかない場合は、最近起動したサービスになります。

コールバック

QtActivityBaseクラスは、Activityの様々な機能の実装の詳細をQt for Androidパッケージ内で非公開にするために設計されています。このクラスはAndroidのライフサイクルとQtフレームワークの仲介役となり、AndroidのライフサイクルのコールバックをQtアプリケーションが応答できるシグナルや操作に変換します。

onCreate()

Activityが作成されると、QtActivityBaseはQt環境を初期化します。これには、Qt ライブラリのロード、QJniObject が使用するクラスローダのセットアップ、アプリのメタデータの解析、Qt アプリケーションの実行準備などが含まれます。アクティビティに固有の必要な初期化がすべて処理されるようにします。

onStart()

AndroidのActivity.OnStart()を呼び出します。

onResume()

Activityがフォアグラウンドに移動すると、QtActivityBaseはQtアプリケーションを再開します。一時停止していたプロセスや操作が継続され、アプリケーションが再びユーザーとのインタラクションに対応できるようになります。onPause()で停止したディスプレイマネージャリスナーを再登録します。

onPause()

他のActivityが部分的にActivityを見えなくする場合、QtActivityBaseはQtアプリケーションを一時停止します。アプリケーションがフォアグラウンドでない間、アプリケーションの状態を保存したり、不要なリソースを解放したりします。

onStop()

アクティビティが表示されなくなると、QtActivityBase は Qt アプリケーションを停止し、より大規模な状態の保存とリソースの解放を行い、アプリケーションを破棄する準備をします。

onDestroy()

Activityが終了するか、システムによって破棄される場合、QtActivityBaseはQtアプリケーションに関連するすべてのリソースをクリーンアップします。これは、適切なシャットダウンと、必要なクリーンアップ処理の実行を保証します。

この統合により、QtActivityBase が複雑な Android ライフサイクルを管理するため、開発者は心配することなく Qt アプリケーションの開発に集中することができます。

スプラッシュ画面の管理

QAndroidApplication QtActivityBase は、アプリケーションの起動シーケンス（通常は onCreate() の後）に合わせて、スプラッシュ画面をフェード効果で隠すことができます。

Qt for Android の詳細

2021 Qt World Summit のビデオでは、Qt for Android の概要が紹介されています。

"YouTube動画にリンクしているアジェンダの写真"