docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.2_WindowManager-Guide.md

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