doc/ApplicationGuide.md

   1 **OnScreen Application Guide**
   2 ====
   3 <div align="right">Revision: 0.1</div>
   4 <div align="right">TOYOTA MOTOR CORPORATION</div>
   5 <div align="right">Advanced Driver Information Technology</div>
   6 <div align="right">12th/Dec/2017</div>
   7
   8 * * *
   9
  10 <div id="Table of content"></div>
  11
  12 ## Table of content
  13 - [Target reader of this document](#Target reader of this document)
  14 - [Overview](#Overview)
  15 - [Getting Start](#Getting Start)
  16         - [Supported environment](#Supported environment)
  17         - [Build](#Build)
  18         - [Configuring](#Configuring)
  19         - [How to call HomeScreen APIs from your Application?](#How to call HomeScreen APIs from your Application?)
  20 - [Supported usecase](#Supported usecase)
  21 - [Operation check](#Operation check)
  22
  23 * * *
  24
  25 <div id="Target reader of this document"></div>
  26
  27 ## Target reader of this document
  28 Application developer who wants to realize on-screen display on HomeScreen using OnScreenApp.
  29
  30 * * *
  31
  32 <div id="Overview"></div>
  33
  34 ## Overview
  35 OnScreenApp realizes on-screen display on the HomeScreen receiving the on_screen_message event of HomeScreenBinding.
  36 OnScreenApp is implemented with Qt. In order to receive the on_screen_message event, HomeScreenBinder needs to be started as part of afb - daemon 's service.
  37 OnScreenApp analyzes the command (JSON) acquired by on_screen_message, reads QML and displays it.
  38
  39 You can find these projects in AGL gerrit.
  40
  41 homescreen-2017(HomeScreenGUI):
  42     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/staging/homescreen-2017
  43 agl-service-homescreen-2017(HomeScreenBinder's binding library):
  44     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen-2017
  45 libhomescreen(library for application to communication with HomeScreenBinder):
  46     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen
  47
  48 Also OnScreenApp is using qlibwindowmanager.
  49
  50 <div id="Getting Start"></div>
  51
  52 ## Getting Start
  53
  54 <div id="Supported environment"></div>
  55
  56 ### Supported environment
  57
  58 | Item        | Description                       |
  59 |:------------|:----------------------------------|
  60 | AGL version | Electric Eel                      |
  61 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
  62
  63
  64 <div id="Build"></div>
  65
  66 ### Build
  67
  68 **Download recipe**
  69
  70 ```
  71 $ mkdir WORK
  72 $ cd WORK
  73 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
  74 $ repo sync
  75
  76 ```
  77
  78 Then you can find the following recipes.
  79
  80 * `meta-agl-devel/meta-hmi-framework/homescreen-2017`
  81
  82 * `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
  83
  84 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
  85
  86
  87 **Bitbake**
  88
  89 ```
  90 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
  91 $ bitbake agl-demo-platform
  92 $ bitbake agl-demo-platform-crosssdk
  93 ```
  94
  95 **Export SDK**
  96
  97 ```
  98 $ cd WORK
  99 $ cd ./build/tmp/deploy/sdk/
 100 $ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-toolchain-4.99.2.sh
 101 ```
 102
 103 * * *
 104
 105 <div id="Configuring"></div>
 106
 107 ### Configuring
 108 OnScreenApp uses HomeScreenBinding and WindowManager API.
 109 In order to use these APIs, you need to paste the following configuration definition into "config.xml" of your application.
 110
 111 ```
 112 <feature name="urn:AGL:widget:required-api">
 113     <param name="homescreen" value="ws" />
 114     <param name="windowmanager" value="ws" />
 115 </feature>
 116 ```
 117
 118 * * *
 119
 120 <div id="How to call HomeScreen and WindowManager APIs from your Application?"></div>
 121
 122 ## How to perform on-screen display on OnScreenApp
 123
 124 ### Send message to perform on-screen display
 125 In order to perform on-screen display on OnScreenApp, it is necessary to use the on_screen_message () API provided by HomeScreenBinding.
 126 In the argument of on_screen_message (), pass the character string of JSON format below.
 127
 128 ```
 129 {
 130     "app": "<Application name>",
 131     "message": "<Message string>",
 132     "file": "<QML file path>",
 133     "mask": "<Display mask image file>"
 134 }
 135 ```
 136
 137 Since the application name is used as a key for specifying an application displayed on OnScreenApp, it needs to be unique.
 138 The message string is a character string for default display when a specific command or external QML is not read.
 139 For the QML file path and the display mask image file, the full path on the AGL system is described respectively.
 140
 141 ### Display QML file and mask image
 142 OnScreenApp has the function of reading and displaying QML file from outside.
 143 Even when there is no QML file, you can display a character string on the default User Interface.
 144 The size of the displayable QML file is width 1079 height 400. Mask image is also similar size and image file with alpha channel (Recommended is png format).
 145
 146 ### Retrieve events from QML
 147 It is possible to execute "on_screen_reply()" of libhomescreen using the object called eventHandler in prepared QML.
 148 For example, by registering the event "Evnet_OnScreenReply" of libhomescreen on the application side,
 149 It is possible to implement processing by clicking buttons prepared on the QML.
 150
 151 Example) Execution of on_screen_reply event by QML Button click
 152
 153 ```
 154     ImageButton {
 155         width: 300
 156         height: 60
 157         offImage: 'images/button.svg'
 158
 159         onClicked: {
 160             eventHandler.onScreenReply("{ \"<Application name>\": \"<Message string>\" }");
 161         }
 162     }
 163 ```
 164
 165
 166 <br />
 167
 168 * * *
 169
 170 <div id="Supported usecase"></div>
 171
 172 ## Supported usecase
 173 1. Display OnScreen messages
 174         - Applications sending OnScreen messages to homescreen-service, and OnScreenApp
 175         will get these message and display.
 176 2. Get OnSreen Reply event
 177         - When OnScreen messages is displaying, OnScreenApp will send a reply event to applications.
 178
 179 * * *
 180
 181 <div id="Operation check"></div>
 182
 183 ## Operation check
 184 The operation on OnScreenApp can be confirmed by afb-client-demo.
 185 OnScreenApp includes QML files for Phone and System as operation confirmation samples.
 186 You can confirm the operation by executing the following command on the AGL on which OnScreenApp is installed.
 187
 188 ```
 189 $ afm-util start onscreenapp@0.1
 190 $ afb-client-demo ws://localhost:1024/api?token=HELLO
 191
 192 homescreen subscribe { "event" : "on_screen_reply" }
 193
 194 homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"incoming call\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }
 195
 196 homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"error\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
 197
 198 homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"rejected\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
 199
 200 homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"call rejected\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }
 201
 202 ```
 203