Define func_list as static
[apps/agl-service-homescreen.git] / doc / ApplicationGuide.md
1 **HomeScreen GUI Application / HomeScreen Service Guide**
2 ====
3 <div align="right">Revision: 0.1</div>
4 <div align="right">TOYOTA MOTOR CORPORATION</div>
5 <div align="right">Advanced Driver Information Technology</div>
6 <div align="right">21th/Nov/2018</div>
7
8 * * *
9
10 <div id="Table\ of\ content"></div>
11
12 ## Table of content
13 - [Target reader of this document](#Target\ reader\ of\ this\ document)
14 - [Overview](#Overview)
15 - [Getting Start](#Getting\ Start)
16         - [Supported environment](#Supported\ environment)
17         - [Build](#Build)
18         - [Configuring](#Configuring)
19         - [How to call HomeScreen APIs from your Application?](#How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?)
20 - [Supported usecase](#Supported\ usecase)
21 - [Software Architecture](#Software\ Architecture)
22 - [API reference](#API\ reference)
23 - [Sequence](#Sequence)
24         - [Initialize](###Initialize\ Sequence)
25         - [Tap Shortcut(deprecated)](###Tap\ Shortcut\ Sequence)
26     - [ShowWindow](###ShowWindow\ Sequence)
27         - [On Screen Message / Reply Sequence(deprecated)](###On\ Screen\ Message\ /\ Reply\ Sequence)
28     - [ShowOnscreen](###ShowOnscreen\ Sequence)
29     - [ShowNotification](###ShowNotification\ Sequence)
30     - [ShowInformation](###ShowInformation\ Sequence)
31 - [Sample code](#Sample\ code)
32 - [Limitation](#Limitation)
33 - [Next Plan](#Next\ Plan)
34 - [Appendix](#Appendix)
35
36 * * *
37
38 <div id="Target\ reader\ of\ this\ document"></div>
39
40 ## Target reader of this document
41 Application developer whose software uses HomeScreen.
42
43 * * *
44
45 <div id="Overview"></div>
46
47 ## Overview
48 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
49 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
50
51 You can find these projects in AGL gerrit.
52
53 homescreen(HomeScreenGUI):
54     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen
55 launcher(LauncherGUI)
56     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher
57 agl-service-homescreen(HomeScreenBinder's binding library):
58     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen
59 libhomescreen(library for application to communication with HomeScreenBinder):
60     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen
61 libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)
62     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen
63
64 Also HomeScreenGUI is using libwindowmanager.
65
66 <div id="Getting\ Start"></div>
67
68 ## Getting Start
69
70 <div id="Supported\ environment"></div>
71
72 ### Supported environment
73
74 | Item        | Description                       |
75 |:------------|:----------------------------------|
76 | AGL version | Electric Eel                      |
77 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
78
79
80 <div id="Build"></div>
81
82 ### Build
83
84 **Download recipe**
85
86 ```
87 $ mkdir WORK
88 $ cd WORK
89 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
90 $ repo sync
91
92 ```
93
94 Then you can find the following recipes.
95
96 * `meta-agl-demo/recipes-demo-hmi/homescreen`
97
98 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
99
100 * `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
101
102 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
103
104 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
105
106
107 **Bitbake**
108
109 ```
110 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
111 $ bitbake agl-demo-platform
112 ```
113
114
115 * * *
116
117 <div id="Configuring"></div>
118
119 ### Configuring
120 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
121
122 ```
123 <feature name="urn:AGL:widget:required-api">
124         <param name="homescreen" value="ws" />
125     <param name="windowmanager" value="ws" />
126 </feature>
127 ```
128
129 * * *
130
131 <div id="How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?"></div>
132
133 ### How to call HomeScreen APIs from your Application?
134 HomeScreen provides a library which is called "libhomescreen".
135 This library treats "json format" as API calling.
136 For example, if an application wants to call "showWIndow()" API, the you should implement as below.
137
138 At first the application should create the instance of libhomescreen.
139
140 ```
141 LibHomeScreen* libhs;
142 libhs = new LibHomeScreen();
143 libhs->init(port, token);
144 ```
145
146 The port and token is provided by Application Framework
147
148 Execute the "showWindow()" function.
149
150 ```
151 libhs->showWindow("application_id", "display_area");
152 ```
153
154 Regarding the detail of showWindow() API, please refer [this](#HomeScreen\ API) section.
155 The first parameter is the appid of application which want to display,liked "dashboard".
156 And the second parameter corresponds to display_area which defined by windowmanager,usually "normal",
157 so in this case "showWindow" the two parameters are proper string.
158
159 See also our [Sample code](#Sample\ code).
160
161
162 <br />
163
164 * * *
165
166 <div id="Supported\ usecase"></div>
167
168 ## Supported usecase
169 1. HomeScreenGUI sending showWindow event to applications
170         - Applications using libhomescreen to subscribe the showWindow event,
171         HomeScreenGUI will send showWindow event to applications.
172 2. Display OnScreen messages(deprecated)
173         - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
174         will get these message and display.
175 3. Get OnSreen Reply event(deprecated)
176         - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
177 4. Display OnScreen by showWindow
178     - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will
179         display request OnScreen.
180 5. Hide OnScreen by hideWindow
181     - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp
182         will hide OnScreen.
183 6. Send OnScreen Reply by replyShowWindow
184     - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
185         back to application.
186 7. Show Notification on HomeScreenGUI
187     - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will
188         display the notification contents on the screen top area.
189 8. Show Information on HomeScreenGUI
190     - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will
191         display the information contents on the screen bottom area.
192 * * *
193
194 <div id="Software\ Architecture"></div>
195
196 ## Software Architecture
197 The architecture of HomeScreen is shown below.
198 HomeScreen is the service designed to be used by multiple applications.
199 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
200 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
201 Usually application side binder has some business logic for each application, so the number of binders depend on the number of applications which use HomeScreen.
202 On the other hand, regarding lower binder there is only one module in the system. This binder receives all messages from multiple applications (in detail, it comes from upper layer binder).
203
204 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
205
206 ![software-stack.png](parts/software-stack.png)
207
208 * * *
209
210 <div id="API%20reference"></div>
211
212 ## API reference
213 "libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
214
215 <div id="Home\ Screen\ Specific\ API"></div>
216
217 ### HomeScreen Specific API
218
219 - [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc)
220 - [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220)
221 - [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a6ca8ff4a2aa019a735afaff713e0ef44)
222 - [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c)
223 - [onScreenReply(const char *reply_message)](api-ref/html/de/dd0/class_lib_home_screen.html#a6c065f41f2c5d1f58d2763bfb4da9c37)
224 - [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)
225 - [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85)
226 - [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f)
227 - [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643)
228 - [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738)
229 - [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6)
230 - [showWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a69fc770cb3f94d30a10c2c8c81eb892f)
231 - [hideWindow (const char* application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a4dbaea6c7b310e8ce7207155ff11b32a)
232 - [replyShowWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a6310b129fc85ef0623e2e2063950cc4b)
233 - [showNotification (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a93ad567ed597a80a344ba82457c2bd7f)
234 - [showInformation (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#ada999aeb0444c964428bdf1ee236727f)
235
236
237 * * *
238
239 <div id="Sequence"></div>
240
241 ## Sequence
242
243 <div id="InitializeSequence"></div>
244
245 ### Initialize Sequence
246 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
247
248 <div id="TapShortcutSequence"></div>
249
250 ### Tap Shortcut Sequence
251 ![tap_shortcut.svg](parts/tap_shortcut.svg)
252
253 <div id="ShowWindowSequence"></div>
254
255 ### ShowWindow Sequence
256 ![showWindow.svg](parts/showWindow.svg)
257
258 <div id="OnScreenMessageSequence"></div>
259
260 ### On Screen Message / Reply Sequence
261 ![on_screen_message.svg](parts/on_screen_message.svg)
262
263 <div id="ShowOnscreenSequence"></div>
264
265 ### ShowOnScreen Sequence
266 ![showOnScreen.svg](parts/showOnScreen.svg)
267
268 <div id="ShowNotificationSequence"></div>
269
270 ### ShowNotification Sequence
271 ![showNotification.svg](parts/showNotification.svg)
272
273 <div id="ShowInformationSequence"></div>
274
275 ### ShowInformation Sequence
276 ![showInformation.svg](parts/showInformation.svg)
277
278
279 <div id="Sample\ code"></div>
280
281 # Sample code
282 You can find sample implementation of HomeScreen as below.
283
284 * `libhomescreen/sample/simple-egl`
285
286 * `libhomescreen/sample/template`
287
288 # Limitation
289 Now OnScreenApp is developing,approximately it will finished at GG.
290
291 # Next Plan
292 None.
293
294 # Appendix
295
296 ```
297 @startuml
298
299 title Application initialization phase
300
301 entity App
302 entity HomeScreenBinder
303 entity HomeScreenGUI
304
305 App->HomeScreenBinder: init(port, token)
306 App->HomeScreenBinder: set_event_handler()
307
308 note over HomeScreenBinder
309     setup event handler the App wishes to receive
310     ・LibHomeScreen::Event_ShowWindow
311     ・LibHomeScreen::Event_HideWindow
312     ・LibHomeScreen::Event_ReplyShowWindow
313 end note
314
315 @enduml
316 ```
317
318 ```
319 @startuml
320 title Application Callback Event TapShortcut phase
321 entity App
322 entity HomeScreenBinder
323 entity HomeScreenGUI
324 App->HomeScreenBinder: set_event_handler()
325
326 note over App
327     LibHomeScreen::Event_TapShortcut
328 end note
329
330 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
331 HomeScreenBinder->App: event_handler(application_id)
332 @enduml
333 ```
334
335 ```
336 @startuml
337
338 title Application callback event showWindow phase
339
340 actor user
341 entity "homescreen-service" as hss
342 entity launcher
343 entity App
344 entity windowmanager as wm
345
346 user-->launcher: tap app's icon
347 launcher->hss: showWindow()
348 note over hss,App
349 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
350 end note
351 hss->App: push showWindow event
352 App->wm: activateWindow("application_name","display area")
353 wm-->App: push syncDraw event
354 App->App: display
355
356 @enduml
357 ```
358
359 ```
360 @startuml
361 title Application Callback Event On Screen Message / Reply phase
362 entity App
363 entity HomeScreenBinder
364 entity HomeScreenGUI
365
366 HomeScreenGUI->HomeScreenBinder: set_event_handler()
367
368 note over HomeScreenGUI
369     LibHomeScreen::Event_OnScreenMessage
370 end note
371
372
373 App->HomeScreenBinder: set_event_handler()
374
375 note over App
376     LibHomeScreen::Event_OnScreenReply
377 end note
378
379 App->HomeScreenBinder: onScreenMessage(display_message)
380 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
381 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
382 HomeScreenBinder->App: event_handler(reply_message)
383 @enduml
384 ```
385
386 ```
387 @startuml
388
389 title show/hide onscreen phase
390
391 actor user
392 entity "homescreen-service" as hss
393 entity App
394 entity onscreenapp
395 entity windowmanager as wm
396
397 == show onscreen ==
398 user->App: the operation request onscreen
399 App->hss: showWindow()
400 note over App,hss
401 {"application_id":"onscreenapp", 
402 "parameter":{"area":"display area", "file":"qml file path", 
403 "data":{"the datas to onscreen qml"}}}
404 end note
405
406 hss->onscreenapp: push showWindow event
407 note over hss,onscreenapp
408 {"application_id":"onscreenapp", 
409 "parameter":{"area":"display area", "file":"qml file path", 
410 "data":{"the datas to onscreen qml"},
411 <font color=red >"replyto":"caller application id"
412 }}
413 end note
414
415 onscreenapp->onscreenapp: get and save parameters
416 onscreenapp->wm: activateWindow("onscreeapp", "display area")
417 alt can show
418 wm-->onscreenapp: push syncDraw event
419 onscreenapp->wm: endDraw("onscreeapp")
420 onscreenapp->onscreenapp: load and display qml file
421 else can't show
422 note over onscreenapp,wm
423 do nothing
424 end note
425 end
426
427 == hide onscreen ==
428
429 user->onscreenapp: tap onscreen's button
430 onscreenapp->hss: replyShowWindow()
431 note over onscreenapp,hss
432 {"application_id":"the application id who called onscreenapp", 
433 "parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
434 end note
435 hss->App: push replyShowWindow event
436 App->App: call reply function
437 App->hss: hideWindow("onscreenapp")
438 hss->onscreenapp: push hideWindow event
439 note over hss,onscreenapp
440 {"application_id":"request hideWindow application id"}
441 end note
442 onscreenapp->wm: deactivateWindow("onscreenapp");
443 onscreenapp->onscreenapp: hide window
444
445 @enduml
446 ```
447
448 ```
449 @startuml
450
451 title show notification on HomeScreen top area
452
453 entity "homescreen-service" as hss
454 entity homescreen
455 entity App
456
457 App->hss: showNotification()
458 note over App,hss
459 {"icon":"display icon", "text":"display text"}
460 end note
461 hss-> homescreen: push showNotification event
462 note over hss,homescreen
463 {"application_id":"request application id", 
464 "parameter":{"icon":"display icon", "text":"display text"}}
465 end note
466
467 homescreen->homescreen: display notification message 3s
468
469 @enduml
470 ```
471
472 ```
473 @startuml
474
475 title show information on HomeScreen bottom area
476
477 entity "homescreen-service" as hss
478 entity homescreen
479 entity App
480
481 App->hss: showInformation()
482 note over hss
483 {"info":"display information"}
484 end note
485 hss-> homescreen: push showInformation event
486
487 homescreen->homescreen: display information message 3s
488
489 @enduml
490 ```