Qt Quick Android-Klasse anzeigen

Mit der QtQuickView-Klasse können Sie QML-Inhalte ganz einfach als View zu Ihrer Android-App hinzufügen.

Detaillierte Beschreibung

Mit der QtQuickView-Klasse können Sie QML-Inhalte einfach als View zu Ihrer Android-App hinzufügen. QtQuickView instanziiert eine QQuickView mit einer gegebenen QML-Komponentenquelle (eine lokale oder Netzwerkdatei) und bettet sie in sich selbst ein. Sie können sie wie jede andere Ansicht in das Layout Ihrer Android-App einfügen. QtQuickView ist eine gute Wahl, wenn Sie Ihre Nicht-Qt-Android-App mit QML-Inhalten erweitern möchten, aber nicht die gesamte App mit dem Qt-Framework erstellen wollen. Es bringt die Leistungsfähigkeit von Qt Quick in Ihre Android-App und macht es möglich, verschiedene Qt Quick APIs in Android-Apps zu verwenden.

Eine typische Anwendung der Klasse:

import org.qtproject.qt.qml.target.Main;
...

private Main m_mainQmlContent;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    ...
    m_mainQmlContent = new Main();
    QtQuickView qmlView = new QtQuickView(this);

    layout.addView(qmlView, params);

    qmlView.loadContent(m_mainQmlContent);
    ...
}

Notwendige Änderungen in main.cpp im Vergleich zu einer Qt for Android-Anwendung

QtQuickView kümmert sich um die Erstellung des Fensters der Anwendung und das Laden von QML-Inhalten. Die Hauptfunktion des QML-Projekts, das Sie in Ihr Android-Projekt einbetten, sollte beides nicht tun. Das Erstellen von QGuiApplication und starting the event loop ist ausreichend. Im Folgenden finden Sie die Mindestanforderungen an main.cpp für Ihr QML-Projekt.

#include <QGuiApplication>

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

Ein ausführlicheres Beispiel finden Sie unter Qt Quick für Android Studio Projekte.

Bekannte Probleme

Hier sind die bekannten Probleme mit dieser API. Sie werden möglicherweise in einem Patch-Release behoben und entfernt.

Die Wiederherstellung von Aktivitäten führt zu einem Absturz der Anwendung

Durch Ausrichtungsänderungen und andere Konfigurationsänderungen wird die Aktivität neu erstellt.

Siehe {https://bugreports.qt.io/browse/QTBUG-123711}{QTBUG-123711} für weitere Informationen.

Unter Qt Quick für Android Studio-Projekte finden Sie ein Beispiel dafür, wie die Rotation innerhalb einer Anwendung manuell gehandhabt werden kann, ohne die Activity neu zu erstellen.

QtQuickView in einem Android-Dienst

Es ist auch möglich, eine QtQuickView aus einem Service-Kontext heraus hinzuzufügen, indem man die Android WindowManager-Schnittstelle verwendet:

import org.qtproject.qt.qml.target.Main;
...
private Main m_mainQmlContent;
@Override
public void onCreate() {
    m_windowManager = getSystemService(WindowManager.class);

    m_mainQmlContent = new Main();
    QtQuickView qmlView = new QtQuickView(this)

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

    qmlView.loadContent(m_mainQmlContent);
}

Um die QtQuickView- und Qt-Bibliotheken zu bereinigen, kann die onDestroy()-Lifecycle-Funktion verwendet werden:

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

Mehrere QtQuickViews in einer Aktivität

Das gleichzeitige Instanziieren mehrerer QtQuickViews ist ebenfalls möglich:

import org.qtproject.qt.qml.target.Main;
import org.qtproject.qt.qml.target.Second;
...

private Main m_mainQmlContent;
private Second m_secondQmlContent;

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

    m_mainQmlContent = new Main();
    m_secondQmlContent = new Second();

    QtQuickView qmlView = new QtQuickView(this);
    QtQuickView secondQmlView = new QtQuickView(this);

    layout.addView(qmlView, params);
    layout.addView(secondQmlView, secondParams);

    qmlView.loadContent(m_mainQmlContent);
    secondQmlView.loadContent(m_secondQmlContent);
    ...
}

Die Konstruktoren

public QtQuickView(Context übergeordnet, String qmlUri, String appName)

Erzeugt eine QtQuickView zum Laden und Rendern einer QML Komponente. Die Instanziierung einer QtQuickView lädt die Qt-Bibliotheken, einschließlich der durch appName angegebenen Anwendungsbibliothek. Anschließend wird eine QQuickView erstellt, die die durch qmlUri angegebene QML-Quelle lädt.

Parameter

• context: der übergeordnete Context.
• qmlUri: die URI der Haupt-QML-Datei.
• appName: der Name der zu ladenden und zu startenden Qt-Anwendungsbibliothek. Dies entspricht dem Zielnamen, der in der CMakeLists.txt der Qt-App festgelegt ist.

