C
QActivityView Class
A C++ wrapper for the ActivityView Java class. More...
| Header: | #include <QActivityView> |
| qmake: | QT += androidactivityview |
| Since: | Qt 6.3 |
| Inherits: | QObject |
Public Types
| enum class | Status { NotInitialized, Ready, Starting, Started, RemovedExternally } |
Public Functions
| QActivityView(QObject *parent = nullptr) | |
| virtual | ~QActivityView() |
| QString | activityClassName() const |
| QString | activityPackageName() const |
| float | cornerRadius() const |
| QRect | geometry() const |
| void | initialize() |
| bool | isRestoreOnAppResumeEnabled() const |
| bool | isVisible() const |
| void | restore() |
| void | setActivityName(const QString &packageName, const QString &className = QString()) |
| void | setCornerRadius(float cornerRadius) |
| void | setGeometry(const QRect &geometry) |
| void | setRestoreOnAppResume(bool restore) |
| void | setVisible(bool visible) |
| QActivityView::Status | status() const |
Signals
| void | statusChanged(QActivityView::Status status) |
Detailed Description
QActivityView allows embedding and handling Android apps and activities.
Activity View Known issues and limitations
Only Android 10, 11 and 12 are supported.
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
Only one app can successfully use ActivityViews
Due to the limitations in the underlying Android 12 API, only one app can successfully use ActivityViews for embedding other apps. If another app with 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 in Android 12, 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.
Member Type Documentation
enum class QActivityView::Status
Indicates the status of the managed Activity.
| Constant | Value | Description |
|---|---|---|
QActivityView::Status::NotInitialized | 0 | 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. |
QActivityView::Status::Ready | 1 | 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. |
QActivityView::Status::Starting | 2 | The activity defined by package/class names is currently being started. |
QActivityView::Status::Started | 3 | The activity has been started. |
QActivityView::Status::RemovedExternally (since Qt 6.4) | 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 closes. 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 closes. |
See also status() and statusChanged().
Member Function Documentation
[explicit] QActivityView::QActivityView(QObject *parent = nullptr)
Creates a wrapper for the ActivityView Java class and sets parent as the parent object.
[virtual noexcept] QActivityView::~QActivityView()
Destroys the wrapper object, releasing the underlying Java object of ActivityView class.
QString QActivityView::activityClassName() const
Returns the class name of the activity.
See also setActivityName().
QString QActivityView::activityPackageName() const
Returns the package name of the activity.
See also setActivityName().
float QActivityView::cornerRadius() const
Returns the corner radius of the managed Activity expressed in pixels.
See also setCornerRadius().
QRect QActivityView::geometry() const
Returns the position and size of the managed Activity expressed in the global coordinate system.
See also setGeometry().
void QActivityView::initialize()
Initializes underlying Java resources, such as creating a Surface. It requires setGeometry to be called first. Subsequent calls have no effect.
bool QActivityView::isRestoreOnAppResumeEnabled() const
Returns whether an activity lost during app's inactive state should be restored.
See also setRestoreOnAppResume().
bool QActivityView::isVisible() const
Returns whether the managed Activity is visible. By default this is true.
See also setVisible().
void QActivityView::restore()
Reloads the embedded activity if it was removed externally from the ActivityView.
void QActivityView::setActivityName(const QString &packageName, const QString &className = QString())
Sets the package name and the class name of the activity to be launched. The packageName must be specified using the full package name. The className is an optional argument specifying the name of a class inside of the application package. When the class name is not provided the default class is the one that is appropriate to launch a main activity in a package:
activityView.setActivityName("com.android.deskclock");
The class name can be specified using its full name:
activityView.setActivityName("com.android.deskclock", "com.android.deskclock.settings.SettingsActivity);
However, if the first character in the className property value is a period, the packageName is prefixed to the className. The snippet above can be shortened to the following form:
activityView.setActivityName("com.android.deskclock",
".settings.SettingsActivity);If the component is initialized, the activity starts immediately. Otherwise, startup is postponed until initialization.
The Activity resolved by the provided packageName and className must meet certain criteria. Check out Known issues and limitations section for details.
See also activityPackageName(), activityClassName(), and initialize().
void QActivityView::setCornerRadius(float cornerRadius)
Sets the corner radius for the managed Activity. The corners will be cropped from the window painted by the contained Activity. cornerRadius is expressed in pixels. The same radius is used by all 4 corners.
See also cornerRadius().
void QActivityView::setGeometry(const QRect &geometry)
Sets the position and size of the component on the screen. The x and y coordinates of geometry are in the global coordinate system. This first call to this method must be done before initialization in order to determine initial location and size of underlying resources. When invoked later, it changes the activity geometry immediately.
See also geometry().
void QActivityView::setRestoreOnAppResume(bool restore)
Turns on/off, depending on restore value, the possibility of restoring the embedded activity after it is lost during inactive state of the app. Restoring takes place when the app goes back to the active state.
See also isRestoreOnAppResumeEnabled().
void QActivityView::setVisible(bool visible)
Sets the visibility to the value of visible.
See also isVisible().
QActivityView::Status QActivityView::status() const
Returns the current status of the activity.
See also statusChanged().
[signal] void QActivityView::statusChanged(QActivityView::Status status)
This signal is emitted when the status of ActivityView changes. The status indicates the new value of the status.
Available under certain Qt licenses.
Find out more.
