1 **OnScreen Application Guide**
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>
10 <div id="Table of content"></div>
13 - [Target reader of this document](#Target reader of this document)
14 - [Overview](#Overview)
15 - [Getting Start](#Getting Start)
16 - [Supported environment](#Supported environment)
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)
25 <div id="Target reader of this document"></div>
27 ## Target reader of this document
28 Application developer who wants to realize on-screen display on HomeScreen using OnScreenApp.
32 <div id="Overview"></div>
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.
39 You can find these projects in AGL gerrit.
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
48 Also OnScreenApp is using qlibwindowmanager.
50 <div id="Getting Start"></div>
54 <div id="Supported environment"></div>
56 ### Supported environment
58 | Item | Description |
59 |:------------|:----------------------------------|
60 | AGL version | Electric Eel |
61 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
64 <div id="Build"></div>
73 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
78 Then you can find the following recipes.
80 * `meta-agl-devel/meta-hmi-framework/homescreen-2017`
82 * `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
84 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
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
99 $ cd ./build/tmp/deploy/sdk/
100 $ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-toolchain-4.99.2.sh
105 <div id="Configuring"></div>
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.
112 <feature name="urn:AGL:widget:required-api">
113 <param name="homescreen" value="ws" />
114 <param name="windowmanager" value="ws" />
120 <div id="How to call HomeScreen and WindowManager APIs from your Application?"></div>
122 ## How to perform on-screen display on OnScreenApp
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.
130 "app": "<Application name>",
131 "message": "<Message string>",
132 "file": "<QML file path>",
133 "mask": "<Display mask image file>"
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.
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).
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.
151 Example) Execution of on_screen_reply event by QML Button click
157 offImage: 'images/button.svg'
160 eventHandler.onScreenReply("{ \"<Application name>\": \"<Message string>\" }");
170 <div id="Supported usecase"></div>
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.
181 <div id="Operation check"></div>
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.
189 $ afm-util start onscreenapp@0.1
190 $ afb-client-demo ws://localhost:1024/api?token=HELLO
192 homescreen subscribe { "event" : "on_screen_reply" }
194 homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"incoming call\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }
196 homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"error\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
198 homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"rejected\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
200 homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"call rejected\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }