QtクイックビューAndroidクラス

QtQuickView クラスを使うと、Android アプリに QML コンテンツをView として簡単に追加できます。

詳しい説明

QtQuickView クラスを使うと、Android アプリに QML コンテンツをView として簡単に追加することができます。QtQuickView は、指定された QML コンポーネントソース（ローカルファイルまたはネットワークファイル）を使ってQQuickView をインスタンス化し、自分自身に埋め込みます。QtQuickView は、非 Qt Android アプリを QML コンテンツで拡張したいが、アプリ全体を Qt フレームワークで作りたくない場合に適しています。Qt QuickのパワーをAndroidアプリにもたらし、Androidアプリで様々なQt Quick APIを使用できるようにします。

このクラスの典型的な使い方

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    ...

    QtQuickView qmlView = new QtQuickView(this, "qrc:/qt/qml/target/main.qml", "target");
    qmlView.setStatusChangeListener(status -> {
        Log.i(TAG, "QML loading status changed to " + status);
    });

    // Add QML to your layout
    layout.addView(qmlView, params);
    ...
}

Qt for Android アプリと比較した場合の main.cpp の変更点

QtQuickViewは、アプリのウィンドウの作成とQMLコンテンツの読み込みを行います。Androidプロジェクトに埋め込むQMLプロジェクトのmain関数は、どちらの処理も行うべきではありません。QGuiApplication とstarting the event loop を作成すれば十分です。以下は、QMLプロジェクトに最低限必要なmain.cpp 。

#include <QGuiApplication>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    return app.exec();
}

より詳細な例については、Qt Quick for Android Studio Projectsを参照してください。

既知の問題

このAPIに関する既知の問題です。これらはパッチリリースで解決され、削除される可能性があります。

アクティビティの再現がアプリケーションのクラッシュにつながる

向きやその他の設定を変更すると、アクティビティが再作成されます。

