X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=doc%2FApplicationGuide.md;h=aaf7bd759f0bfef0395cca8468ef883efa8451ba;hb=da0e4c298d2335e1500484fb6b650cd6a09c8640;hp=dd3f1f0ee4adc3b51add2356e06a5a2360179b9f;hpb=b5702d25b7b5386fabd6a81a748ea2d6fe647fcd;p=apps%2Fagl-service-homescreen.git
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md
index dd3f1f0..aaf7bd7 100644
--- a/doc/ApplicationGuide.md
+++ b/doc/ApplicationGuide.md
@@ -1,75 +1,69 @@
**HomeScreen GUI Application / HomeScreen Service Guide**
====
-
Revision: 0.1
-TOYOTA MOTOR CORPORATION
-Advanced Driver Information Technology
-26th/Sep/2017
+ Revision: 0.1
+ TOYOTA MOTOR CORPORATION
+ Advanced Driver Information Technology
+ 13th/May/2019
* * *
-
-
## 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)
-- [Software Architecture](#Software\ Architecture)
-- [API reference](#API\ reference)
-- [Sequence](#Sequence)
- - [Initialize](#InitializeSequence)
- - [Tap Shortcut](#TapShortcutSequence)
- - [On Screen Message / Reply Sequence](#OnScreenMessageSequence)
-- [Sample code](#Sample\ code)
-- [Limitation](#Limitation)
-- [Next Plan](#Next\ Plan)
+- [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)
+- [Software Architecture](#software-architecture)
+- [API reference](#api-reference)
+- [Sequence](#sequence)
+ - [Initialize](#initialize-sequence)
+ - [Tap Shortcut(deprecated)](#tap-shortcut-sequence)
+ - [ShowWindow](#showwindow-sequence)
+ - [On Screen Message / Reply Sequence(deprecated)](#on-screen-message-reply-sequence)
+ - [ShowOnscreen](#showonscreen-sequence)
+ - [ShowNotification](#shownotification-sequence)
+ - [ShowInformation](#showinformation-sequence)
+- [Sample code](#sample-code)
+- [Limitation](#limitation)
+- [Next Plan](#next-plan)
+- [Appendix](#appendix)
* * *
-
-
## Target reader of this document
Application developer whose software uses HomeScreen.
* * *
-
-
## Overview
HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
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
+- [homescreen(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen)
+- [launcher(LauncherGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher)
+- [gl-service-homescreen(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen)
+- [libhomescreen(library for application to communication with HomeScreenBinder]( https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen)
+- [libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen)
Also HomeScreenGUI is using libwindowmanager.
-
+* * *
## Getting Start
-
-
### Supported environment
| Item | Description |
|:------------|:----------------------------------|
-| AGL version | Electric Eel |
+| AGL version | Grumpy Guppy |
| Hardware | Renesas R-Car Starter Kit Pro(M3) |
-
-
### Build
**Download recipe**
@@ -84,12 +78,16 @@ $ repo sync
Then you can find the following recipes.
-* `meta-agl-devel/meta-hmi-framework/homescreen-2017`
+* `meta-agl-demo/recipes-demo-hmi/homescreen`
+
+* `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
-* `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
+* `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
* `meta-agl-demo/recipes-demo-hmi/libhomescreen`
+* `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
+
**Bitbake**
@@ -98,28 +96,20 @@ $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-sma
$ bitbake agl-demo-platform
```
-
-* * *
-
-
-
### Configuring
To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
```
+
```
-* * *
-
-
-
### How to call HomeScreen APIs from your Application?
HomeScreen provides a library which is called "libhomescreen".
This library treats "json format" as API calling.
-For example, if an application wants to call "tap_shortcut()" API, the you should implement as below.
+For example, if an application wants to call "showWIndow()" API, the you should implement as below.
At first the application should create the instance of libhomescreen.
@@ -131,40 +121,48 @@ libhs->init(port, token);
The port and token is provided by Application Framework
-Execute the "tapShortcut()" function.
+Execute the "showWindow()" function.
```
-libhs->tapShortcut("application_id");
+libhs->showWindow("application_id", "display_area");
```
-Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API) section.
-The first parameter is the name of API, so in this case "tap_shortcut" is proper string.
-And the second parameter corresponds to arguments of "connect()" API.
-
+Regarding the detail of showWindow() API, please refer [this](#homescreen-specific-api) section.
+The first parameter is the appid of application which want to display,liked "dashboard".
+And the second parameter corresponds to display_area which defined by windowmanager,usually "normal",
+so in this case "showWindow" the two parameters are proper string.
-See also our [Sample code](#Sample\ code).
-
-
-
+See also our [Sample code](#sample-code).
* * *
-
-
## Supported usecase
-1. HomeScreenGUI sending ShortCut Icon tapped event to applications
- - Applications using libhomescreen to subscribe the tapShortcut event,
- HomeScreenGUI will send ShortCut Icon tapped event to applications.
-2. Display OnScreen messages
+1. HomeScreenGUI sending showWindow event to applications
+ - Applications using libhomescreen to subscribe the showWindow event,
+ HomeScreenGUI will send showWindow event to applications.
+2. Display OnScreen messages(deprecated)
- Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
will get these message and display.
-3. Get OnSreen Reply event
+3. Get OnSreen Reply event(deprecated)
- When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
+4. Display OnScreen by showWindow
+ - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will
+ display request OnScreen.
+5. Hide OnScreen by hideWindow
+ - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp
+ will hide OnScreen.
+6. Send OnScreen Reply by replyShowWindow
+ - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
+ back to application.
+7. Show Notification on HomeScreenGUI
+ - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will
+ display the notification contents on the screen top area.
+8. Show Information on HomeScreenGUI
+ - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will
+ display the information contents on the screen bottom area.
* * *
-
-
## Software Architecture
The architecture of HomeScreen is shown below.
HomeScreen is the service designed to be used by multiple applications.
@@ -179,18 +177,14 @@ The communication protocols between libhomescreen and upper binder, upper binder
* * *
-
-
## API reference
-"libhomescreen" and "agl-service-homescreen-2017" provides several kinds of APIs.
-
-
+"libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
### HomeScreen Specific API
- [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc)
- [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220)
-- [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#afb571c9577087b47065eb23e7fdbc903)
+- [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a6ca8ff4a2aa019a735afaff713e0ef44)
- [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c)
- [onScreenReply(const char *reply_message)](api-ref/html/de/dd0/class_lib_home_screen.html#a6c065f41f2c5d1f58d2763bfb4da9c37)
- [registerCallback (void(*event_cb)(const std::string &event, struct json_object *event_contents), void(*reply_cb)(struct json_object *reply_contents), void(*hangup_cb)(void)=nullptr)](api-ref/html/de/dd0/class_lib_home_screen.html#a2789e8a5372202cc36f48e71dbb9b7cf)
@@ -199,76 +193,77 @@ The communication protocols between libhomescreen and upper binder, upper binder
- [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643)
- [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738)
- [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6)
+- [showWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a69fc770cb3f94d30a10c2c8c81eb892f)
+- [hideWindow (const char* application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a4dbaea6c7b310e8ce7207155ff11b32a)
+- [replyShowWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a6310b129fc85ef0623e2e2063950cc4b)
+- [showNotification (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a93ad567ed597a80a344ba82457c2bd7f)
+- [showInformation (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#ada999aeb0444c964428bdf1ee236727f)
* * *
-
-
## Sequence
-
-
### Initialize Sequence
-![initialize-registercallback.svg](parts/initialize-registercallback.svg) * deprecated
![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
-
-
### Tap Shortcut Sequence
![tap_shortcut.svg](parts/tap_shortcut.svg)
-
+### ShowWindow Sequence
+![showWindow.svg](parts/showWindow.svg)
### On Screen Message / Reply Sequence
![on_screen_message.svg](parts/on_screen_message.svg)
+### ShowOnScreen Sequence
+![showOnScreen.svg](parts/showOnScreen.svg)
-
+### ShowNotification Sequence
+![showNotification.svg](parts/showNotification.svg)
-# Sample code
+### ShowInformation Sequence
+![showInformation.svg](parts/showInformation.svg)
+
+* * *
+
+## Sample code
You can find sample implementation of HomeScreen as below.
* `libhomescreen/sample/simple-egl`
* `libhomescreen/sample/template`
-### Appendix
+* * *
-```
-@startuml
-title Application initialization phase (ex. registerCallback)
-entity App
-entity HomeScreenBinder
-entity HomeScreenGUI
-App->HomeScreenBinder: init(port, token)
-App->HomeScreenBinder: subscribe()
+## Limitation
+Now OnScreenApp is developing,approximately it will finished at GG.
-note over HomeScreenBinder
- Register the event the App wishes to receive
- ã»tap_shortcut
- ã»on_screen_message
- ã»on_screen_reply
-end note
+* * *
-App->HomeScreenBinder: registerCallback()
+## Next Plan
+None.
-@enduml
-```
+* * *
+
+## Appendix
```
@startuml
-title Application initialization phase (ex. set_event_handler)
+
+title Application initialization phase
+
entity App
entity HomeScreenBinder
entity HomeScreenGUI
+
App->HomeScreenBinder: init(port, token)
App->HomeScreenBinder: set_event_handler()
note over HomeScreenBinder
setup event handler the App wishes to receive
- ã»LibHomeScreen::Event_TapShortcut
- ã»LibHomeScreen::Event_OnScreenMessage
- ã»LibHomeScreen::Event_OnScreenReply
+ ã»LibHomeScreen::Event_ShowWindow
+ ã»LibHomeScreen::Event_HideWindow
+ ã»LibHomeScreen::Event_ReplyShowWindow
end note
@enduml
@@ -291,6 +286,30 @@ HomeScreenBinder->App: event_handler(application_id)
@enduml
```
+```
+@startuml
+
+title Application callback event showWindow phase
+
+actor user
+entity "homescreen-service" as hss
+entity launcher
+entity App
+entity windowmanager as wm
+
+user-->launcher: tap app's icon
+launcher->hss: showWindow()
+note over hss,App
+{"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
+end note
+hss->App: push showWindow event
+App->wm: activateWindow("application_name","display area")
+wm-->App: push syncDraw event
+App->App: display
+
+@enduml
+```
+
```
@startuml
title Application Callback Event On Screen Message / Reply phase
@@ -317,3 +336,109 @@ HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
HomeScreenBinder->App: event_handler(reply_message)
@enduml
```
+
+```
+@startuml
+
+title show/hide onscreen phase
+
+actor user
+entity "homescreen-service" as hss
+entity App
+entity onscreenapp
+entity windowmanager as wm
+
+== show onscreen ==
+user->App: the operation request onscreen
+App->hss: showWindow()
+note over App,hss
+{"application_id":"onscreenapp",
+"parameter":{"area":"display area", "file":"qml file path",
+"data":{"the datas to onscreen qml"}}}
+end note
+
+hss->onscreenapp: push showWindow event
+note over hss,onscreenapp
+{"application_id":"onscreenapp",
+"parameter":{"area":"display area", "file":"qml file path",
+"data":{"the datas to onscreen qml"},
+"replyto":"caller application id"
+}}
+end note
+
+onscreenapp->onscreenapp: get and save parameters
+onscreenapp->wm: activateWindow("onscreeapp", "display area")
+alt can show
+wm-->onscreenapp: push syncDraw event
+onscreenapp->wm: endDraw("onscreeapp")
+onscreenapp->onscreenapp: load and display qml file
+else can't show
+note over onscreenapp,wm
+do nothing
+end note
+end
+
+== hide onscreen ==
+
+user->onscreenapp: tap onscreen's button
+onscreenapp->hss: replyShowWindow()
+note over onscreenapp,hss
+{"application_id":"the application id who called onscreenapp",
+"parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
+end note
+hss->App: push replyShowWindow event
+App->App: call reply function
+App->hss: hideWindow("onscreenapp")
+hss->onscreenapp: push hideWindow event
+note over hss,onscreenapp
+{"application_id":"request hideWindow application id"}
+end note
+onscreenapp->wm: deactivateWindow("onscreenapp");
+onscreenapp->onscreenapp: hide window
+
+@enduml
+```
+
+```
+@startuml
+
+title show notification on HomeScreen top area
+
+entity "homescreen-service" as hss
+entity homescreen
+entity App
+
+App->hss: showNotification()
+note over App,hss
+{"icon":"display icon", "text":"display text"}
+end note
+hss-> homescreen: push showNotification event
+note over hss,homescreen
+{"application_id":"request application id",
+"parameter":{"icon":"display icon", "text":"display text"}}
+end note
+
+homescreen->homescreen: display notification message 3s
+
+@enduml
+```
+
+```
+@startuml
+
+title show information on HomeScreen bottom area
+
+entity "homescreen-service" as hss
+entity homescreen
+entity App
+
+App->hss: showInformation()
+note over hss
+{"info":"display information"}
+end note
+hss-> homescreen: push showInformation event
+
+homescreen->homescreen: display information message 3s
+
+@enduml
+```
\ No newline at end of file