**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\"}" }

```