ApplicationManager QML Type

The application model and controller. More...

Import Statement: import QtApplicationManager 1.0

Properties

Signals

Methods

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 nameTypeDescription
applicationIdstringThe unique Id of an application, represented as a string (e.g. Browser or com.pelagicore.music)
namestringThe name of the application. If possible, already translated to the current locale.
iconstringThe URL of the application's icon.
isRunningboolA boolean value representing the run-state of the application.
isStartingUpboolA boolean value indicating whether the application is starting up and not fully operational yet.
isShuttingDownboolA boolean value indicating whether the application is currently shutting down.
isBlockedboolA 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.
isUpdatingboolA boolean value indicating whether the application is currently being installed or updated. If true, the updateProgress can be used to track the actual progress.
isRemovableboolA boolean value indicating whether this application is user-removable; true for all dynamically installed third party applications and false for all system applications.
updateProgressrealWhile isUpdating is true, querying this role returns the actual progress as a floating-point value in the 0.0 to 1.0 range.
codeFilePathstringThe 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.
categorieslist<string>The categories this application is registered for via its meta-data file (currently work in progress).
versionstringThe currently installed version of this application.
applicationApplicationThe underlying application object for quick access to the properties outside of a model delegate.

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 2.0
import QtApplicationManager 1.0

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.


[read-only] count : int

This property holds the number of applications available.


[read-only] securityChecksEnabled : bool

This property holds whether security related checks are enabled.

See also no-security.


[read-only] shuttingDown : bool

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.


[read-only] singleProcess : bool

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


[read-only] systemProperties : var

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


[read-only] windowManagerCompositorReady : bool

This property starts with the value false and will change to true once the Wayland compositor is ready to accept connections from other processes. Please be aware that this will only happen either implicitly after the System-UI's main QML has been loaded or explicitly when calling WindowManager::registerCompositorView() from QML before the loading stage has completed.


Signal Documentation

applicationAboutToBeRemoved(string id)

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

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.


applicationAdded(string id)

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

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.


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


applicationRunStateChanged(string id, enumeration runState)

This signal is emitted when the runState of the application identified by id changed. The runState can be one of:

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

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

See also Application::runState


applicationWasActivated(string id, string aliasId)

This signal is emitted when an application identified by id is (re-)started via the ApplicationManager API, possibly through an alias, provided in aliasId.

The window manager should take care of raising the application's window in this case.


openUrlRequested(string requestId, string url, string mimeType, list<string> possibleAppIds)

This signal is emitted when the application-manager is requested to open an URL. This can happen by calling

  • Qt.openUrlExternally in an application,
  • Qt.openUrlExternally in the System-UI,
  • ApplicationManager::openUrl in the System-UI or
  • io.qt.ApplicationManager.openUrl via D-Bus

Note: This signal is only emitted, if there is a receiver connected at all - see openUrl for the fallback behavior.

The receiver of this signal can inspect the requested url an its mimeType. It can then either call acknowledgeOpenUrlRequest to choose from one of the supplied possibleAppIds or rejectOpenUrlRequest to ignore the request. In both cases the unique requestId needs to be sent to identify the request. Not calling one of these two functions will result in memory leaks.

See also openUrl, acknowledgeOpenUrlRequest, and rejectOpenUrlRequest.


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.


Application application(string id)

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

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.


Application application(int index)

Returns the Application object 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.


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 just like startApplication. The application is started via the given debugWrapper though. Please see the Debugging page for more information on how to setup and use these debug-wrappers.


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.


object get(int row)

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

Returns an empty object if the specified row 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.


string identifyApplication(int pid)

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

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


int indexOfApplication(string id)

Maps the application 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.

See also openUrlRequested, acknowledgeOpenUrlRequest, and rejectOpenUrlRequest.


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.


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.


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.


© 2018 Pelagicore AG. 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.