Qt Quick Android-Klasse anzeigen
Mit der QtQuickView-Klasse können Sie QML-Inhalte ganz einfach als View zu Ihrer Android-App hinzufügen.
Klasse: | QtQuickView |
Paketname: | org.qtproject.qt.android |
Erweitert: | org.qtproject.qt.android.QtView - org.qtproject.qt.android.QtLayout -- android.view.ViewGroup |
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
Warnung: Die Wiederherstellung von Aktivitäten kann zu einem Absturz führen. Dies ist darauf zurückzuführen, dass die Ressourcen nicht ordnungsgemäß freigegeben werden.
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; }
Hinweis: Das Hinzufügen eines QtQuickViews aus einem Service-Kontext erfordert, dass Ihre Anwendung die Berechtigung SYSTEM_ALERT_WINDOW hat und mit dem Plattformschlüssel signiert ist.
Hinweis: QML-Ansichten, die in einen Service-Kontext eingebettet sind, unterstützen keine Tastatureingaben oder Barrierefreiheitsfunktionen.
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.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.