C

ActivityView QML Type

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

Import Statement:	`import QtAndroidActivityView`
Since:	Qt 6.3
Inherits:	Item

Properties

activitySize() : size
className : string
fillMode : enumeration
packageName : string
placeholder : Item
restoreOnAppResume : bool
status : enumeration
usePlaceholder : bool

Methods

void resetActivitySize()
void restore()

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 needs special permissions and also relies on private Android APIs, apps that use it must be signed with a platform key.

Android 10

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.

Property Documentation

activitySize() : size

This property holds the info about the desired size of the activity. If it is empty, the activity size will be bound to this item size.

Note: The actual Android activity size will be in device coordinates, not in device-independent pixels. This means that even if High-DPI scaling is active (with a scale factor larger than 1.0), the Android activity will still be created using device coordinates.

See also fillMode.

className : string

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.

fillMode : enumeration [read-only]

This property holds the fillMode of the underlaying ActivityView texture.

Constant	Description
`ActivityView.Stretch`	The activity is scaled to fit.
`ActivityView.PreserveAspectFit`	The activity is scaled uniformly to fit without cropping.

Note: If the activitySize is not set, setting this property has no effect. In another word, scaling happens only when the activitySize differs from the Item size.

See also activitySize.

packageName : string

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 Activity View 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.

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.

Constant	Description
`ActivityView.NotInitialized`	The 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.Ready`	The 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.Starting`	The activity defined by package/class names is currently being started.
`ActivityView.Started`	The 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 resetActivitySize()

If activity size value has changed to null, sets the size values to 0, updates the values and triggers emit that the activity size has changed.

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.