--- /dev/null
+**OnScreen Application Guide**
+====
+<div align="right">Revision: 0.1</div>
+<div align="right">TOYOTA MOTOR CORPORATION</div>
+<div align="right">Advanced Driver Information Technology</div>
+<div align="right">12th/Dec/2017</div>
+
+* * *
+
+<div id="Table of content"></div>
+
+## Table of content
+- [Target reader of this document](#Target reader of this document)
+- [Overview](#Overview)
+- [Getting Start](#Getting Start)
+ - [Supported environment](#Supported environment)
+ - [Build](#Build)
+ - [Configuring](#Configuring)
+ - [How to call HomeScreen APIs from your Application?](#How to call HomeScreen APIs from your Application?)
+- [Supported usecase](#Supported usecase)
+- [Operation check](#Operation check)
+
+* * *
+
+<div id="Target reader of this document"></div>
+
+## Target reader of this document
+Application developer who wants to realize on-screen display on HomeScreen using OnScreenApp.
+
+* * *
+
+<div id="Overview"></div>
+
+## Overview
+OnScreenApp realizes on-screen display on the HomeScreen receiving the on_screen_message event of HomeScreenBinding.
+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.
+OnScreenApp analyzes the command (JSON) acquired by on_screen_message, reads QML and displays it.
+
+You can find these projects in AGL gerrit.
+
+homescreen-2017(HomeScreenGUI):
+ https://gerrit.automotivelinux.org/gerrit/#/admin/projects/staging/homescreen-2017
+agl-service-homescreen-2017(HomeScreenBinder's binding library):
+ https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen-2017
+libhomescreen(library for application to communication with HomeScreenBinder):
+ https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen
+
+Also OnScreenApp is using qlibwindowmanager.
+
+<div id="Getting Start"></div>
+
+## Getting Start
+
+<div id="Supported environment"></div>
+
+### Supported environment
+
+| Item | Description |
+|:------------|:----------------------------------|
+| AGL version | Electric Eel |
+| Hardware | Renesas R-Car Starter Kit Pro(M3) |
+
+
+<div id="Build"></div>
+
+### Build
+
+**Download recipe**
+
+```
+$ mkdir WORK
+$ cd WORK
+$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
+$ repo sync
+
+```
+
+Then you can find the following recipes.
+
+* `meta-agl-devel/meta-hmi-framework/homescreen-2017`
+
+* `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
+
+* `meta-agl-demo/recipes-demo-hmi/libhomescreen`
+
+
+**Bitbake**
+
+```
+$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
+$ bitbake agl-demo-platform
+$ bitbake agl-demo-platform-crosssdk
+```
+
+**Export SDK**
+
+```
+$ cd WORK
+$ cd ./build/tmp/deploy/sdk/
+$ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-toolchain-4.99.2.sh
+```
+
+* * *
+
+<div id="Configuring"></div>
+
+### Configuring
+OnScreenApp uses HomeScreenBinding and WindowManager API.
+In order to use these APIs, you need to paste the following configuration definition into "config.xml" of your application.
+
+```
+<feature name="urn:AGL:widget:required-api">
+ <param name="homescreen" value="ws" />
+ <param name="windowmanager" value="ws" />
+</feature>
+```
+
+* * *
+
+<div id="How to call HomeScreen and WindowManager APIs from your Application?"></div>
+
+## How to perform on-screen display on OnScreenApp
+
+### Send message to perform on-screen display
+In order to perform on-screen display on OnScreenApp, it is necessary to use the on_screen_message () API provided by HomeScreenBinding.
+In the argument of on_screen_message (), pass the character string of JSON format below.
+
+```
+{
+ "app": "<Application name>",
+ "message": "<Message string>",
+ "file": "<QML file path>",
+ "mask": "<Display mask image file>"
+}
+```
+
+Since the application name is used as a key for specifying an application displayed on OnScreenApp, it needs to be unique.
+The message string is a character string for default display when a specific command or external QML is not read.
+For the QML file path and the display mask image file, the full path on the AGL system is described respectively.
+
+### Display QML file and mask image
+OnScreenApp has the function of reading and displaying QML file from outside.
+Even when there is no QML file, you can display a character string on the default User Interface.
+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).
+
+### Retrieve events from QML
+It is possible to execute "on_screen_reply()" of libhomescreen using the object called eventHandler in prepared QML.
+For example, by registering the event "Evnet_OnScreenReply" of libhomescreen on the application side,
+It is possible to implement processing by clicking buttons prepared on the QML.
+
+Example) Execution of on_screen_reply event by QML Button click
+
+```
+ ImageButton {
+ width: 300
+ height: 60
+ offImage: 'images/button.svg'
+
+ onClicked: {
+ eventHandler.onScreenReply("{ \"<Application name>\": \"<Message string>\" }");
+ }
+ }
+```
+
+
+<br />
+
+* * *
+
+<div id="Supported usecase"></div>
+
+## Supported usecase
+1. Display OnScreen messages
+ - Applications sending OnScreen messages to homescreen-service, and OnScreenApp
+ will get these message and display.
+2. Get OnSreen Reply event
+ - When OnScreen messages is displaying, OnScreenApp will send a reply event to applications.
+
+* * *
+
+<div id="Operation check"></div>
+
+## Operation check
+The operation on OnScreenApp can be confirmed by afb-client-demo.
+OnScreenApp includes QML files for Phone and System as operation confirmation samples.
+You can confirm the operation by executing the following command on the AGL on which OnScreenApp is installed.
+
+```
+$ afm-util start onscreenapp@0.1
+$ afb-client-demo ws://localhost:1024/api?token=HELLO
+
+homescreen subscribe { "event" : "on_screen_reply" }
+
+homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"incoming call\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }
+
+homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"error\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
+
+homescreen on_screen_message { "display_message" : "{\"app\":\"System\", \"message\":\"rejected\", \"file\":\"qrc:/system.qml\", \"mask\":\":/images/oval_1079x400.png\"}" }
+
+homescreen on_screen_message { "display_message" : "{\"app\":\"Phone\", \"message\":\"call rejected\", \"file\":\"qrc:/phone.qml\", \"mask\":\":/images/star_1079x400.png\"}" }
+
+```
+
Code Review / apps / onscreenapp.git / blobdiff