詳細は{https://bugreports.qt.io/browse/QTBUG-123711}{QTBUG-123711}を参照してください。

Activityを再作成せずにアプリケーション内部で回転を手動で処理する方法の例については、Android StudioプロジェクトのQMLを参照してください。

1つのアプリケーションに複数のQtQuickViewがあると未定義の動作が発生する

1つのアプリケーションで複数のQtQuickViewを使用すると、クリーンアップ時に未定義の動作が発生することがあります。アプリケーションレイアウトからQtQuickViewを削除するとクラッシュすることがあります。

詳細は{https://bugreports.qt.io/browse/QTBUG-127422}{QTBUG-127422}を参照してください。

Androidサービス内のQtQuickView

AndroidのWindowManagerインターフェイスを使って、ServiceコンテキストからQtQuickViewを追加することも可能です：

@Override
public void onCreate() {
    m_windowManager = getSystemService(WindowManager.class);
    m_qtView = new QtQuickView(this, "qrc:/qt/qml/target/main.qml", "target");
    WindowManager.LayoutParams layoutParams = new WindowManager.LayoutParams(
            640, 320,
            WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY,
            WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS,
            PixelFormat.TRANSLUCENT);
    m_windowManager.addView(m_qtView, layoutParams);
}

QtQuickViewとQtライブラリをクリーンアップするには、onDestroy()ライフサイクル関数を使用します：

@Override
public void onDestroy() {
    super.onDestroy();
    m_windowManager.removeView(m_qtView);
    m_qtView = null;
}

コンストラクタ

public QtQuickView(Context parent, String qmlUri, String appName)

QMLコンポーネントをロードしてレンダリングするQtQuickViewを作成します。QtQuickViewのインスタンスは、appNameで指定されたアプリライブラリを含むQtライブラリを読み込みます。次に、qmlUriで指定されたQMLソースをロードするQQuickView 。

パラメータ

• context: 親コンテキスト。
• qmlUri: メインのQMLファイルのURI。
• appName: ロードして起動するQtアプリのライブラリ名。これは、QtアプリのCMakeLists.txtで設定されたターゲット名に対応します。

スロー

パラメータが無効な場合にInvalidParameterException をスローします。

public QtQuickView(Context context, String qmlUri, String appName, String[] qmlImportPaths)

QMLコンポーネントを読み込み、表示するためのQtQuickViewを作成します。QtQuickViewのインスタンスは、appNameで指定されたアプリライブラリを含むQtライブラリを読み込みます。次に、qmlUriで指定されたQMLソースをロードするQQuickView 。このオーバーロードは、QMLアプリケーションがカスタムパスからQMLモジュールをロードする場合に、文字列qmlImportPathsの配列を受け入れます。

パラメータ

• context: 親コンテキスト。
• qmlUri: メインの QML ファイルの URI。
• appName: ロードして起動するQtアプリのライブラリ名。これは、Qt アプリの CMakeLists.txt で設定されたターゲット名に対応します。
• qmlImportPaths: 追加のインポートパスを渡す文字列の配列。

スロー

パラメータが無効な場合にInvalidParameterException をスローします。

インターフェイス

public interface SignalListener<T>.

シグナルが発信されたときに Android UI スレッドで呼び出されます。

パラメータ

• signalName: シグナル名（リテラル
• value: シグナルによって配信される値、またはシグナルにパラメータがない場合はNULL。

public interface StatusChangeListener

QML コンポーネントのステータスが変更された時、Android UI スレッドで呼び出されます。

パラメータ

• status：現在のステータス。

フィールド

ステータスの値

ステータスは、STATUS_NULL、STATUS_READY、STATUS_LOADINGまたはSTATUS_ERROR のいずれかである。詳細はQQuickView::Status を参照。

メソッド

public void setProperty(String propertyName, Object value)

QML ルートオブジェクトの既存のプロパティの値を設定します。対応する型はInteger,Double,Float,Boolean,String です。これらの型は対応する QML の型 int, double/float, bool, string に変換されます。QML ルートオブジェクトにプロパティが存在しない場合、この関数はプロパティを追加しません。

パラメータ

• propertyName: 値を設定するルートオブジェクトのプロパティ名。
• value: プロパティの値。

public <T extends Object> T getProperty(String propertyName)

QML ルートオブジェクトの既存のプロパティの値を取得します。対応する戻り値の型はInteger,Double,Float,Boolean,String です。これらの型は、対応する QML の型 int, double/float, bool, string から変換されます。

パラメータ

• propertyName: 既存のルート・オブジェクトのプロパティ名。

戻り値

プロパティが存在しない場合、または QML コンポーネントの状態がSTATUS_READY 以外の場合、この関数は null を返します。

スロー

型のキャストに失敗した場合にClassCastException をスローします。

public <T> int addSignalListener(String signalName, Class<T> argType, SignalListener<T> listener)

SignalListenerをQMLルートオブジェクトのシグナルに関連付けます。

パラメータ

• signalName: ルートオブジェクトのシグナル名。
• argType: シグナルの引数のクラス型。
• listener: SignalListenerインターフェースのインスタンス。

戻り値

シグナルとリスナーの間のConnection ID または、同じシグナルとリスナーの間に既存の接続がある場合は、既存の接続ID。QML ルートオブジェクトにシグナルが存在しない場合は負の値を返す。

public boolean removeSignalListener(int signalListenerId)

addSignalListener()の呼び出しで取得した指定された ID を持つSignalListenerがシグナルをリスンするのを停止します。

パラメータ

• signalListenerId: 接続ID。

戻り値

接続IDが有効で、正常に削除された場合はtrueを返し、そうでない場合はfalseを返します。

パブリック int getStatus()

QMLコンポーネントのステータスを取得します。

戻り値

STATUS_READYは QML の準備ができたことを示す。setProperty(),getProperty(),addSignalListener() などの QML ルートオブジェクトを操作するメソッドは、現在のステータスがSTATUS_READY の場合にのみ成功します。また、QQuickView インスタンスのステータスを表す他のステータス値を返すこともできます。

public void setStatusChangeListener(StatusChangeListener listener)

ステータスの変更をリッスンするStatusChangeListenerを設定する。

パラメータ

• listener:StatusChangeListenerインターフェースのインスタンス。