diff options
Diffstat (limited to 'examples')
-rw-r--r-- | examples/applicationmanager/hello-world/doc/src/hello-world.qdoc | 2 | ||||
-rw-r--r-- | examples/applicationmanager/intents/apps/intents.blue/main.qml | 2 | ||||
-rw-r--r-- | examples/applicationmanager/intents/apps/intents.green/main.qml | 2 | ||||
-rw-r--r-- | examples/applicationmanager/intents/apps/intents.red/main.qml | 4 | ||||
-rw-r--r-- | examples/applicationmanager/intents/doc/images/intents-example.png | bin | 0 -> 70425 bytes | |||
-rw-r--r-- | examples/applicationmanager/intents/doc/images/intents-launched.png | bin | 0 -> 29188 bytes | |||
-rw-r--r-- | examples/applicationmanager/intents/doc/src/intents.qdoc | 221 | ||||
-rw-r--r-- | examples/applicationmanager/intents/intents.pro | 2 | ||||
-rw-r--r-- | examples/applicationmanager/intents/shared/IntentsApplicationWindow.qml (renamed from examples/applicationmanager/intents/shared/IntentClient.qml) | 8 | ||||
-rw-r--r-- | examples/applicationmanager/intents/shared/IntentsUIPage.qml (renamed from examples/applicationmanager/intents/shared/IntentPage.qml) | 0 | ||||
-rw-r--r-- | examples/applicationmanager/intents/system-ui.qml | 16 |
11 files changed, 246 insertions, 11 deletions
diff --git a/examples/applicationmanager/hello-world/doc/src/hello-world.qdoc b/examples/applicationmanager/hello-world/doc/src/hello-world.qdoc index 394e213d..7900cc36 100644 --- a/examples/applicationmanager/hello-world/doc/src/hello-world.qdoc +++ b/examples/applicationmanager/hello-world/doc/src/hello-world.qdoc @@ -76,7 +76,7 @@ Each application is put in its own separate directory as described below: \endlist \endlist -As you can see above, each application, besides its mail QML file, also has an icon and a +As you can see above, each application, besides its main QML file, also has an icon and a \tt{info.yaml}. That YAML file contains the application metadata (it tells System-UI the name of the application, its icon filename, etc). diff --git a/examples/applicationmanager/intents/apps/intents.blue/main.qml b/examples/applicationmanager/intents/apps/intents.blue/main.qml index d9bf24f3..fe549f88 100644 --- a/examples/applicationmanager/intents/apps/intents.blue/main.qml +++ b/examples/applicationmanager/intents/apps/intents.blue/main.qml @@ -53,4 +53,4 @@ import "../../shared" -IntentClient { } +IntentsApplicationWindow { } diff --git a/examples/applicationmanager/intents/apps/intents.green/main.qml b/examples/applicationmanager/intents/apps/intents.green/main.qml index d9bf24f3..fe549f88 100644 --- a/examples/applicationmanager/intents/apps/intents.green/main.qml +++ b/examples/applicationmanager/intents/apps/intents.green/main.qml @@ -53,4 +53,4 @@ import "../../shared" -IntentClient { } +IntentsApplicationWindow { } diff --git a/examples/applicationmanager/intents/apps/intents.red/main.qml b/examples/applicationmanager/intents/apps/intents.red/main.qml index d9bf24f3..3d6b070d 100644 --- a/examples/applicationmanager/intents/apps/intents.red/main.qml +++ b/examples/applicationmanager/intents/apps/intents.red/main.qml @@ -51,6 +51,8 @@ ** ****************************************************************************/ +//! [Main] import "../../shared" -IntentClient { } +IntentsApplicationWindow { } +//! [Main] diff --git a/examples/applicationmanager/intents/doc/images/intents-example.png b/examples/applicationmanager/intents/doc/images/intents-example.png Binary files differnew file mode 100644 index 00000000..2b213beb --- /dev/null +++ b/examples/applicationmanager/intents/doc/images/intents-example.png diff --git a/examples/applicationmanager/intents/doc/images/intents-launched.png b/examples/applicationmanager/intents/doc/images/intents-launched.png Binary files differnew file mode 100644 index 00000000..a1d8cddd --- /dev/null +++ b/examples/applicationmanager/intents/doc/images/intents-launched.png diff --git a/examples/applicationmanager/intents/doc/src/intents.qdoc b/examples/applicationmanager/intents/doc/src/intents.qdoc new file mode 100644 index 00000000..65a0d5d8 --- /dev/null +++ b/examples/applicationmanager/intents/doc/src/intents.qdoc @@ -0,0 +1,221 @@ +/**************************************************************************** +** +** Copyright (C) 2019 Luxoft Sweden AB +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Luxoft Application Manager. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\example applicationmanager/intents +\title Intents System-UI and Applications Example +\image intents-example.png The Intents example with all applications running. +\brief Three applications and a System-UI communicating over Intents. +\ingroup applicationmanager-examples + +\section1 Introduction + +This example shows how the System-UI and applications can send and receive Intents. Just like in the +"Hello World!" example, the window management part is kept to a minimum: the 2x2 grid on the right +will always show the System-UI part (gray) in the top-left quadrant, while the three apps (red, +green and blue) will dynamically occupy the other quadrants in the order they are started. You're +able to see icons and names of the available applications on the left and start and stop them by +clicking on their respective icons. + +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 \e Intent), +and optionally also specify which application you would like to handle the chosen request via the +combo-box below (labeled \e Application). +Clicking the \e Request button will create and send the corresponding intent request to the +application-manager's IntentServer for handling. There are three possible outcomes: +\list +\li The \e Intent / \e Application combination was valid and the target application was able to + handle the request: the \l{IntentRequest::result}{result of this request} will be shown + as JSON text in the lower output field labeled \e Request. + +\li Either the \e Intent / \e Application combination was invalid or the target application was not + able to handle the request properly: the \l{IntentRequest::errorMessage} + {error message of this request} will be shown as plain text in the lower output field + labeled \e Request. + +\li You did not specify an \e Application, plus the chosen \e Intent can be handled by more than + one application: in this case the example's System-UI will display a dialog, prompting the user + to \l{IntentServer::disambiguationRequest}{disambiguate the request}. +\endlist + + +\section1 Files and folder structure + +This example is comprised of a System-UI and three sample applications ("Red Intents", "Green Intents" +and "Blue Intents"), making for 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 component live in a shared +directory. + +\list +\li \tt{system-ui.qml} +\li \tt{\b{apps}} + \list + \li \tt{\b{intents.blue}} + \list + \li \tt{icon.png} + \li \tt{info.yaml} + \li \tt{main.qml} + \endlist + \li \tt{\b{intents.red}} + \list + \li \tt{icon.png} + \li \tt{info.yaml} + \li \tt{main.qml} + \endlist + \li \tt{\b{intents.green}} + \list + \li \tt{icon.png} + \li \tt{info.yaml} + \li \tt{main.qml} + \endlist + \endlist +\li \tt{\b{shared}} + \list + \li \tt{IntentsApplicationWindow.qml} + \li \tt{IntentsUIPage.qml} + \endlist +\endlist + +As you can see above, each application, besides its main QML file, also has an icon and a +\tt{info.yaml}. That YAML file contains the application metadata, which also includes the +definition of the intents that this application is able to handle. + +\section1 Running + +Assuming the \c appman executable is in your path, you can run the System-UI as follows: + +\badcode +examples/applicationmanager/intents$ appman --builtin-apps-manifest-dir ./apps system-ui.qml +\endcode + +Adding \c{-o "ui: { style: material }" } will make the example look and feel a lot nicer. + +And this is what you should see: + +\image intents-launched.png + +For information on these and other command line options you can run \tt{appman --help}. + + +\section1 Application implementation + +All the applicationa (red, green and blue) are exactly the same and their \c main.qml just +instantiates the shared IntentsApplicationWindow component. + +\snippet applicationmanager/intents/apps/intents.red/main.qml Main + +The IntentsApplicationWindow component is actually a top-level ApplicationManagerWindow, with its +UI contents being defined by instantiating the - also shared - component \c IntentsUIPage. This UI +component does not have any intent specific code, so the actual sending is done in signal +handler attached to the IntentsUIPage request signal: + +\snippet applicationmanager/intents/shared/IntentsApplicationWindow.qml Send Intent + +After calling IntentClient::sendIntentRequest with the parameters as chosen in the UI, the +example code will connect a function object to the \l{IntentClientRequest::replyReceived} +{request's replyReceived} signal. As mentioned in the introduction, it will then dump the result +into the \e Request field in the UI. + +In addition, it defines all the necessary IntentHandlers for the applications, e.g.: + +\snippet applicationmanager/intents/shared/IntentsApplicationWindow.qml Intent Handler + +These intent handlers are pretty simple, with each one just triggering a simple animation that is +also defined in this file, so for the \c rotate-window intent this would be: + +\snippet applicationmanager/intents/shared/IntentsApplicationWindow.qml Intent Animation + +Just implementing IntentHandlers in QML is not enough though, because the application-manager needs +the information on which application supports which intents \b before the applications are already +running, most importantly to faciliate auto-starting applications on intent requests. As for +every other application configuration in the application-manager, this is done through the +applications's manifest file \c info.yaml: + +The \b Red application defines three available intents. + +\quotefromfile applicationmanager/intents/apps/intents.red/info.yaml +\skipto intents: +\printto + +Additionally, the red application gains the \c call-blue capability, which is required by certain +intents in the blue application (see below) + +\quotefromfile applicationmanager/intents/apps/intents.red/info.yaml +\skipto capabilities: +\printline capabilities + + +The \b Green application defines only two available intents. Please note that even though the green +application has an IntentHandler for the \c blink-window intent through the shared +IntentsApplicationWindow component, this handler would never be called, since this intent id is not +registered with the system via the \c info.yaml manifest: + +\quotefromfile applicationmanager/intents/apps/intents.green/info.yaml +\skipto intents: +\printto + +The \b Blue application has the most complex intent definition. In addition to handling the same +three intents as the red application, it registeres the \c blue-window-private intent that has the +attribute \c{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 \c blue-window-private +intent. Furthermore, the \c rotate-window intent in this application can only be requested by +applications that have the \c call-blue capability: here the red application comes with the +required capability, while the green one doesn't (see above). + +\quotefromfile applicationmanager/intents/apps/intents.blue/info.yaml +\skipto intents: +\printto + + +\section1 System-UI implementation + +The windows and application management part of the System-UI is in large parts a copy of the +"Hello-World!" example. Instead of arranging all incoming application windows in a column on the +right, the Intents example uses a 2x2 grid to display its own UI and the three applications it +comes with. The System-UI in the top-left part is the shared IntentsUIPage component, that is used +the same way in the applications (see below). + +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: + +\snippet applicationmanager/intents/system-ui.qml Connection + +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 (\c allRequests). The \c Dialog that consumes that +queue is a fairly standard QtQuickControls 2 dialog, that gives you nice UI showing you the +possible application choices coming from the IntentServer::disambiguationRequested() signal. Upon +pressing \e Ok or \e Cancel, the dialog will notify the IntentServer about the user's decision: + +\snippet applicationmanager/intents/system-ui.qml OkCancel + +*/ diff --git a/examples/applicationmanager/intents/intents.pro b/examples/applicationmanager/intents/intents.pro index 10e552a3..eaa0e964 100644 --- a/examples/applicationmanager/intents/intents.pro +++ b/examples/applicationmanager/intents/intents.pro @@ -3,6 +3,8 @@ CONFIG += am-systemui OTHER_FILES += \ *.qml \ + doc/images/*.png \ + doc/src/*.qdoc \ shared/*.qml \ apps/intents.blue/*.yaml \ apps/intents.blue/*.qml \ diff --git a/examples/applicationmanager/intents/shared/IntentClient.qml b/examples/applicationmanager/intents/shared/IntentsApplicationWindow.qml index b24753a5..4f56b576 100644 --- a/examples/applicationmanager/intents/shared/IntentClient.qml +++ b/examples/applicationmanager/intents/shared/IntentsApplicationWindow.qml @@ -59,12 +59,13 @@ ApplicationManagerWindow { id: root property string flavor: ApplicationInterface.applicationId.split(".")[1] - IntentPage { + IntentsUIPage { id: intentPage anchors.fill: parent flavor: root.flavor title: ApplicationInterface.name["en"] + //! [Send Intent] onRequest: { var request = IntentClient.sendIntentRequest(intentId, applicationId, parameters) request.onReplyReceived.connect(function() { @@ -72,12 +73,15 @@ ApplicationManagerWindow { request.succeeded ? request.result : request.errorMessage) }) } + //! [Send Intent] + //! [Intent Animation] RotationAnimation on rotation { id: rotationAnimation running: false duration: 500; from: 0; to: 360 } + //! [Intent Animation] SequentialAnimation on scale { id: scaleAnimation @@ -101,6 +105,7 @@ ApplicationManagerWindow { } } + //! [Intent Handler] IntentHandler { intentIds: "rotate-window" onRequestReceived: { @@ -108,6 +113,7 @@ ApplicationManagerWindow { request.sendReply({ "done": true }) } } + //! [Intent Handler] IntentHandler { intentIds: "scale-window" diff --git a/examples/applicationmanager/intents/shared/IntentPage.qml b/examples/applicationmanager/intents/shared/IntentsUIPage.qml index ccf5534f..ccf5534f 100644 --- a/examples/applicationmanager/intents/shared/IntentPage.qml +++ b/examples/applicationmanager/intents/shared/IntentsUIPage.qml diff --git a/examples/applicationmanager/intents/system-ui.qml b/examples/applicationmanager/intents/system-ui.qml index 8cec8ee2..07efbcf2 100644 --- a/examples/applicationmanager/intents/system-ui.qml +++ b/examples/applicationmanager/intents/system-ui.qml @@ -98,7 +98,7 @@ Item { } columns: 2 - IntentPage { + IntentsUIPage { id: sysui_page width: parent.width / 2 height: parent.height / 2 @@ -123,6 +123,12 @@ Item { } } + //! [Connection] + Connections { + target: IntentServer + onDisambiguationRequest: { disambiguationDialog.add(requestId, potentialIntents) } + } + //! [Connection] Dialog { id: disambiguationDialog @@ -156,6 +162,8 @@ Item { open() } } + + //! [OkCancel] onAccepted: { IntentServer.acknowledgeDisambiguationRequest(currentRequest.requestId, currentRequest.intents[handlingApplications.currentIndex]); @@ -165,6 +173,7 @@ Item { IntentServer.rejectDisambiguationRequest(currentRequest.requestId) showNext() } + //! [OkCancel] GridLayout { id: grid @@ -207,9 +216,4 @@ Item { } } } - - Connections { - target: IntentServer - onDisambiguationRequest: { disambiguationDialog.add(requestId, potentialIntents) } - } } |