- Qt 6.8
- Qt Quick
- Qt Quick View Android Class
- Qt 6.8.1 Reference Documentation

# Qt Quick View Android Class

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

Class: | QtQuickView
Package Name: | org.qtproject.qt.android
Extends: | org.qtproject.qt.android.QtView – org.qtproject.qt.android.QtLayout –– android.view.ViewGroup

## 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:

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

### 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

Warning: Activity recreation may lead to a crash. This is due to resources not being released properly.

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.

## QtQuickView in an Android Service

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

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

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

Note: Adding a QtQuickView from a Service context requires your application to have the SYSTEM_ALERT_WINDOW permission, and to be signed with the platform key.

Note: QML views embedded within a Service context do not support keyboard input or accessibility features.

## Multiple QtQuickViews in an Activity

Instantiating multiple QtQuickViews at once is also possible:

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

## 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.