ActivityView QML Type

QML wrapper for Qt Android Activity View. More...

Import Statement: import QtAndroidActivityView
Since: Qt 6.3



Detailed Description

ActivityView allows embedding and handling Android apps and activities from a QML component.

Example Usage

The following snippet shows the simplest usage of the ActivityView type.

import QtAndroidAutomotive.ActivityView

ActivityView {
    anchors.fill: parent

    packageName: "com.android.deskclock"

Activity View Known issues and limitations

Since ActivityView relies on private Android APIs, apps that use it must be signed with a platform key.

An ActivityView component is always rendered on top. It can be freely changed in size and position. However, the standard z-order rules do not apply. It is always rendered above all components rendered by QML. Additionally, it is also not possible to apply transformations such as rotation or scaling, changing the opacity or offscreen rendering using layers.

The Activity resolved by the provided packageName and className must have the resizeableActivity attribute set to true in order to be launched correctly as an embedded activity. Also, if the activity is not owned by the owner of this app, it must allow embedding. This rule also applies to activities launched from within embedded activities. Otherwise, new activities may not behave correctly, e.g. be launched in fullscreen.

Android 10 and 11

In case of Android 11 platform only one ActivityView can get touch events at a time. When working with multiple ActivityViews, the user will have to make an 'initial tap' on the activity to give it focus for receiving touch events.

When an activity is running in ActivityView, an attempt to run the same activity with Context.startActivity() may not show the activity on the screen. To overcome this problem, use the two parameter version of this function, so you can specify the displayId for the activity to show up.

Android 12 and 13

Only one app can successfully use ActivityViews

Due to the limitations in the these underlying Android API versions, only one app can successfully use ActivityViews for embedding other apps. If another app with an ActivityView is launched, the previously launched app's activity embedding may not work as expected anymore.

Activity that is embedded may not show outside the host app

When an Activity has been embedded into an ActivityView, trying to start the same Activity outside of it, in fullscreen mode, may not show the Activity on the screen. If you want to start the embedded Activity in fullscreen, you need to remove it from the ActivityView first by clearing its packageName.

Note: Because of these issues ActivityView should not be considered a general-purpose API. Apps to be embedded should be written with this criteria taken in mind. In the case of external apps, they should be thoroughly tested, especially in terms of starting new activities.

Keyboard input not working

Soft and physical keyboard input in apps with embedded ActivityViews does not work, no text can be entered and a virtual keyboard does not appear.

Note: Text input works as expected inside the app that has been embedded using an ActivityView.

Property Documentation

className : QString

This property holds the name of the class inside of the package defined by the packageName property. When defined, the specified class is used to start the activity, otherwise the default class for given package is used, appropriate to launch a main activity in a package.

The name of the class must be specified using the full package destination:

ActivityView {
    anchors.fill: parent

    packageName: "com.android.contacts"
    className: "com.android.contacts.activities.LicenseActivity"

However, if the first character in the className property value is a period, the app's package name (packageName property) is prefixed to the name. Therefore, the following example runs the same activity as the example above:

ActivityView {
    anchors.fill: parent

    packageName: "com.android.contacts"
    className: ".activities.LicenseActivity"

See also packageName.

packageName : QString

This property holds the name of the package of the Activity that is intended to be run inside the component.

The Activity resolved by the provided packageName and className must meet certain criteria. Check out Known issues and limitations section for details.

See also className.

placeholder : Item

This property holds the placeholder item to be displayed instead of the activity.

The example below demonstrates how to use the placeholder when the ActivityView is moved:

Rectangle {
    width: 400
    height: 600
    border.width: 1

    MouseArea {
        id: dragMouseArea

        anchors.fill: parent
        drag.target: parent

    ActivityView {
        id: activityView

        anchors.fill: parent
        anchors.margins: 30

        packageName: "com.android.deskclock"
        usePlaceholder: dragMouseArea.pressed

        placeholder: Item {
            Image {
                anchors.centerIn: parent
                source: "icon.png"
                width: 50
                height: 50

Note: The content item is automatically positioned and resized to fit within the ActivityView. Bindings to the x, y, width, and height properties of the contentItem are not respected.

See also usePlaceholder.

radius : float

This property holds the corner radius of the ActivityView, in pixels. The same radius is used by all 4 corners.

An additional rectangle with the same radii can be used to create a frame around the ActivityView:

Rectangle {
    anchors.fill: parent
    radius: 20

    ActivityView {
        anchors.fill: parent
        anchors.margins: 1
        radius: 20

        packageName: "com.android.contacts"

restoreOnAppResume : bool

This property holds whether the embedded activity should be restored in case it was closed or run somewhere else during app's non-active state. By default this is true.

status : enumeration [read-only]

This property holds the status of the controlled ActivityView.

ActivityView.NotInitializedThe component instance is not yet initialized. Initialization is in progress and must complete before any activity can run. This process involves allocating the appropriate resources, such as creating a Surface. Initialization is done once for each instance of the ActivityView component.
ActivityView.ReadyThe component instance is initialized, but valid package/class names are not set. After setting a valid package/class name, the activity will be launched immediately.
ActivityView.StartingThe activity defined by package/class names is currently being started.
ActivityView.StartedThe activity has been started.
ActivityView.RemovedExternally (since Qt 6.4)The activity has has been removed from this ActivityView. This happens whenever the app is active and the activity has been run somewhere else or has closed. Second case is when the app is not active (suspended ,for example), restoreOnAppResume is set to false and the activity is run somewhere else or has closed.

Use this status to provide an update or respond to the status change in some way. For example, you could bind to the status value:

BusyIndicator {
    running: activityView.status !== ActivityView.Started

usePlaceholder : bool

This property holds whether the placeholder is displayed instead of the actual ActivityView. By default this is false.

See also placeholder.

Method Documentation

void restore()

This function reloads the activity that was removed externally from the ActivityView component.

See also restoreOnAppResume and status.

Available under certain Qt licenses.
Find out more.