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.