Qt for Androidの仕組み

QtがAndroidプラットフォームをどのようにサポートしているかについて、概要を知りたい開発者の皆様には、このページが役立ちます。

Qt アプリケーションの起動

ネイティブの Android アプリと同様に、アプリが起動されアクティビティが作成されると、Qt のメインアクティビティのonCreate() が早い段階で呼び出されます。ここで、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間の双方向におけるさまざまなイベントおよびシグナルの伝播を処理します。その役割には、シグナル処理、タッチイベント、UI要素、レンダリングなどが含まれます。また、このレイヤーは、アプリの起動時の初期化や、アプリの終了または破棄時のクリーンアップも担当します。

スレッド

Android向けQtアプリにおいて、Qtでは通常、2つのスレッドが重要となります。1つ目は、Qtが起動するQtThread です。2つ目は、AndroidのUIスレッドです。

QtThread

このスレッドは、例えばライブラリの読み込みなどを行う前に、Qtアプリによって最初に実装および起動されます。このスレッドはqtMainLoopThread と呼ばれます。以下のすべての操作は、このスレッドの下で実行されます：

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

AndroidのUIスレッド

Android アプリと同様に、UI に影響を与える操作は UI スレッドで実行されることが想定されています。Qt は、UI で実行されることが想定される内部呼び出しについて、内部でこれを処理します。 また、Qt には、C++ コードからこのスレッドで操作を実行するための APIrunOnAndroidMainThread() が用意されています。この API を使用すると、Qt は、アプリがアクティブな場合は呼び出しをスレッドに直接投稿し、アプリが一時停止中またはバックグラウンドにある場合はキューに入れるといった処理を管理します。

アーキテクチャ

Qt クラス

以下のセクションでは、Android 向け Qt のさまざまなクラスと、それらの機能および Qt アプリケーションにおける役割について解説します。

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

これらのクラスは、Activity、Service、Application といったユーザー向けのクラスの内部実装の詳細をラップするパブリッククラスです。これらのクラスは、Qt Android アプリでデフォルトで使用され、Android マニフェストファイルで参照されます。ビルドシステムとデプロイメントツールが、これらをビルドに組み込む処理を自動的に行います。

ユーザーはこれらのクラスを使用して、デフォルトの挙動を変更したり拡張したりできます。例えば、`QtActivity` は `Activity ` を拡張し、Qt ライブラリの読み込みや、Android と Qt 間のイベントおよびネイティブ呼び出しの処理に必要なロジックを実装しています。

QtとAndroid間のさまざまなイベントや呼び出しに対してQtの実装を必要とする場合は、通常、QtActivity を継承する必要があります。それ以外の場合は、Activity を継承すれば問題ありません。

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スタイルを、それ以前のバージョンではTheme_Holo_Lightスタイルを設定します。

アプリケーションパラメータの追加

追加のアプリケーションパラメータ（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 for Android アプリでは、ネイティブの Qt ライブラリやサードパーティ製ライブラリの機能を呼び出す前に、それらのモジュールが確実に読み込まれている必要があります。 ビルドシステムは、さまざまな Qt ライブラリの依存関係、QPA プラグイン、メインアプリライブラリ、およびサードパーティ製ライブラリのリストを、アプリケーションのlibs.xmlリソースファイルに保持しています。以下のセクションで説明するすべての前提条件が完了すると、System.load() を使用してライブラリが読み込まれます。

クラスローダー

クラスローダーオブジェクトは、Qtライブラリの読み込みやデリゲートの初期化が行われる前に、QtLoader によって早期に設定されます。これは、クラスローダーがQJniObject によってJavaクラスの検索に使用されるほか、QJniObject を使用したJNI呼び出しを行うために必要となるためです。

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

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

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

さまざまな Qt モジュールでは、Java 側から初期化処理を行う必要があり、その際にActivityやService のコンテキストが必要になる場合があります。そのようなモジュールでは、Activity、Service、または Context をパラメータとして受け取る静的メソッドを実装します。

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

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

Qt for Android による Android アクティビティのライフサイクルの処理方法

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()

アクティビティが作成されると、QtActivityBaseはQt環境を初期化します。これには、Qtライブラリの読み込み、QJniObject が使用するクラスローダーの設定、アプリのメタデータの解析、およびQtアプリケーションの実行準備が含まれます。これにより、そのアクティビティ固有の必要な初期化処理がすべて確実に実行されます。

onStart()

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

onResume()

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

onPause()

別のアクティビティによってこのアクティビティが部分的に隠された場合、QtActivityBase は Qt アプリケーションを一時停止します。これにより、アプリケーションの状態が保存されるほか、アプリケーションがフォアグラウンドにない間に不要となるリソースが解放されます。

onStop()

アクティビティが画面上に表示されなくなると、QtActivityBase は Qt アプリケーションを停止します。これには、より広範囲な状態の保存とリソースの解放が含まれ、アプリケーションが破棄される可能性に備えます。

onDestroy()

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

この統合により、QtActivityBase が内部でこれらの複雑な処理を管理するため、開発者は Android のライフサイクルの複雑な仕組みを気にすることなく、Qt アプリケーションの構築に集中することができます。

スプラッシュスクリーンの管理

QAndroidApplication は、フェード効果を使ってスプラッシュスクリーンを非表示にすることができます。このフェード効果は、アプリケーションの起動シーケンス（通常は onCreate() の後）に合わせてタイミングを調整できます。

Qt for Androidの詳細

2021年の Qt World Summit で公開された動画では、Qt for Android の概要が紹介されています。

「YouTube 動画にリンクされたアジェンダの画像」