ApplicationManager QML Type

The application model and controller. More...

Import Statement: import QtApplicationManager.SystemUI 2.0

List of all members, including inherited members

Properties

containerSelectionFunction : var
count : int
securityChecksEnabled : bool
shuttingDown : bool
singleProcess : bool
systemProperties : var
windowManagerCompositorReady : bool

Signals

applicationAboutToBeRemoved(string id)
applicationAdded(string id)
applicationChanged(string id, list<string> changedRoles)
applicationRunStateChanged(string id, enumeration runState)
applicationWasActivated(string id, string aliasId)
openUrlRequested(string requestId, string url, string mimeType, list<string> possibleAppIds)

Methods

acknowledgeOpenUrlRequest(string requestId, string appId)
ApplicationObject application(int index)
ApplicationObject application(string id)
list<string> applicationIds()
list<string> capabilities(string id)
bool debugApplication(string id, string debugWrapper, string document)
object get(int index)
object get(string id)
list<string> identifyAllApplications(int pid)
string identifyApplication(int pid)
int indexOfApplication(ApplicationObject application)
int indexOfApplication(string id)
bool openUrl(string url)
rejectOpenUrlRequest(string requestId)
bool startApplication(string id, string document)
stopAllApplications(bool forceKill)
stopApplication(string id, bool forceKill)

Detailed Description

The ApplicationManager singleton type is the core of the application manager. It provides both a DBus and a QML API for all of its functionality.

The type is derived from QAbstractListModel, so it can be used directly as a model in app-grid views.

The following roles are available in this model:

Role name	Type	Description
`applicationId`	string	The unique Id of an application, represented as a string (e.g. `Browser` or `com.pelagicore.music`)
`name`	string	The name of the application. If possible, already translated to the current locale.
`icon`	string	The URL of the application's icon.
`isRunning`	bool	A boolean value representing the run-state of the application.
`isStartingUp`	bool	A boolean value indicating whether the application is starting up and not fully operational yet.
`isShuttingDown`	bool	A boolean value indicating whether the application is currently shutting down.
`isBlocked`	bool	A boolean value that gets set when the application manager needs to block the application from running: this is normally only the case while an update is applied.
`isUpdating`	bool	A boolean value indicating whether the application is currently being installed or updated. If `true`, the `updateProgress` can be used to track the actual progress.
`isRemovable`	bool	A boolean value indicating whether this application is user-removable; `true` for all dynamically installed third party applications and `false` for all system applications.
`updateProgress`	real	While `isUpdating` is `true`, querying this role returns the actual progress as a floating-point value in the `0.0` to `1.0` range.
`codeFilePath`	string	The filesystem path to the main "executable". The format of this file is dependent on the actual runtime though: for QML applications the "executable" is the `main.qml` file.
`categories`	list<string>	The categories this application is registered for via its meta-data file.
`version`	string	The currently installed version of this application.
`application`	ApplicationObject	The underlying ApplicationObject for quick access to the properties outside of a model delegate.
`applicationObject`	ApplicationObject	Exactly the same as `application`. This was added to keep the role names between the PackageManager and ApplicationManager models as similar as possible. This role was introduced in Qt version 6.6.

Note: The index-based API is currently not available via DBus. However, the same functionality is provided by the id-based API.

After importing, you can just use the ApplicationManager singleton as follows:

import QtQuick
import QtApplicationManager.SystemUI

ListView {
    id: appList
    model: ApplicationManager

    delegate: Text {
        text: name + "(" + applicationId + ")"

        MouseArea {
            anchors.fill: parent
            onClick: ApplicationManager.startApplication(applicationId)
        }
    }
}

Property Documentation

containerSelectionFunction : var

A JavaScript function callback that will be called whenever the application manager needs to instantiate a container for running an application. See Container Selection Configuration for more information.

count : int [read-only]

This property holds the number of applications available.

securityChecksEnabled : bool [read-only]

This property holds whether security related checks are enabled.

See also no-security.

shuttingDown : bool [read-only]

This property is there to inform the System UI, when the application manager has entered its shutdown phase. New application starts are already prevented, but the System UI might want to impose additional restrictions in this state.

singleProcess : bool [read-only]

This property indicates whether the application manager runs in single- or multi-process mode.

systemProperties : var [read-only]

Returns the project specific system properties that were set via the config file.

windowManagerCompositorReady : bool [read-only]

This property starts with the value false and will change to true once the Wayland compositor is ready to accept connections from other processes. In multi-process mode, this happens implicitly after the System UI's main QML has been loaded.

Signal Documentation

applicationAboutToBeRemoved(string id)

This signal is emitted before an existing application, identified by id, is removed via the PackageManager.

Note: In addition to the normal "low-level" QAbstractListModel signals, the application manager will also emit these "high-level" signals for System UIs that cannot work directly on the ApplicationManager model: applicationAdded, applicationAboutToBeRemoved and applicationChanged.

Note: The corresponding handler is onApplicationAboutToBeRemoved.

applicationAdded(string id)

This signal is emitted after a new application, identified by id, has been installed via the PackageManager. The model has already been update before this signal is sent out.

Note: The corresponding handler is onApplicationAdded.

applicationChanged(string id, list<string> changedRoles)

Emitted whenever one or more data roles, denoted by changedRoles, changed on the application identified by id. An empty list in the changedRoles argument means that all roles should be considered modified.

Note: The corresponding handler is onApplicationChanged.

applicationRunStateChanged(string id, enumeration runState)

This signal is emitted when the runState of the application identified by id changed. Possible values for the runState are defined by the ApplicationObject type.

