Add documentation for the intents example

Change-Id: I474f8bc8d8a3efa7b0f8405892d56a793a88e883
Reviewed-by: Kavindra Palaraja <kpalaraja@luxoft.com>

12 files changed, 247 insertions, 12 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
new 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
new 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) }
-    }
 }
diff --git a/src/intent-client-lib/intentclientrequest.cpp b/src/intent-client-lib/intentclientrequest.cpp
index 27358307..bee28543 100644
--- a/src/intent-client-lib/intentclientrequest.cpp
+++ b/src/intent-client-lib/intentclientrequest.cpp
@@ -160,7 +160,7 @@ QT_BEGIN_NAMESPACE_AM
     valid.
 
     \note This signal will only ever by emitted for request objects created by
-          IntentClient.sendIntentRequest().
+          IntentClient::sendIntentRequest().
 */