X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=doc%2FApplicationGuide.md;fp=doc%2FApplicationGuide.md;h=3dcb2489659f963963a62013f754438254b415c7;hb=b2670af592e664ed304f7df77d84f1964f039636;hp=0000000000000000000000000000000000000000;hpb=ec044f44133cad1d12311345437b13b1a953226e;p=apps%2Fonscreenapp.git
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md
new file mode 100644
index 0000000..3dcb248
--- /dev/null
+++ b/doc/ApplicationGuide.md
@@ -0,0 +1,203 @@
+**OnScreen Application Guide**
+====
+
Revision: 0.1
+TOYOTA MOTOR CORPORATION
+Advanced Driver Information Technology
+12th/Dec/2017
+
+* * *
+
+
+
+## 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)
+
+* * *
+
+
+
+## Target reader of this document
+Application developer who wants to realize on-screen display on HomeScreen using OnScreenApp.
+
+* * *
+
+
+
+## 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.
+
+
+
+## Getting Start
+
+
+
+### Supported environment
+
+| Item | Description |
+|:------------|:----------------------------------|
+| AGL version | Electric Eel |
+| Hardware | Renesas R-Car Starter Kit Pro(M3) |
+
+
+
+
+### 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
+```
+
+* * *
+
+
+
+### 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.
+
+```
+
+
+
+
+```
+
+* * *
+
+
+
+## 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": "",
+ "message": "",
+ "file": "",
+ "mask": ""
+}
+```
+
+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("{ \"\": \"\" }");
+ }
+ }
+```
+
+
+
+
+* * *
+
+
+
+## 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.
+
+* * *
+
+
+
+## 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\"}" }
+
+```
+