Introduction

This example shows how the System-UI and applications can send and receive Intents. Similar to the "Hello World!" System-UI Example, the window management aspect is kept to a minimum to focus only on Intents: the 2x2 grid on the right will always show the System-UI part (gray) in the top-left corner, while the three apps (red, green and blue) will dynamically occupy the other corner in the order they are started. You can see the names and icons for the available applications on the left; click on their respective icons to start and stop these applications.

Each application, as well as the System-UI, look alike and have the same functionality available in the UI: You can choose from one of the available intent IDs in the top combo-box (labeled Intent), and optionally also specify the corresponding application that should handle the chosen request (labeled Application). Clicking the Request button will create and send the corresponding intent request to the application-manager's IntentServer for handling:

• The combination of Intent and Application was valid and the target application was able to handle the request; the result of this request will be shown as JSON text in the lower output field labeled Request.
• Either the combination of Intent and Application was invalid or the target application was not able to handle the request properly; the error message of this request will be shown as plain text in the lower output field labeled Request.
• The Application was not specified, plus the Intent chosen can be handled by more than one application; in this case the example's System-UI will display a dialog, prompting the user to disambiguate the request.

Files and Folder Structure

This example comprises of a System-UI and three sample applications ("Red Intents", "Green Intents" and "Blue Intents"), resulting in four separate QML applications in total. System-UI is also just a QML application in the end, albeit a special one.

Each application is put in its own separate directory as described below. Since the QtQuickControls 2 based UI is used by all the applications and the System-UI, its components live in a shared directory.

• system-ui.qml
• apps
  • intents.blue
    • icon.png
    • info.yaml
    • main.qml
  • intents.red
    • icon.png
    • info.yaml
    • main.qml
  • intents.green
    • icon.png
    • info.yaml
    • main.qml
• shared
  • IntentsApplicationWindow.qml
  • IntentsUIPage.qml

As you can see above, each application, besides its main QML file, also has an icon and a info.yaml file that contains the application metadata, which also includes the definition of the intents that this application can handle.

Running the Example

Assuming the appman executable is in your path, you can run the System-UI as follows:

examples/applicationmanager/intents$ appman --builtin-apps-manifest-dir ./apps system-ui.qml

Adding -o "ui: { style: material }" will make the example look and feel a lot nicer.

And this is what you should see:

For information on these and other command line options you can run appman --help or have a look at the Configuration documentation.

Application implementation

All the applications (red, green and blue) are identical and their main.qml just instantiates the shared IntentsApplicationWindow component.

import "../../shared"

IntentsApplicationWindow { }

The IntentsApplicationWindow component is actually a top-level ApplicationManagerWindow, with its UI contents being defined by instantiating the IntentsUIPage component, that is also shared. This UI component does not have any intent-specific code, so the actual sending is done in the signal handler attached to the IntentsUIPage request signal:

onRequest: {
    var request = IntentClient.sendIntentRequest(intentId, applicationId, parameters)
    request.onReplyReceived.connect(function() {
        intentPage.setResult(request.requestId, request.succeeded,
                             request.succeeded ? request.result : request.errorMessage)
    })
}

After calling IntentClient::sendIntentRequest with the parameters as chosen in the UI, the example code will connect a function object to the request's replyReceived signal. The result is placed in the Request field in the UI.

In addition, it defines all the necessary IntentHandlers for the applications, for example:

IntentHandler {
    intentIds: "rotate-window"
    onRequestReceived: {
        rotationAnimation.start()
        request.sendReply({ "done": true })
    }
}

These intent handlers are not complex, with each one just triggering a basic animation that is also defined in this file, so for the rotate-window intent this would be:

RotationAnimation on rotation {
    id: rotationAnimation
    running: false
    duration: 500; from: 0; to: 360
}

In QML, only implementing the IntentHandlers is not sufficient, because the application-manager needs to have information on which application supports which intents. This information must be available to the application-manager before the applications run, to facilitate auto-starting applications on intent requests. As for every other application configuration in the application-manager, this is done through the application's manifest file info.yaml:

The Red application defines three available intents:

intents:
- id: rotate-window
- id: scale-window
- id: blink-window

Additionally, the Red application gains the call-blue capability, which is required by certain intents in the Blue application.

capabilities: 'call-blue'

The Green application defines only two available intents. Note that even though this application has an IntentHandler for the blink-window intent through the shared IntentsApplicationWindow component, this handler is never called, since this intent ID is not registered with the system via the info.yaml manifest:

intents:
- id: rotate-window
- id: scale-window

The Blue application has the most complex intent definition. In addition to handling the same three intents as the Red application, it registers the blue-window-private intent that has the attribute visibility: private. Private intents can only be requested from the same application that registered them, so in this case only Blue can successfully request the blue-window-private intent. Furthermore, the rotate-window intent can only be requested by applications that have the call-blue capability: here the Red application comes with the required capability, while the Green doesn't.

intents:
- id: rotate-window
  requiredCapabilities: [ 'call-blue' ]
- id: scale-window
- id: blink-window
- id: blue-window-private
  visibility: private

System-UI implementation

What is special about the System-UI as compared to the applications, is the disambiguation mechanism and the accompanying UI. Registering for the IntentServer's disambiguation requests is done here:

Connections {
    target: IntentServer
    onDisambiguationRequest: { disambiguationDialog.add(requestId, potentialIntents) }
}

Since we want to stay flexible with regards to the number of parallel intent requests in the system, we just add the incoming request to a queue (allRequests). The Dialog that consumes that queue is a fairly standard QtQuickControls 2 dialog, that gives you a nice UI showing you the possible application choices coming from the IntentServer::disambiguationRequested() signal. Upon pressing Ok or Cancel, the dialog will notify the IntentServer about the user's decision:

onAccepted: {
    IntentServer.acknowledgeDisambiguationRequest(currentRequest.requestId,
                                                  currentRequest.intents[handlingApplications.currentIndex]);
    showNext()
}
onRejected: {
    IntentServer.rejectDisambiguationRequest(currentRequest.requestId)
    showNext()
}

Files:

• applicationmanager/intents/apps/intents.blue/info.yaml
• applicationmanager/intents/apps/intents.blue/main.qml
• applicationmanager/intents/apps/intents.green/info.yaml
• applicationmanager/intents/apps/intents.green/main.qml
• applicationmanager/intents/apps/intents.red/info.yaml
• applicationmanager/intents/apps/intents.red/main.qml
• applicationmanager/intents/intents.pro
• applicationmanager/intents/shared/IntentsApplicationWindow.qml
• applicationmanager/intents/shared/IntentsUIPage.qml
• applicationmanager/intents/system-ui.qml

Images:

• applicationmanager/intents/apps/intents.blue/icon.png
• applicationmanager/intents/apps/intents.green/icon.png
• applicationmanager/intents/apps/intents.red/icon.png