Add gitreview file for Lucky Lamprey branch
[apps/agl-service-windowmanager.git] / doc / ApplicationGuide.md
1 # Window Manager Application Guide
2
3 ## Table of content
4
5 - [Target reader of this document](#target-reader-of-this-document)
6 - [Overview](#overview)
7   - [Supported usecase](#supported-usecase)
8 - [Getting Started](#getting-started)
9   - [Build](#build-by-sdk)
10   - [Install](#install)
11   - [Bitbake](#bitbake)
12   - [Enable to call Window Manager](#enable-to-call-window-manager)
13 - [Software Architecture](#software-architecture)
14 - [Sequence](#sequence)
15 - [API reference](#api-reference)
16   - [Request to Window Manager](#request-to-window-manager)
17   - [Event from Window Manager](#event-from-window-manager)
18   - [Client Library](#client-library)
19 - [Sample code](#sample-code)
20 - [Policy Manager](#policy-manager)
21   - [Enabling split](#enabling-split)
22 - [Release Note](#release-note)
23
24 | Version | Author | Updated at |
25 |:-:|:-:|:-:|
26 | 0.8 | TOYOTA MOTOR CORPORATION| 22th/Feb/2019 |
27
28 * * *
29
30 ## Target reader of this document
31
32 This document is intended for developers and system integrators who
33 need to know, how Window manager works and how it is to be used.
34
35 ### Scope of this Document
36
37 This document covers Window manager that was implemented for TMC and
38 delivered to the Automotive Grade Linux (AGL) project. It includes its
39 implementation details, concepts of operation, configuration and usage.
40
41 It does not include
42
43 - document of the underlying architecture, see
44   [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
45
46 - document of the AGL application framework and its technologies,
47   see [AGL Application
48     Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
49
50 - document of HomeScreen, see
51   [HomeScreen](./ApplicationGuide.html).
52
53 It is highly recommended to have a good understanding of these documents
54 and projects before using Window manager.
55
56 * * *
57
58 # Overview
59
60 Window Manager is the service process which provides window management based on policy.
61 And implements a layout switching of applications on
62 multiple layers and with different layer layouts.
63 Window Manager is based on ivi layer management from GENIVI and AGL application framework.
64
65 Window Manager consists of
66
67 - afb-binder
68 - service binding library
69 - shared library for policy management
70 - configuration files
71
72 In order to understand Window Manager, the below figure shows the one of typical usecases.
73 In this example, there are two mode for window management.
74
75 1. Window Management in `Car Stops`
76 1. Window Management in `Car Runs`
77
78 ![Figure: Typical usecase](parts/state_change_example.png)
79
80 The important points are:
81
82 - Window transition should be done by Window Manager
83
84  Window Manager switch application displayed on top layer by user operation(touch shortcut button).
85  In this example, when an user touches `navigation` shortcut button, Window Manager displays `navigation` and hide `launcher`. Next, when an user touches `videoplayer` shortcut button, Window Manager divides a screen into two parts and display two applications.
86
87 - There is a priority `role` for each application.
88
89  Window Manager realizes state transition change based on the policy which consists of `role`.
90  According to the state transition table, it controls the visibility of application window, layout change, and so on.
91  The reasons why this is necessary are
92
93 - to support user driving
94 - not to disturb a driver concerns on driving for safety
95
96   In this example, for safety, when the car starts running, Window Manager set up the role `videoplayer`
97   to be masked and uncontrollable by user not to disturb driver concerns.
98   And, for supporting driving, set up `navigation` role to be displayed 3 seconds after the car ran.
99   In `Car Run` state, the user can't switch to other application from Navigation application until car stops.
100
101 ## Supported usecase
102
103 1. Window Management
104 - When an user chooses a different application, Window Manager changes the layout and then displays the application.
105 - When an user chooses a different application, Window Manager changes the layout and then hides the displayed application.
106 2. Policy Management
107 - Window Manager changes layout according to policy table based on `role`.
108 3. Define Layout by `area` configuration
109 - Window Manager realizes the abstracted `area` and can resize the window by using it. User can easily edit this configuration.
110
111 * * *
112
113 ## Getting Started
114
115 ### Build by SDK
116
117 ```bash
118 git clone https://gerrit.automotivelinux.org/gerrit/apps/agl-service-windowmanager
119 cd agl-service-windowmanager
120 mkdir build
121 cd build
122 source <your SDK path> // normally this is /opt/agl-sdk/environment
123 cmake ..
124 make
125 make package
126 ```
127
128 The widget package is populated in the 'package' directory.
129
130 ```bash
131 ls package/
132 root  windowmanager-service.wgt
133 ```
134
135 ### Install
136
137 Copy windowmanager-service.wgt to the file system then execute the following command.
138
139 ```bash
140 afm-util install windowmanager-service.wgt
141 ```
142
143 ## Bitbake
144
145 You can make Window Manager object files with the following two stage operations.
146
147 ### Download recipe
148
149 ```bash
150 mkdir WORK
151 cd WORK
152 repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
153 repo sync
154 ```
155
156 ### Execute Bitbake
157
158 ```bash
159 source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo hmi-framework
160 bitbake agl-demo-platform
161 ```
162
163 * * *
164
165 ## Enable to call Window Manager
166
167 To call Window Manager, it is important to enable the permission from security framework.
168 To use Window Manager API, an application or a service shall add the following configuration definition into "config.xml" of your application.
169
170 ```xml
171 <feature name="urn:AGL:widget:required-api">
172     <param name="windowmanager" value="ws" />
173 </feature>
174 ```
175
176 To call Window Manager function easily, Window Manager provides a library which is called "libwindowmanager".
177 This library provides a function style API calling interface.
178 So you can include the libwindowmanager.hpp header file, and can link against this library.
179 Please also refer to the sample application.
180
181 See also our [Sample code](#sample-code).
182
183 * * *
184
185 ## Software Architecture
186
187 The static relationship with other components is shown below.
188 The actual logic of Window Manager is the binding in Binder(afb-daemon).
189 Window Manager is based on AGL application framework,
190 so the IPC via websocket is protected by AGL application framework.
191
192 The upper binder is for the application side security context.
193 The lower binder is the Window Manager for the server side security context.
194 Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Window Manager.
195 On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications.
196
197 An application can use libwindowmanager.so to call Window Manager API simply.
198
199 Window Manager is based on the GENIVI layer management system.
200
201 ![wm_software_stack.png](parts/wm_software_stack.png)
202
203 ### Layers
204
205 Layers are entities that means the application stack group defined in `layers.json`.
206 This doesn't mean layer ID defined in GENIVI ivi layer.
207 The layer ID is used for application itself in Window Manager.
208 Currently, application can't have multiple surfaces in Window Manager.
209
210 ### Surfaces
211
212 Surfaces are *placed* on layers . The surface
213 will then be resized to dimensions, according to the name of `areas.json`
214 application requests by `activateWindow` or policy management.
215 As default, `normal.full` is set by libwindowmanager for native application.
216
217 ### Configuration
218
219 The window manager is configured with the *layers.json*, *areas.json*, *roles.db* configuration
220 files. By default they are searched in `${AFM_APP_INSTALL_DIR}/etc/`.
221
222 Sample configurations are provided with the window manager
223 implementation, these samples are installed to ${AFM_APP_INSTALL_DIR}/etc/ .
224
225 This configuration is supposed to be configured by policy designer which means OEM or Tier1.
226
227 #### layers.json
228
229 `layers.json` has three roles.
230
231 1. Create application containers `Layer`.
232 1. Set id range for applications.
233 1. Attach application to `Layer` according to the role application requests.
234
235 The sample configuration is here
236
237 ```json
238 {
239    "comment": "Surface ID to Layer ID mapping",
240
241    "main_surface": {
242       "surface_role": "HomeScreen",
243       "comment": "This surface should never be made invisible (The HomeScreen)"
244    },
245
246    "mappings": [
247       {
248          "role": "BackGroundLayer",
249          "name": "BackGroundLayer",
250          "layer_id": 999,
251          "comment": "Single BackGround layer map for the map, radio, music and video"
252       },
253       {
254          "role": "homescreen",
255          "name": "FarHomeScreen",
256          "layer_id": 1000,
257          "comment": "FarHomeScreen is the part of HomeScreen. The z order of this layer is lower than NearHomeScreen"
258       },
259       {
260          "role": "music|video|browser|radio|phone|map|hvac|settings|dashboard|poi|mixer|sdl|launcher|fallback",
261          "name": "Apps",
262          "layer_id": 1001,
263          "comment": "Range of IDs that will always be placed on layer 1001"
264       },
265       {
266          "role": "^on_screen.*",
267          "name": "OnScreen",
268          "layer_id": 9999,
269          "comment": "Range of IDs that will always be placed on the OnScreen layer, that gets a very high 'dummy' id of 9999"
270       }
271    ]
272 }
273 ```
274
275 Each mapping defines the following items to map corresponding surfaces
276 to a layer.
277
278 - `role` defines what kind of ability the application has. And the application will be attached to `Layer` according to the `role`.
279     A regular expression that application drawing names
280     are matched against. If applications match this regular expression,
281     the surface will be visible on this layer.
282
283 - `name` is just a name definition for `Layer`, it has no
284     functional use apart from identifying a layer with a name.
285 - `layer_id` is the id used in GENIVI IVI layer management control.
286
287 `Layer` stacks from beginning to end.
288
289 The above `Layer` example image is below.
290
291 ![wm_layer_stack.png](parts/wm_layer_stack.png)
292
293 Note:
294 "fallback" role is the special role. This role is set if the role application requests doesn't exist
295 in `layers.json`. Then, Window Manager will accept any applications.
296 If the "fallback" is not set in layers.json, window manager blocks the application displaying in such case.
297 In such a situation, you have to add your role(application name) at "role" in layers.json.
298
299 Note:
300 `BackGroundLayer` name of `Layer` is exception for work around. This layer is fallback layer not to stop event loop of application when it becomes invisible.
301 The problem is issued in <https://jira.automotivelinux.org/browse/SPEC-1484>.
302
303 #### areas.json
304
305 Area means abstract expressions of 2-dimensional size and position.
306 `areas.json` defines the area which an application is set.
307
308 ```json
309 {
310     "areas": [
311         {
312             "name": "fullscreen",
313             "rect": {
314                 "x": 0,
315                 "y": 0,
316                 "w": 1080,
317                 "h": 1920
318             }
319         },
320         {
321             "name": "normal.full",
322             "rect": {
323                 "x": 0,
324                 "y": 218,
325                 "w": 1080,
326                 "h": 1488
327             }
328         },
329         {
330             "name": "split.main",
331             "rect": {
332                 "x": 0,
333                 "y": 218,
334                 "w": 1080,
335                 "h": 744
336             }
337         },
338         {
339             "name": "split.sub",
340             "rect": {
341                 "x": 0,
342                 "y": 962,
343                 "w": 1080,
344                 "h": 744
345             }
346         }
347     ]
348 }
349 ```
350
351 The image of the above setting is described below.
352
353 ![wm_area.png](parts/wm_area.png)
354
355 - `name` is an abstract data of rectangle.
356
357 - `rect` has 4 arguments. `x`, `y` means the offset from (0, 0) of screen.`w` means the width of the area, and `h` means the height of the area. The dimensions can be specified relative to the screen dimensions.
358
359 The dimensions can be specified absolute to the screen dimensions. But if `fullscreen` is not suitable to screen dimensions, Window Manager scales the area automatically.
360
361 Note:
362
363 `fullscreen` must be set because this is the base size of scaling in Window Manger.
364
365 Note:
366
367 The direction of the coordinates depends on `transform` in weston.ini.
368 Currently, agl-demo-platform set `transform=270`.
369 This suppose to use screen vertically.
370
371 #### roles.db
372
373 * * *
374
375 ## Sequence
376
377 To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/hmiframework).
378
379 The typical sequence to render your application, follow the sequence below.
380
381 1. Register your role (and request surfaceID)
382
383 ![request_role.png](parts/request_role.png)
384
385 The above sequence is the initialization phase of your application to use Window Manager.
386 An Application has to register your `role` to Window Manager. For ivi-shell application, Window Manager generates surfaceID to input it into the function
387 to create surface. And also it is important for synchronization to get `syncDraw` event for receiving the request for resize and redraw, and notifying Window Manager of `endDraw`, so register callback function with setEventHandler for `syncDraw`.
388
389 [requestSurface](#requestSurface)
390
391 [setEventHandler](#wm_subscribe)
392
393 setEventHandler is API of libwindowmanager. This calls wm_subscribe internally.
394
395 2. Display your window
396
397 ![hmi_framework_designed_seq_toyota.png](parts/hmi_framework_designed_seq_toyota.png)
398
399 To display your window, your application has to request `activateWindow` with `role` and `area` to Window Manager.
400 Window Manager checks the app should be visible on the `area` according to the policy table using `role` .
401 If it is accepted, afb_req_success will be returned, and next Window Manager
402 will push the event `syncDraw` to applications which will be displayed. If it is denied, afb_req_fail will be returned. In this sample sequence, `syncDraw` is emitted to the apps who requested only,
403 but this shall be emitted to other applications whose size shall be changed.
404
405 [activateWindow](#activateWindow)
406
407 [syncDraw](#syncDraw)
408
409 [endDraw](#endDraw)
410
411 [flushDraw](#flushDraw)
412
413 3. Activate OnScreen Window
414
415 ![deactivate_window.png](parts/deactivate_window.png)
416
417 [deactivateWindow](#deactivateWindow)
418
419 [See sample code for more detail about OnScreen Window.](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps%2Fonscreenapp.git;a=summary)
420
421 The above sequence shows the sample of OnScreen Window.
422 If the role is high priority than NormapApp, Window Manager rejects NormalApp
423 request when OnScreenApp is displayed.
424
425 Note : Above repository is currently empty, so please refer to the sandbox branch.
426
427 * * *
428
429 ## API reference
430
431 ### Request to Window Manager
432
433 | Use | verb | version |
434 |:-:|:-:|:-:|
435 | Initialize | requestSurface | from 0.7 |
436 |            | wm_subscribe | from 0.7 |
437 |            | requestSurfaceXDG | from 0.7 |
438 |Activate/Deactivate| activateWindow | from 0.7 |
439 |            | deactivateWindow | from 0.7 |
440 |            | endDraw | from 0.7 |
441 | Change area size | changeAreaSize | from 0.8 |
442 | Get Infomation | getDisplayInfo | from 0.7 |
443 |                | getAreaList    | from 0.8 |
444
445 Note: We created this table from 0.7
446
447 The data of IPC via websocket consists of JSON.
448 This section describes the verb of API and key.
449 Normally, the body of requesting API will be here.
450
451 ### Initialize
452
453 #### *requestSurface*
454
455 Register your role to Window Manager and get surfaceID for ivi-shell. The role is used for policy management. SurfaceID is supposed to be set to the API `ivi_application_surface_create` of ivi-application protocol or set it to environment variable `QT_IVI_SURFACE_ID` if your app is Qt and integrate ivi-shell.
456
457 - verb : "requestSurface"
458 - argument : {"drawing_name":"your role"}
459
460 the value must be selected in layers.json.
461
462 argument example :
463
464 ```json
465 {
466   "drawing_name" : "navigation"
467 }
468 ```
469
470 #### *requestSurfaceXDG*
471
472 This API is for XDGLauncher, so it is not necessary for normal application.
473 XDGLauncher is created for XDG application for desktop app without editing for HMI-Framework.
474 Please see the repository in detail.
475 <https://gerrit.automotivelinux.org/gerrit/gitweb?p=staging%2Fxdg-launcher.git;a=summary>
476
477 #### *wm_subscribe*
478
479 Subscribe the Window Manager's event.
480 Application must subscribe `syncDraw` event.
481
482 - verb : "wm_subscribe"
483 - argument : {"event" : *event number*}
484
485 argument example :
486
487 ```json
488 {
489   "event" : 5
490 }
491 ```
492
493 The event is abstracted with a number (enumeration).
494
495 | Number | Event |
496 |:-:|:-:|
497 | 0 | "active" |
498 | 1 | "inactive" |
499 | 2 | "visible" |
500 | 3 | "invisible" |
501 | 4 | "syncDraw" |
502 | 5 | "flushDraw" |
503 | 6 | "screenUpdated" |
504
505 ### Activate/Deactivate
506
507 #### *activateWindow*
508
509 Request to display your application with `role` on the `area` to Window Manager.
510 Window Manager checks the app should be visible on the `area` and change layout according to the policy table using `role` .
511 If it is accepted, afb_req_success will be returned, and next Window Manager
512 will push the event `syncDraw` to applications which will be displayed.
513 If it is denied, afb_req_fail will be returned.
514
515 - verb : "activateWindow"
516 - argument : {"drawing_name" : "your role", "drawing_area" : "your area"}
517
518 the value must be selected among layers.json.
519
520 argument example :
521
522 ```json
523 {
524   "drawing_name" : "navigation",
525   "drawing_area" : "normal.full"
526 }
527 ```
528
529 #### *deactivateWindow*
530
531 Request to hide your application to Window Manager.
532 This verb is supposed to be used by high priority application which
533 are for example popup application or system UI application such like alert.
534 If Window Manager set the priority of popup high in the policy, Window Manager may not hide the popup even if normal applications
535 send `activateWindow` until popup application send `deactivateWindow` . This behavior depends on the policy table. After this request, Window Manager checks which app should be visible and change layout according to the policy table.
536
537 - verb : "deactivateWindow"
538 - argument : None
539
540 #### *endDraw*
541
542 Notify Window Manager of application finishes drawing.
543 This function must be sent in event `syncDraw`.
544 Otherwise, Window Manager will roll back to previous state and reject your request `activateWindow` .
545
546 - verb : "endDraw"
547 - argument : {"drawing_name" : "your role"}
548
549 argument example :
550
551 ```json
552 {
553   "drawing_name" : "navigation",
554 }
555 ```
556
557 #### *changeAreaSize*
558
559 Request to change the size of area and location. Then Window Manager sends `syncDraw` to the applications whose size and location will be changed.
560 The caller has responsible of appearance of layouts.
561
562 The use case of this function is shown in below.
563 The system application such like HomeScreen call this function, then the layout changes. The trigger may be user request on GUI, or system events and so on.
564
565 ![chnage_layout_img](parts/wm_change_layout.png)
566
567 The sequence is below.
568
569 ![change_layout_sequnce](parts/change_layout_seq.png)
570
571 - verb : "changeAreaSize"
572 - argument : {"areas" : [{"name":"area_name","rect":{"x":int,"y":int,"w":int,"h":int}, ...}]}
573
574 Note: Only the application whose role is written in whitelist is allowed to call this API. This is because marcious application can change the layouts. The layout should be controled by system application.
575
576 ### Get Information
577
578 #### *getDisplayInfo*
579
580 Get screen information such as resolution.
581
582 - verb : "getDisplayInfo"
583 - argument : None
584
585 Return : The screen information will return.
586
587 Return example :
588
589 ```json
590 {
591     "response":{
592         "width_pixel":1080,
593         "height_pixel":1920,
594         "width_mm":320,
595         "height_mm":520,
596         "scale":1
597     },
598     "jtype" : "afb-reply",
599     "request":{
600         "status":"success",
601         "info":"success",
602         "uuid":"05ae219a-0e56-4f46-af9f-3186a18cb110"
603     }
604 }
605 ```
606
607 Note :
608
609 "width_mm", "height_mm" is from output which is one of the wayland object.
610 These items lack reliability, so recommend not to use.
611
612 #### *getAreaList*
613
614 Get area definition defined in areas.json.
615
616 - verb : "getAreaList"
617 - argument : None
618
619 Return : The area definition list.
620
621 Return example :
622
623 ```json
624 {
625   "response":{
626     "areas":[
627       {
628         "name":"on_screen",
629         "rect":{
630           "x":0,
631           "y":218,
632           "w":1080,
633           "h":1488
634         }
635       },
636       {
637         "name":"restriction.split.sub",
638         "rect":{
639           "x":0,
640           "y":962,
641           "w":1080,
642           "h":744
643         }
644       }
645     ]
646   },
647   "jtype":"afb-reply",
648   "request":{
649     "status":"success",
650     "uuid":"0e6b8835-0df0-4a34-9718-125e6258b378"
651   }
652 }
653 ```
654
655 ### Event from Window Manager
656
657 | Number | Event | version |
658 |:-:|:-:|:-:|
659 | 0 | "active" | from 0.7|
660 | 1 | "inactive" | from 0.7 |
661 | 2 | "visible" | from 0.7 |
662 | 3 | "invisible" | from 0.7 |
663 | 4 | "syncDraw" | from 0.7 |
664 | 5 | "flushDraw" | from 0.7 |
665 | 6 | "screenUpdated" | from 0.7 |
666
667 Events also consists of JSON.
668 The data of event is contained in `data` such like
669
670 ```json
671 {
672     "event":"windowmanager\/active",
673     "date":{
674         "drawing_name":"navigation"
675     },
676     "jtype":"afb-event"
677 }
678 ```
679
680 "event" is the event name.
681 "data" is the data object from Window Manager and contains
682 the message of event.
683 This section describes "event" and the contents of "data".
684
685 #### active
686
687 This event means when the application becomes active state.
688
689 example :
690
691 ```json
692 {
693   "event":"windowmanager\/active",
694   "data":{
695     "drawing_name":"launcher"
696     }
697   },
698   "jtype":"afb-event"
699 }
700 ```
701
702 #### inactive
703
704 This event means when the application becomes inactive state.
705
706 example :
707
708 ```json
709 {
710   "event":"windowmanager\/inactive",
711   "data":{
712     "drawing_name":"launcher"
713     }
714   },
715   "jtype":"afb-event"
716 }
717 ```
718
719 #### visible
720
721 This event is issued when the application is visible state.
722
723 example :
724
725 ```json
726 {
727   "event":"windowmanager\/visible",
728   "data":{
729     "drawing_name":"launcher"
730     }
731   },
732   "jtype":"afb-event"
733 }
734 ```
735
736 #### invisible
737
738 This event is issued when the application is invisible state.
739
740 example :
741
742 ```json
743 {
744   "event":"windowmanager\/invisible",
745   "data":{
746     "drawing_name":"launcher"
747     }
748   },
749   "jtype":"afb-event"
750 }
751 ```
752
753 #### syncDraw
754
755 This event is issued by Window Manager state change operation in policy to the following cases.
756
757 - Your app requested `activateWindow` then your application will be resized or visible.
758 - Other app requested `activateWindow` then your application will be resized or visible.
759 - Window Manager change layout due to vehicle condition.
760
761 This event is the requests from Window Manager to
762
763 - request your app to callback `endDraw` to Window Manager.
764 - request your app to resize and redraw according to "drawing_area".
765
766 This is the abstract word then the real size is given in "drawing_rect".
767
768 example :
769
770 ```json
771 {
772   "event":"windowmanager\/syncDraw",
773   "data":{
774     "drawing_name":"radio",
775     "drawing_area":"normal.full",
776     "drawing_rect":{
777       "x":0,
778       "y":218,
779       "width":1080,
780       "height":1488
781     }
782   },
783   "jtype":"afb-event"
784 }
785 ```
786
787 An application which gets this event must send `endDraw`.
788 For details, please see the sequence.
789
790 #### flushDraw
791
792 This event is issued after Window Manager receives all `endDraw` from applications who recieved `syncDraw` . After this event, Window Manager expects applications to update its surface.
793
794 example :
795
796 ```json
797 {
798   "event":"windowmanager\/flushDraw",
799   "data":{
800     "drawing_name":"launcher"
801     }
802   },
803   "jtype":"afb-event"
804 }
805 ```
806
807 #### screenUpdated
808
809 This event is issued after the visible application changes as a state transition change. This contains resized applications and visible applications. This event is issued to all subscriber. Typical usecase is only for HomeScreen. If HomeScreen has an animation until the started application is visible such as progress bar, this signal may become a switch to stop the animation.
810
811 ```json
812 {
813   "event":"windowmanager\/screenUpdated",
814   "data":{
815     "ids":[
816       "mediaplayer",
817       "navi"
818     ]
819   },
820   "jtype":"afb-event"
821 }
822 ```
823
824 "ids" is the application_id described in config.xml of application.
825
826 ### Client library
827
828 A client library implementation that internally uses the *libafbwsc*, is
829 provided in the `libwindowmanager`.
830 This library is for C++ native application.
831
832 Regarding more detail, please refer to <https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Flibwindowmanager.git;a=summary>
833
834 * * *
835
836 ## Sample code
837
838 In order to enable application to activate application(render on layer),
839 above described steps need to be implemented.
840
841 As a minimal example the usage and initialization can look like the
842 following.
843
844 Typical implementation of C++ application.
845
846 - Repo: `git clone https://gerrit.automotivelinux.org/gerrit/src/libhomescreen`
847   - Path: `sample/simple-egl/main.c`
848
849 Typical implementation of Qt application.
850
851 - Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/radio`
852 - Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/videoplayer`
853
854 This is the good example to write more simply for Qt application using QtAGLExtras.
855
856 ## Policy Manager
857
858 ### Concepts
859
860 Policy Manager decides next layout by using input event data and current state
861 based on the policy table.
862
863 And PolicyManager is plugin for WindowManager.
864 Therefore the OEMs can replace it.
865
866 ### Enabling split
867
868 Window Manager supports split layout to change policy and `areas.json`.
869 This section describes how to play split layout. The sample image is here.
870
871 ![example_split.png](parts/example_split.png)
872
873 To play the split layout,
874
875 1. Edit in `policy_manager/CMakeLists.txt` as follows:
876
877 ```cmake:policy_manager/CMakeList.txt
878   #set(STM_DIR stub)
879   set(STM_DIR zipc)
880 ```
881
882 This results in using source code generated by ZIPC.
883
884 1. Set bool value "ON" to TRY_SPLIT_LAYOUT at line 28 in policy_manager/CMakeLists.txt as follows:
885   set(TRY_SPLIT_LAYOUT ON CACHE BOOL "Enable to show split layout")
886 1. compile
887 1. copy window manager to your board
888 1. re-install windowmanager and reboot
889
890 As a result, if application requests `navi` with `activateWindow` when current layout is `video` or `mediaplayer`, Window Manager change layout to split window. The reverse is true.
891
892 Note:
893
894 Currently, the policy manager force application change the size even if the application which has the role doesn't have the split design. In that case, the view of application may be ugly. Window Manager supposes that applications may have multi designs according to system design by OEM. For example, if OEM sets 2 pattern layout for `navi`, the application which requests `navi` should have 2 pattern designs.
895
896 * * *
897
898 ## Release Note
899
900 ### version: 0.8
901
902 #### New Feature
903
904 - Add Policy Manager
905
906 ### version: 0.7
907
908 #### New Features
909
910 - Add API of getting area list and changing area size on runtime
911
912 #### Changes
913
914 - Reduce binary size to use ilmControl library.
915 - Change layer management. Client has one ivi-layer and can have multi surfaces.
916 - Stop conversion table which is compatible with old role to avoid complexity.
917 - Upgrade bindings v3.
918 - Add configuration file over-ride mechanism.
919
920 #### Limitation
921
922 - Only single-surface Qt applications are support through the
923   libwindowmanager library. This is a limitation of how Qt creates surface
924   IDs for the ivi-application interface.
925
926 - Currenly, Window Manager supports only one screen. Dual display is not supported.
927 - As implemented in sample code, Qt application has to wait requesting `activateWindow` until `frameSwapped` is emitted.
928 - Qt application conceals, wayland and openGL processes, so it is difficult to call `swapBuffer` after `flushDraw` event described in the architecture document. But no problem if you use toolkit such as Qt, because it is automatically processed between applications and compositor(weston).
929 - Editing ZIPC is difficult for open source developer due to licence.