Wirft

Löst eine InvalidParameterException aus, wenn ein Parameter ungültig ist.

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

Erzeugt eine QtQuickView zum Laden und Anzeigen einer QML-Komponente. Die Instanziierung einer QtQuickView lädt die Qt-Bibliotheken, einschließlich der durch appName angegebenen Anwendungsbibliothek. Dann wird eine QQuickView erstellt, die die durch qmlUri angegebene QML-Quelle lädt. Diese Überladung akzeptiert ein Array von Strings qmlImportPaths für den Fall, dass die QML-Anwendung QML-Module aus benutzerdefinierten Pfaden laden soll.

Parameter

• context: der übergeordnete Context.
• qmlUri: die URI der Haupt-QML-Datei.
• appName: der Name der zu ladenden und zu startenden Qt-Anwendungsbibliothek. Dies entspricht dem Zielnamen, der in der CMakeLists.txt der Qt-App gesetzt ist.
• qmlImportPaths: ein Array von Strings für zusätzliche Importpfade, die übergeben werden.

Wirft

Löst eine InvalidParameterException aus, wenn ein Parameter ungültig ist.

Schnittstellen

öffentliche Schnittstelle SignalListener<T>

Wird im Android UI-Thread aufgerufen, wenn das Signal ausgesendet wurde.

Parameter

• signalName: Literaler Signalname
• value: der vom Signal gelieferte Wert oder null, wenn das Signal keinen Parameter hat.

öffentliche Schnittstelle StatusChangeListener

Wird auf dem Android UI-Thread aufgerufen, wenn sich der Status der QML-Komponente geändert hat.

Parameter

• Status: Der aktuelle Status.

Felder

Status-Werte

Der Status kann STATUS_NULL, STATUS_READY, STATUS_LOADING oder STATUS_ERROR sein. Für weitere Informationen siehe QQuickView::Status.

Methoden

public void setProperty(String propertyName, Object value)

Setzt den Wert einer vorhandenen Eigenschaft des QML-Wurzelobjekts. Die unterstützten Typen sind Integer, Double, Float, Boolean, und String. Diese Typen werden in ihre entsprechenden QML-Typen int, double/float, bool und string umgewandelt. Diese Funktion fügt dem QML-Root-Objekt keine Eigenschaften hinzu, wenn sie nicht vorhanden sind.

Parameter

• propertyName: der Name der vorhandenen Eigenschaft des Wurzelobjekts, dessen Wert gesetzt werden soll
• value: der Wert der Eigenschaft

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

Liefert den Wert einer vorhandenen Eigenschaft des QML-Wurzelobjekts. Die unterstützten Rückgabetypen sind Integer, Double, Float, Boolean und String. Diese Typen werden aus ihren entsprechenden QML-Typen int, double/float, bool und string konvertiert.

Parameter

• propertyName: der Name der vorhandenen Stammobjekteigenschaft.

Rückgabe

Existiert die Eigenschaft nicht oder ist der Status der QML-Komponente ein anderer als STATUS_READY, gibt diese Funktion null zurück.

Wirft

Wirft eine ClassCastException, wenn das Typ-Casting fehlschlägt.

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

Verknüpft einen SignalListener mit einem Signal des QML-Wurzelobjekts.

Parameter

• signalName: der Name des Signals des Wurzelobjekts.
• argType: der Klassentyp des Signalarguments.
• listener: eine Instanz der Schnittstelle SignalListener.

Rückgabe

Eine Connection ID zwischen Signal und Listener oder die bestehende Verbindungs-ID, wenn es eine bestehende Verbindung zwischen demselben Signal und Listener gibt. Gibt einen negativen Wert zurück, wenn das Signal im QML-Root-Objekt nicht existiert.

public boolean removeSignalListener(int signalListenerId)

Hält einen SignalListener mit einer gegebenen ID, die durch den Aufruf addSignalListener() ermittelt wurde, davon ab, auf ein Signal zu hören.

Parameter

• signalListenerId: die Verbindungs-ID.

Rückgabe

True, wenn die Verbindungs-ID gültig ist und erfolgreich entfernt wurde, andernfalls wird false zurückgegeben.

public int getStatus()

Ermittelt den Status der QML-Komponente.

Rückgabe

STATUS_READY zurück, wenn die QML bereit ist. Der Aufruf von Methoden, die auf das QML-Root-Objekt wirken, wie setProperty(), getProperty() und addSignalListener(), wäre nur dann erfolgreich, wenn der aktuelle Status STATUS_READY ist. Es können auch andere Statuswerte zurückgegeben werden, die den Status der zugrunde liegenden Instanz QQuickView darstellen.

public void setStatusChangeListener(StatusChangeListener listener)

Setzt einen StatusChangeListener, um auf Statusänderungen zu hören.

Parameter

• listener: eine Instanz der Schnittstelle StatusChangeListener.