diff options
| -rw-r--r-- | doc/ApplicationGuide.md | 189 | ||||
| -rw-r--r-- | doc/api-services-book.yml | 1 |
2 files changed, 104 insertions, 86 deletions
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md index 5bbf234..902e9b6 100644 --- a/doc/ApplicationGuide.md +++ b/doc/ApplicationGuide.md @@ -1,75 +1,63 @@ **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">26th/Sep/2017</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](#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) + - [On Screen Message / Reply Sequence](#on-screen-message-/-reply-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-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-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 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 | Funky Flounder | | Hardware | Renesas R-Car Starter Kit Pro(M3) | -<div id="Build"></div> - ### Build **Download recipe** @@ -98,11 +86,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. @@ -112,10 +95,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. @@ -141,16 +120,10 @@ Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API 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. - -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 ShortCut Icon tapped event to applications - Applications using libhomescreen to subscribe the tapShortcut event, @@ -163,8 +136,6 @@ See also our [Sample code](#Sample\ code). * * * -<div id="Software\ Architecture"></div> - ## Software Architecture The architecture of HomeScreen is shown below. HomeScreen is the service designed to be used by multiple applications. @@ -179,60 +150,108 @@ The communication protocols between libhomescreen and upper binder, upper binder * * * -<div id="API%20reference"></div> - ## API reference "libhomescreen" and "agl-service-homescreen-2017" 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_name)](api-ref/html/de/dd0/class_lib_home_screen.html#afb571c9577087b47065eb23e7fdbc903) -- [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) +- 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_name) +``` + application_name [in] : Tapped application name (label) -<div id="Sequence"></div> + Request to show the window of application_name. +``` +- LibHomeScreen::onScreenMessage(const char *display_message) +``` + display_message [in] : message for display -## Sequence + Request to display message in onscreen. +``` +- LibHomeScreen::onScreenReply(const char *reply_message) +``` + reply_message [in] : message for reply -<div id="InitializeSequence"></div> + Post reply message to application. +``` +- 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. +``` + +* * * + +## Sequence ### Initialize Sequence  * deprecated  -<div id="TapShortcutSequence"></div> - ### Tap Shortcut Sequence  -<div id="OnScreenMessageSequence"></div> - ### On Screen Message / Reply 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` -### Appendix +* * * + +## Limitation +None. + +* * * + +## Next Plan +None. + +* * * + +## Appendix ``` @startuml diff --git a/doc/api-services-book.yml b/doc/api-services-book.yml index bb581a8..f5660d7 100644 --- a/doc/api-services-book.yml +++ b/doc/api-services-book.yml @@ -9,5 +9,4 @@ books: version: flounder chapters: - url: ApplicationGuide.md - destination: 3_1-HomeScreen-Guide.md name: Home Screen Developper Guide
\ No newline at end of file |