diff options
Diffstat (limited to 'doc/ApplicationGuide.md')
| -rw-r--r-- | doc/ApplicationGuide.md | 251 |
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  -<div id="TapShortcutSequence"></div> - ### Tap Shortcut Sequence  -<div id="ShowWindowSequence"></div> - ### ShowWindow Sequence  -<div id="OnScreenMessageSequence"></div> - ### On Screen Message / Reply Sequence  -<div id="ShowOnscreenSequence"></div> - ### ShowOnScreen Sequence  -<div id="ShowNotificationSequence"></div> - ### ShowNotification Sequence  -<div id="ShowInformationSequence"></div> - ### ShowInformation Sequence  +* * * -<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 |