summaryrefslogtreecommitdiffstats
path: root/doc/ApplicationGuide.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ApplicationGuide.md')
-rw-r--r--doc/ApplicationGuide.md251
1 files changed, 142 insertions, 109 deletions
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md
index 9c5c409..183ae3e 100644
--- a/doc/ApplicationGuide.md
+++ b/doc/ApplicationGuide.md
@@ -1,84 +1,69 @@
**HomeScreen GUI Application / HomeScreen Service 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">21th/Nov/2018</div>
+ Revision: 0.1
+ TOYOTA MOTOR CORPORATION
+ Advanced Driver Information Technology
+ 17th/June/2019
* * *
-<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)
-- [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](#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)
* * *
-<div id="Target\ reader\ of\ this\ document"></div>
-
## Target reader of this document
Application developer whose software uses HomeScreen.
* * *
-<div id="Overview"></div>
-
## 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(HomeScreenGUI):
- https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen
-launcher(LauncherGUI)
- https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher
-agl-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
+- [homescreen(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen)
+- [launcher(LauncherGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher)
+- [agl-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.
-<div id="Getting\ Start"></div>
+* * *
## Getting Start
-<div id="Supported\ environment"></div>
-
### Supported environment
| Item | Description |
|:------------|:----------------------------------|
-| AGL version | Electric Eel |
+| AGL version | Grumpy Guppy |
| Hardware | Renesas R-Car Starter Kit Pro(M3) |
-<div id="Build"></div>
-
### Build
**Download recipe**
@@ -111,11 +96,6 @@ $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-sma
$ bitbake agl-demo-platform
```
-
-* * *
-
-<div id="Configuring"></div>
-
### Configuring
To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
@@ -126,10 +106,6 @@ To use HomeScreen API, an application shall paste the following configuration de
</feature>
```
-* * *
-
-<div id="How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?"></div>
-
### How to call HomeScreen APIs from your Application?
HomeScreen provides a library which is called "libhomescreen".
This library treats "json format" as API calling.
@@ -151,20 +127,15 @@ Execute the "showWindow()" function.
libhs->showWindow("application_id", "display_area");
```
-Regarding the detail of showWindow() API, please refer [this](#HomeScreen\ API) section.
+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).
-
-
-<br />
+See also our [Sample code](#sample-code).
* * *
-<div id="Supported\ usecase"></div>
-
## Supported usecase
1. HomeScreenGUI sending showWindow event to applications
- Applications using libhomescreen to subscribe the showWindow event,
@@ -189,9 +160,8 @@ See also our [Sample code](#Sample\ code).
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.
-* * *
-<div id="Software\ Architecture"></div>
+* * *
## Software Architecture
The architecture of HomeScreen is shown below.
@@ -207,91 +177,154 @@ The communication protocols between libhomescreen and upper binder, upper binder
* * *
-<div id="API%20reference"></div>
-
## API reference
"libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
-<div id="Home\ Screen\ Specific\ API"></div>
-
### 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#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)
-- [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85)
-- [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f)
-- [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)
+- LibHomeScreen::init (const int port, const std::string &token)
+```
+ port [in] : This argument should be specified to the port number to be used for websocket
+ token [in] : This argument should be specified to the token to be used for websocket
+ Create connection to homescreen-service by port and token which provided by
+ application framework. This API must be called before calling other api.
+```
+- LibHomeScreen::tapShortcut(const char *application_id)
+```
+ application_id [in] : Tapped application id (label)
-* * *
+ This api is deprecated, recommend using showWindow.
+```
+- LibHomeScreen::onScreenMessage(const char *display_message)
+```
+ display_message [in] : message for display
-<div id="Sequence"></div>
+ This api is deprecated, recommend using showWindow/hideWindow to call onscreenapp.
+```
+- LibHomeScreen::onScreenReply(const char *reply_message)
+```
+ reply_message [in] : message for reply
-## Sequence
+ This api is deprecated, recommend using replyShowWindow.
+```
+- LibHomeScreen::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)
+```
+ event_cb [in] : This argument should be specified to the callback for subscribed event
+ reply_cb [in] : This argument should be specified to the reply callback for call function
+ hangup_cb [in] : This argument should be specified to the hangup callback for call function
+
+ This api is deprecated, recommend using set_event_handler.
+```
+- LibHomeScreen::set_event_handler(enum EventType et, handler_func f)
+```
+ et [in] : event name
+ f [in] : event handler
+
+ Setting event handler for Homescreen-Service Event.
+```
+- LibHomeScreen::call(const string& verb, struct json_object* arg)
+- LibHomeScreen::call(const char* verb, struct json_object* arg)
+```
+ verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut")
+ arg [in] : This argument should be specified to the argument of API.
+ And this argument expects JSON object
+
+ Call homescreen-service verb.
+```
+- LibHomeScreen::subscribe(const string& event_name)
+```
+ event_name [in] : This argument should be specified to the event name
+
+ Subscribe homescreen-service event. Deprecated, recommend using set_event_handler.
+```
+- LibHomeScreen::unsubscribe(const string& event_name)
+```
+ event_name [in] : This argument should be specified to the event name
+
+ Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler.
+```
+- LibHomeScreen::showWindow(const char* application_id, json_object* json)
+```
+ application_id [in] : This argument should be specified to the application's id
+ json [in] : This argument should be specified to the json parameters
+
+ Request to show the window of application_id, and set display area in json liked
+ {"area":"normal.full"}.
+```
+- LibHomeScreen::hideWindow(const char* application_id)
+```
+ application_id [in] : This argument should be specified to the application's id
-<div id="InitializeSequence"></div>
+ Request to hide the window of application_id.
+```
+- LibHomeScreen::replyShowWindow(const char* application_id, json_object* json)
+```
+ application_id [in] : This argument should be specified to the onscreen reply to applilcation id
+ json [in] : This argument should be specified to the json parameters
+
+ Post reply information to who called showWindow.
+```
+- LibHomeScreen::showNotification(json_object* json)
+```
+ json [in] : This argument should be specified to the json parameters.
+
+ Post Notification to Homescreen which will display at top area of Homescreen.
+```
+- LibHomeScreen::showInformation(json_object* json)
+```
+ json [in] : This argument should be specified to the json parameters.
+
+ Post Information to Homescreen which will display at bottom area of Homescreen.
+```
+
+* * *
+
+## Sequence
### Initialize Sequence
![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
-<div id="TapShortcutSequence"></div>
-
### Tap Shortcut Sequence
![tap_shortcut.svg](parts/tap_shortcut.svg)
-<div id="ShowWindowSequence"></div>
-
### ShowWindow Sequence
![showWindow.svg](parts/showWindow.svg)
-<div id="OnScreenMessageSequence"></div>
-
### On Screen Message / Reply Sequence
![on_screen_message.svg](parts/on_screen_message.svg)
-<div id="ShowOnscreenSequence"></div>
-
### ShowOnScreen Sequence
![showOnScreen.svg](parts/showOnScreen.svg)
-<div id="ShowNotificationSequence"></div>
-
### ShowNotification Sequence
![showNotification.svg](parts/showNotification.svg)
-<div id="ShowInformationSequence"></div>
-
### ShowInformation Sequence
![showInformation.svg](parts/showInformation.svg)
+* * *
-<div id="Sample\ code"></div>
-
-# Sample code
+## Sample code
You can find sample implementation of HomeScreen as below.
* `libhomescreen/sample/simple-egl`
* `libhomescreen/sample/template`
-# Limitation
-Now OnScreenApp is developing,approximately it will finished at GG.
+* * *
-# Next Plan
+## Limitation
None.
-# Appendix
+* * *
+
+## Next Plan
+None.
+
+* * *
+
+## Appendix
```
@startuml