Qt Quick View Android Class

The QtQuickView class lets you easily add QML content to your Android app as a View.

Detailed description

The QtQuickView class lets you easily add QML content to your Android app as a View. QtQuickView instantiates a QQuickView with a given QML component source (a local or network file) and embeds it to itself. You can add it to your Android app's layout as with any other View. QtQuickView is a good choice when you want to extend your non-Qt Android app with QML content but do not want to make the entire app using the Qt framework. It brings the power of Qt Quick into your Android app, making it possible to use various Qt Quick APIs in Android apps.

A typical use of the class:

@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);
    ...
}

Changes needed in main.cpp compared to a Qt for Android application

QtQuickView will handle creating the app's window and loading any QML content. The main function of the QML project you are embedding into your Android project shouldn't do either. Creating the QGuiApplication and starting the event loop is enough. Below is the minimum required main.cpp for your QML project.

#include <QGuiApplication>

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

For a more detailed example, see Qt Quick for Android Studio Projects.

Known issues

Here are the known issues with this API. They may be resolved and removed in a patch release.

Activity recreation leads to an application crash

Orientation and other configuration changes will recreate the Activity.

See {https://bugreports.qt.io/browse/QTBUG-123711}{QTBUG-123711} for more information.

See QML in Android Studio Projects for an example of how to handle rotation manually inside an application without recreating the Activity.

Multiple QtQuickViews in one application causes undefined behavior

Using multiple QtQuickViews in one application may cause undefined behavior during cleanup. Removing a QtQuickView from the application layout may cause a crash.

See {https://bugreports.qt.io/browse/QTBUG-127422}{QTBUG-127422} for more information.

QtQuickView in an Android Service

It is also possible to add a QtQuickView from a Service context by using the Android WindowManager interface:

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

To clean up the QtQuickView and Qt libraries, the onDestroy() lifecycle function can be used:

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

Constructors

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

Creates a QtQuickView to load and render a QML component. Instantiating a QtQuickView will load the Qt libraries, including the app library specified by appName. Then, it creates a QQuickView that loads the QML source specified by qmlUri.

Parameters

• context: the parent Context.
• qmlUri: the URI of the main QML file.
• appName: the name of the Qt app library to load and start. This corresponds to the target name set in the Qt app's CMakeLists.txt.

Throws

Throws a InvalidParameterException if a parameter is invalid.

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

Creates a QtQuickView to load and view a QML component. Instantiating a QtQuickView will load the Qt libraries, including the app library specified by appName. Then, it creates a QQuickView that loads the QML source specified by qmlUri. This overload accepts an array of strings qmlImportPaths in the case where the QML application should load QML modules from custom paths.

Parameters

• context: the parent Context.
• qmlUri: the URI of the main QML file.
• appName: the name of the Qt app library to load and start. This corresponds to the target name set in the Qt app's CMakeLists.txt.
• qmlImportPaths: an array of strings for additional import paths to be passed to.

Throws

Throws a InvalidParameterException if a parameter is invalid.

Interfaces

public interface SignalListener<T>

Invoked on the Android UI thread when the signal has been emitted.

Parameters

• signalName: literal signal name
• value: the value delivered by the signal or null if the signal is without a parameter.

public interface StatusChangeListener

Invoked on the Android UI thread when the QML component status has changed.

Parameters

• status: The current status.

Fields

Status values

The status can be STATUS_NULL, STATUS_READY, STATUS_LOADING or STATUS_ERROR. For more information, see QQuickView::Status.

Methods

public void setProperty(String propertyName, Object value)

Sets the value of an existing property on the QML root object. The supported types are Integer, Double, Float, Boolean, and String. These types get converted to their corresponding QML types int, double/float, bool, and string. This function does not add properties to the QML root object if they do not exist.

Parameters

• propertyName: the name of the existing root object property to set its value
• value: the value of the property

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

Gets the value of an existing property of the QML root object. The supported return types are Integer, Double, Float, Boolean, and String. These types get converted from their corresponding QML types int, double/float, bool, and string.

Parameters

• propertyName: the name of the existing root object property.

Returns

If the property does not exist or the status of the QML component is anything other than STATUS_READY, this function will return null.

Throws

Throws a ClassCastException if type casting fails.

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

Associates a SignalListener with a signal of the QML root object.

Parameters

• signalName: the name of the root object signal.
• argType: the Class type of the signal argument.
• listener: an instance of the SignalListener interface.

Returns

A Connection ID between signal and listener or the existing connection ID if there is an existing connection between the same signal and listener. Returns a negative value if the signal does not exist on the QML root object.

public boolean removeSignalListener(int signalListenerId)

Stops a SignalListener with a given id obtained from addSignalListener() call, from listening to a signal.

Parameters

• signalListenerId: the connection ID.

Returns

True if the connection ID is valid and has been successfully removed, otherwise returns false.

public int getStatus()

Gets the status of the QML component.

Returns

STATUS_READY when the QML is ready. Invoking methods that operate on the QML root object, such as setProperty(), getProperty(), and addSignalListener(), would succeed only if the current status is STATUS_READY. It can also return other status values representing the status of the underlying QQuickView instance.

public void setStatusChangeListener(StatusChangeListener listener)

Sets a StatusChangeListener to listen to status changes.

Parameters

• listener: an instance of a StatusChangeListener interface.