For example this signal can be used to restart an application in multi-process mode when it has crashed:

Connections {
    target: ApplicationManager
    function onApplicationRunStateChanged() {
        if (runState === Am.NotRunning
            && ApplicationManager.application(id).lastExitStatus === Am.CrashExit) {
            ApplicationManager.startApplication(id);
        }
    }
}

Method Documentation

acknowledgeOpenUrlRequest(string requestId, string appId)

Tells the application manager to go ahead with the request to open an URL, identified by requestId. The chosen appId needs to be one of the possibleAppIds supplied to the receiver of the openUrlRequested signal.

See also openUrl and openUrlRequested.

ApplicationObject application(int index)

Returns the application corresponding to the given index in the model, or null if the index is invalid.

Note: The object ownership of the returned Application object stays with the application manager. If you want to store this pointer, you can use the ApplicationManager's QAbstractListModel signals or the applicationAboutToBeRemoved signal to get notified if the object is about to be deleted on the C++ side.

ApplicationObject application(string id)

Returns the application corresponding to the given application id, or null if the id does not exist.

list<string> applicationIds()

Returns a list of all available application ids. This can be used to further query for specific information via get().

list<string> capabilities(string id)

Returns a list of all capabilities granted by the user to the application identified by id. Returns an empty list if the application id is not valid.

bool debugApplication(string id, string debugWrapper, string document)

Instructs the application manager to start the application identified by its unique id, just like startApplication. The application is started via the given debugWrapper though. The optional argument document will be supplied to the application as is - most commonly this is used to refer to a document to display.

Returns a bool value indicating success. See the full documentation at ApplicationManager::startApplication for more information.

Please see the Debugging page for more information on how to setup and use these debug-wrappers.

See also ApplicationObject::debug.

object get(int index)

Retrieves the model data at index as a JavaScript object. See the role names for the expected object fields.

Returns an empty object if the specified index is invalid.

Note: This is very inefficient if you only want to access a single property from QML; use application() instead to access the Application object's properties directly.

object get(string id)

Retrieves the model data for the application identified by id as a JavaScript object. See the role names for the expected object fields.

Returns an empty object if the specified id is invalid.

list<string> identifyAllApplications(int pid)

Validates the process running with process-identifier pid as a process started by the application manager.

If multiple applications are running within the same container process, this function will return all those application ids.

Returns a list with the applications' ids on success, or an empty list on failure.

string identifyApplication(int pid)

Validates the process running with process-identifier pid as a process started by the application manager.

Note: If multiple applications are running within the same container process, this function will return only the first matching application. See identifyAllApplications() for a way to retrieve all application ids.

Returns the application's id on success, or an empty string on failure.

int indexOfApplication(ApplicationObject application)

Maps the application to its position within this model. Returns -1 if the specified application is invalid.

int indexOfApplication(string id)

Maps the application corresponding to the given id to its position within the model. Returns -1 if the specified id is invalid.

bool openUrl(string url)

Tries start an application that is capable of handling url. The application manager will first look at the URL's scheme:

If it is file:, the operating system's MIME database will be consulted, which will try to find a MIME type match, based on file endings or file content. In case this is successful, the application manager will use this MIME type to find all of its applications that claim support for it (see the mimeTypes field in the application's manifest). A music player application that can handle mp3 and wav files, could add this to its manifest:
```
mimeTypes: [ 'audio/mpeg', 'audio/wav' ]
```
If it is something other than file:, the application manager will consult its internal database of applications that claim support for a matching x-scheme-handler/... MIME type. In order to have your web-browser application handle http: and https: URLs, you would have to have this in your application's manifest:
```
mimeTypes: [ 'x-scheme-handler/http', 'x-scheme-handler/https' ]
```

If there is at least one possible match, it depends on the signal openUrlRequested() being connected within the System UI: In case the signal is not connected, an arbitrary application from the matching set will be started. Otherwise the application manager will emit the openUrlRequested signal and return true. It is up to the receiver of this signal to choose from one of possible applications via acknowledgeOpenUrlRequest or deny the request entirely via rejectOpenUrlRequest. Not calling one of these two functions will result in memory leaks.

If an application is started by one of the two mechanisms, the url is supplied to the application as a document to open via its ApplicationInterface.

Returns true, if a match was found in the database, or false otherwise.

rejectOpenUrlRequest(string requestId)

Tells the application manager to ignore the request to open an URL, identified by requestId.

See also openUrl and openUrlRequested.

bool startApplication(string id, string document)

Instructs the application manager to start the application identified by its unique id. The optional argument document will be supplied to the application as is - most commonly this is used to refer to a document to display. Returns true if the application id is valid and the application manager was able to start the runtime plugin. Returns false otherwise. Note that even though this call may indicate success, the application may still later fail to start correctly as the actual startup process within the runtime plugin may be asynchronous.

See also ApplicationObject::start.

stopAllApplications(bool forceKill)

Tells the application manager to stop all running applications. The meaning of the forceKill parameter is runtime dependent, but in general you should always try to stop an application with forceKill set to false first in order to allow a clean shutdown. Use forceKill set to true only as a last resort to kill hanging applications.

See also stopApplication.

stopApplication(string id, bool forceKill)

Tells the application manager to stop an application identified by its unique id. The meaning of the forceKill parameter is runtime dependent, but in general you should always try to stop an application with forceKill set to false first in order to allow a clean shutdown. Use forceKill set to true only as a last resort to kill hanging applications.

QML applications and native applications that support the ApplicationInterface will be notified via ApplicationInterface::quit(). All other applications will be sent the Unix TERM signal.

See also ApplicationObject::stop.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.