diff options
Diffstat (limited to 'doc/ApplicationGuide.md')
| -rw-r--r-- | doc/ApplicationGuide.md | 271 |
1 files changed, 221 insertions, 50 deletions
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md index dd3f1f0..9c5c409 100644 --- a/doc/ApplicationGuide.md +++ b/doc/ApplicationGuide.md @@ -3,7 +3,7 @@ <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> +<div align="right">21th/Nov/2018</div> * * * @@ -21,12 +21,17 @@ - [Software Architecture](#Software\ Architecture) - [API reference](#API\ reference) - [Sequence](#Sequence) - - [Initialize](#InitializeSequence) - - [Tap Shortcut](#TapShortcutSequence) - - [On Screen Message / Reply Sequence](#OnScreenMessageSequence) + - [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) * * * @@ -45,12 +50,16 @@ HomeScreen can start/switch applications run in AGL, also displays information s 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 +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. @@ -84,12 +93,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/agl-service-homescreen-2017` +* `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher` + +* `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** @@ -109,6 +122,7 @@ To use HomeScreen API, an application shall paste the following configuration de ``` <feature name="urn:AGL:widget:required-api"> <param name="homescreen" value="ws" /> + <param name="windowmanager" value="ws" /> </feature> ``` @@ -119,7 +133,7 @@ To use HomeScreen API, an application shall paste the following configuration de ### 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,16 +145,16 @@ 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\ 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). @@ -152,15 +166,29 @@ 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, - 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. * * * <div id="Software\ Architecture"></div> @@ -182,7 +210,7 @@ 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. +"libhomescreen" and "agl-service-homescreen" provides several kinds of APIs. <div id="Home\ Screen\ Specific\ API"></div> @@ -190,7 +218,7 @@ The communication protocols between libhomescreen and upper binder, upper binder - [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,6 +227,12 @@ 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) + * * * @@ -209,7 +243,6 @@ The communication protocols between libhomescreen and upper binder, upper binder <div id="InitializeSequence"></div> ### Initialize Sequence - * deprecated  <div id="TapShortcutSequence"></div> @@ -217,11 +250,31 @@ The communication protocols between libhomescreen and upper binder, upper binder ### 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> @@ -232,43 +285,31 @@ You can find sample implementation of HomeScreen as below. * `libhomescreen/sample/template` -### Appendix +# Limitation +Now OnScreenApp is developing,approximately it will finished at GG. -``` -@startuml -title Application initialization phase (ex. registerCallback) -entity App -entity HomeScreenBinder -entity HomeScreenGUI -App->HomeScreenBinder: init(port, token) -App->HomeScreenBinder: subscribe() +# Next Plan +None. -note over HomeScreenBinder - Register the event the App wishes to receive - ・tap_shortcut - ・on_screen_message - ・on_screen_reply -end note - -App->HomeScreenBinder: registerCallback() - -@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 @@ -293,6 +334,30 @@ HomeScreenBinder->App: event_handler(application_id) ``` @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 entity App entity HomeScreenBinder @@ -317,3 +382,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"}, +<font color=red >"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 |