doc/ApplicationGuide.md

   1 **Window Manager Application Guide**
   2 ====
   3 <div align="right">Revision: 0.2Final</div>
   4 <div align="right">TOYOTA MOTOR CORPORATION</div>
   5 <div align="right">23rd/Oct/2017</div>
   6
   7 * * *
   8 <div id="Table\ of\ content"></div>
   9
  10 Table of content
  11 ============
  12 - [Introduction](#Introduction)
  13         - [Intended audience](#Intended\ audience)
  14         - [Scope of this Document](#Scope\ of\ this\ Document)
  15         - [Known Issues](#Known\ Issues)
  16         - [External libraries](#External\ libraries)
  17         - [Client Library](#Client\ Library)
  18 - [Concepts](#Concepts)
  19         - [Layers](#Layers)
  20         - [Surfaces](#Surfaces)
  21 - [Configuration](#Configuration)
  22         - [Configuration Items](#Configuration\ Items)
  23 - [Building and Running](#Building\ and\ Running)
  24         - [Dependencies](#Dependencies)
  25         - [Build Configuration](#Build\ Configuration)
  26 - [Implementation Notes](#Implementation\ Notes)
  27         - [Binding code generation](#Binding\ code\ generation)
  28         - [Structure](#Structure)
  29 - [Sequence](#Sequence)
  30 - [Binding API](#Binding\ API)
  31         - [LibWindowmanager](#LibWindowmanager)
  32         - [Methods](#Methods)
  33         - [Errors](#Errors)
  34         - [Usage](#Usage)
  35         - [Events](#Events)
  36 - [Sample](#Sample)
  37
  38
  39 <div id="Introduction"></div>
  40
  41 Introduction
  42 ============
  43
  44 This WindowManager implements simple layout switching of applications on
  45 multiple layers and with different layer layouts.
  46
  47 <div id="Intended\ audience"></div>
  48
  49 Intended audience
  50 -----------------
  51
  52 This documentation is intended for developers and system integrators who
  53 need to know, how the window manager works and how it is to be used.
  54
  55 <div id="Scope\ of\ this\ Document"></div>
  56
  57 Scope of this Document
  58 ----------------------
  59
  60 This document covers the window manager that was implemented for TMC and
  61 delivered to the Automotive Grade Linux (AGL) project. It includes its
  62 implementation details, concepts of operation, configuration and usage.
  63
  64 It does not include
  65
  66 -   documentation of the underlying architecture, see
  67     [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
  68
  69 -   documentation of the AGL application framework and its technologies,
  70     see [AGL Application
  71     Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
  72
  73 It is highly recommended to have a good understanding of these documents
  74 and projects before using the window manager.
  75
  76 <div id="Known\ Issues"></div>
  77
  78 Known Issues
  79 ------------
  80
  81 Currently there is a one known issues:
  82
  83 -   Only single-surface Qt applications are support through the
  84     libwindowmanager library. This is a limitation of how Qt creates surface
  85     IDs for the ivi-application interface.
  86
  87 <div id="External\ libraries"></div>
  88
  89 External libraries
  90 ------------------
  91
  92 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
  93 library by Niels Lohmann](https://github.com/nlohmann/json).
  94
  95 <div id="Client\ Library"></div>
  96
  97 Client Library
  98 --------------
  99
 100 A client library implementation that internally uses the *libafbwsc*, is
 101 provided in the `libwindowmanager`.
 102
 103 <div id="Concepts"></div>
 104
 105 Concepts
 106 ========
 107
 108 The window manager implements a couple of concepts in order to allow
 109 efficient implementation.
 110
 111 <div id="Layers"></div>
 112
 113 Layers
 114 ------
 115
 116 Layers are entities that are stacked on top of each other. Each layer
 117 has an ID which is used for the ivi-controller interface, but this ID
 118 also implicitly specifies its stacking order, from lowest to highest.
 119
 120 Layers are always full-screen. We do not use layer dimensions as a way
 121 to setup the scene, rather - each layer has a layout attached to it,
 122 which specifies an area that is used by surfaces to draw on.
 123
 124 Additionally, layers will generally leave surfaces on below layers
 125 activated, and only disable surfaces on layers the are above the
 126 currently used layer.
 127
 128 It is possible to deactivate these surfaces on lower layers explicitly
 129 using the `DeactivateSurface` API call.
 130
 131 <div id="Surfaces"></div>
 132
 133 Surfaces
 134 --------
 135
 136 Surfaces are *placed* on layers according to their name. The surface
 137 will then be resized to dimensions, according to the layer's layout
 138 configuration.
 139
 140
 141 <div id="Configuration"></div>
 142
 143 Configuration
 144 =============
 145
 146 The window manager is configured with the *layers.json* configuration
 147 file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`.
 148 Note, that the WM will not run unless this configuration is found and valid.
 149
 150 A sample configuration is provided with the window manager
 151 implementation, this sample is installed to ${AFM_APP_INSTALL_DIR}/etc/layers.json.
 152
 153 <div id="Configuration\ Items"></div>
 154
 155 Configuration Items
 156 -------------------
 157
 158 This section describes configuration items available through
 159 `layers.json`. It will do this, by first providing an example, and then
 160 going into its components.
 161
 162 ### main\_surface
 163
 164     "main_surface": {
 165        "surface_role": "HomeScreen",
 166     },
 167
 168 The `main_surface` object describes a surface that will internally be
 169 treated as the main surface - usually this mean *HomeScreen*. The only
 170 special handling this surface receives, is that it is not allowed to
 171 deactivate it. Placement of this surface on an layer is done by the
 172 other configuration described below.
 173
 174 -   `surface_role` this configuration item specifies the name of the
 175     main surface. Set this to e.g. `HomeScreen`.
 176
 177 ### mappings
 178
 179 This configuration item is a list of surface-name to layer mappings.
 180
 181 #### surface to layer mapping
 182
 183     "mappings": [
 184       {
 185          "role": "^HomeScreen$",
 186          "name": "HomeScreen",
 187          "layer_id": 1000,
 188          "area": { "type": "full" },
 189          "comment": "Single layer map for the HomeScreen"
 190       },
 191       {
 192          "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
 193          "name": "apps",
 194          "layer_id": 1001,
 195          "area": { "type": "rect", "rect": { "x": 0, "y": 218, "width": -1, "height": -433 } },
 196          "comment": "Range of IDs that will always be placed on layer 1001, negative rect values are interpreted as output_size.dimension - $value",
 197
 198          "split_layouts": [
 199             {
 200                "name": "Navigation",
 201                "main_match": "Navigation",
 202                "sub_match": "HVAC|MediaPlayer",
 203                "priority": 1000
 204             }
 205          ]
 206       },
 207       {
 208          "role": "^OnScreen.*",
 209          "name": "popups",
 210          "layer_id": 9999,
 211          "area": { "type": "rect", "rect": { "x": 0, "y": 760, "width": -1, "height": 400 } },
 212          "comment": "Range of IDs that will always be placed on the popup layer, that gets a very high 'dummy' id of 9999"
 213       }
 214     ]
 215
 216 Each mapping defines the following items to map corresponding surfaces
 217 to a layer.
 218
 219 -   `role` defines a regular expression that application drawing names
 220     are matched against. If applications match this regular expression,
 221     the surface will be visible on this layer.
 222
 223 -   `name` is just a name definition for this layer, it has no
 224     functional use apart from identifying a layer with a name.
 225
 226 -   `layer_id` specifies which ID this layer will use.
 227
 228 -   `area` is an object that defines the area assigned to surfaces.
 229
 230 -   `split_layouts` is an optional item, that - if present - defines a
 231     number of possible split-screen layouts for this layer.
 232
 233 #### Area
 234
 235 Areas can be either `full` or `rect`, whereas `full` means a full-screen
 236 layer, this is mostly useful for the main\_surface or HomeScreen layer.
 237 `rect` declares a layer drawing area specified as a rectangle with start
 238 coordinates `x` and `y` as well as its dimensions `width` and `height`.
 239
 240 The dimensions can be specified relative to the screen dimensions. For
 241 this negative values for width and height mus be used.
 242
 243 For example, a full-screen surface can have the following `rect`
 244 definition:
 245
 246     "rect": { "x": 0,
 247               "y": 0,
 248               "width": -1,
 249               "height": -1 }
 250
 251 A surface that leaves a 200pixel margin on the top and bottom can use
 252 the following `rect` definition:
 253
 254     "rect": { "x": 0,
 255               "y": 200,
 256               "width": -1,
 257               "height": -401 }
 258
 259 So the expression for the actual surface dimensions when using
 260 screen-size-relative values will be:
 261
 262     actual_width = screen_width + 1 + width
 263     actual_height = screen_height + 1 + height
 264
 265 Or in other words, to leave an `N` wide border around a surface, the
 266 actual value in the dimension configuration needs to be `-N - 1`, and
 267 appropriate offsets need to be set for `x` and `y`.
 268
 269 #### split\_layouts
 270
 271 This configuration item allows the specification of split-screen layouts
 272 on layers for certain surfaces.
 273
 274 A split screen layout always has a *main* surface and a *sub* surface.
 275 In order to enter a split screen layout, first the *main* surface of the
 276 layout must be activated, and then the *sub* surface. In order to
 277 disable the split layout, one of the two participating surface must be
 278 deactivated (or a surface on a layer below the current one must be
 279 activated).
 280
 281     "split_layouts": [
 282        {
 283            "name": "Navigation",
 284            "main_match": "Navigation",
 285            "sub_match": "HVAC|MediaPlayer",
 286        }
 287     ]
 288
 289 A split layout object has the following attributes:
 290
 291 -   `name` defines its name, it has no actual function other then a way
 292     to identify this split layout.
 293
 294 -   `main_match` is a regular expression that matches for the *main*
 295     surface of this split layout.
 296
 297 -   `sub_match` is a regular expression that matches for the *sub*
 298     surface of this layout.
 299
 300 In the above example only the surface with drawing name
 301 `Navigation` will be used as the *main* surface, and the surfaces
 302 with drawing name `HVAC` or `MediaPlayer` can be used as a *sub* surface for
 303 this layout.
 304
 305 The names must still match the layer's role match!
 306
 307 <div id="Building\ and\ Running"></div>
 308
 309 Building and Running
 310 ====================
 311
 312 <div id="Dependencies"></div>
 313
 314 Dependencies
 315 ------------
 316
 317 This project is intended to be build with the 4.0 release of AGL.
 318
 319 Build dependencies are as follows:
 320
 321 -   afb-daemon &gt;= 1.0
 322
 323 -   libsystemd &gt;= 222
 324
 325 -   wayland-client &gt;= 1.11
 326
 327 -   cmake &gt;= 3.6.1
 328
 329 <div id="Supported environment"></div>
 330
 331 Supported environment
 332 -------------------
 333
 334 | Item        | Description                       |
 335 |:------------|:----------------------------------|
 336 | AGL version | Electric Eel                      |
 337 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
 338
 339
 340 <div id="Build\ Configuration"></div>
 341
 342 Build Configuration
 343 -------------------
 344
 345 **Download recipe**
 346 If repo is already done, please start with git clone
 347
 348 ```
 349 $ mkdir WORK
 350 $ cd WORK
 351 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
 352 $ repo sync
 353
 354 ```
 355
 356 Then you can get the following recipe.
 357
 358 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/agl-service-windowmanager-2017`
 359
 360 * `meta-agl-devel/meta-hmi-framework/recipes-graphics/libwindowmanager`
 361
 362 **Bitbake**
 363
 364 ```
 365 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
 366 $ bitbake agl-demo-platform
 367 ```
 368
 369 <div id="Implementation\ Notes"></div>
 370
 371 Implementation Notes
 372 ====================
 373
 374 The window manager is implemented as a app-framework-binder binding.
 375 That means, the build produces one shared object that exports a binding
 376 interface.
 377
 378 <div id="Binding\ code\ generation"></div>
 379
 380 Binding code generation
 381 -----------------------
 382
 383 The binding API is rather simple; functions receive a json object
 384 describing arguments and return a json object describing the result or
 385 an error. In order to simplify development, the
 386 `generate-binding-glue.py` script was added, that contains a description
 387 of the API as a python dictionary. This script generates the header
 388 `afb_binding_api.hpp` and the afb binding functions as
 389 `afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
 390
 391 Each function for the AFB binding that is generated does the following:
 392
 393 -   Lock the binding mutex, so that we serialize all access to
 394     the binding.
 395
 396 -   Do some debug logging (if wanted).
 397
 398 -   Check the binding state, i.e. the compositor might have exited
 399     unexpectedly at which point it would not make sense to continue.
 400
 401 -   Extract the arguments from the json object that is provided (doing
 402     some primitive type checking).
 403
 404 -   Call the afb\_binding\_api method corresponding to this binding
 405     function
 406
 407 -   Check the afb\_binding\_api’s function return value, log an error
 408     state and return the result to the afb request.
 409
 410 The generated functions do also check for any "loose" exception that
 411 comes out of the afb\_binding\_api call (which in turn might call the
 412 actual non-trivial implementation in `App`). However, **IF** an
 413 exception is thrown and not handled inside the afb\_binding\_call, that
 414 internal state of the window manager might be broken at this time (hence
 415 the talkative error log).
 416
 417 <div id="Structure"></div>
 418
 419 Structure
 420 ---------
 421
 422 The implementation is loosely split across the following source files:
 423
 424 -   `main.cpp`: The program entry point as used by the afb-daemon. This
 425     file defines the afbBindingV2 symbol tat is used by the afb-daemon
 426     in order to load a binding. It also defines the wayland fd event
 427     dispatcher and some globals to be used (as context for the afb calls
 428     we receive).
 429
 430 -   `afb_binding_api.cpp`: The implementation of the afb
 431     binding functions. The actual functions are generated by
 432     `generate-binding-glue.py` which generates a **.inl** file that is
 433     included by `main.cpp`.
 434
 435 -   `app.cpp` / `app.hpp`: This is the main application
 436     logic implementation.
 437
 438 -   `config.cpp` / `config.hpp`: Very simple configuration
 439     item interface.
 440
 441 -   `controller_hooks.hpp`: hook functions called by the wayland
 442     controller to call into the App instance. Only a very limited number
 443     of events are passed to the Application, which allowed the usage of
 444     such a simple interface.
 445
 446 -   `json_helper.cpp` / `json_helper.hpp`: Smaller json related
 447     helper functions.
 448
 449 -   `layers.cpp` / `layers.hpp`: Actually hold all the data from
 450     layers.json configuration, do some transformations and service the
 451     App implementation.
 452
 453 -   `layout.cpp` / `layout.hpp`: Very simple layout state for the
 454     implementation of split layouts and tracking of the
 455     surfaces involved.
 456
 457 -   `policy.hpp`: PolicyManager implementation stub. Gets passed the
 458     current and new layout on layout switch and can decide upon it being
 459     valid or not.
 460
 461 -   `result.hpp`: Simple result class around
 462     `std::experimental::optional` that additionally can hold a
 463     `char const *` to describe the error.
 464
 465 -   `util.cpp` / `util.hpp`: general utility functions and structs - and
 466     preprocessor definitions (e.g. `log*()` to AFB logging functions.
 467
 468 -   `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
 469     libwayland-client wrapper. It is instanced in `main.cpp` and handles
 470     all our wayland needs.
 471
 472 <div id="Sequence"></div>
 473
 474 Sequence
 475 ===============
 476
 477 To understand the sequence between application and window manager, refer to the [spec documentation](https://wiki.automotivelinux.org/windowmanager).
 478
 479
 480 <div id="Binding\ API"></div>
 481
 482 Binding API
 483 ===============
 484
 485 Each function returns a reply containing at least a failed or successful
 486 result of the call, additionally, when calls return something, it is
 487 noted.
 488
 489 <div id="LibWindowmanager"></div>
 490
 491 LibWindowmanager
 492 ------
 493
 494 This is the public interface of the class `LibWindowmanager`.
 495
 496     class LibWindowmanager
 497     {
 498     public:
 499         LibWindowmanager();
 500         ~LibWindowmanager();
 501
 502         enum EventType {
 503            Event_Active = 0,
 504            Event_Inactive,
 505
 506            Event_Visible,
 507            Event_Invisible,
 508
 509            Event_SyncDraw,
 510            Event_FlushDraw,
 511         };
 512
 513         int init(int port, char const *token);
 514
 515         // WM API
 516         int requestSurface(json_object *object);
 517         int activateSurface(json_object *object);
 518         int deactivateSurface(json_object *object);
 519         int endDraw(json_object *object);
 520         int getDisplayInfo(json_object *object);
 521         int getAreaInfo(json_object *in_obj, json_object *out_obj);
 522
 523         int getAreaInfo(const char *label, json_object *out_obj);
 524
 525         void set_event_handler(enum EventType et, handler_fun f);
 526
 527     };
 528
 529 <div id="Methods"></div>
 530
 531 Methods
 532 -------
 533
 534 ### init(int port, char const *token)
 535
 536 Initialize the Binding communication.
 537
 538 The `token` parameter is a string consisting of only alphanumeric characters.
 539 If these conditions are not met, the LibWindowmanager instance will not initialize,
 540 i.e. this call will return `-EINVAL`.
 541
 542 The `port` parameter is the port the afb daemon is listening on, an
 543 invalid port will lead to a failure of the call and return `-EINVAL`.
 544
 545 ### requestSurface(json_object *object)
 546
 547 **args: `{ 'kKeyDrawingName': 'application name' }`**
 548 This method requests a surface with the label given from the *Window Manager*.
 549 It will return `surface id` a client application can use, and
 550 `-errno` on failure. Additionally, on the standard error, messages are
 551 logged to help debgging the issue.
 552
 553 ### activateSurface(json_object *object)
 554
 555 **args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout'  }`**
 556 This method is mainly intended for *manager* applications that control
 557 other applications (think an application manager or the *HomeScreen*).
 558 It instructs the window manager to activate the surface with the given
 559 *label*.
 560
 561 This method only is effective after the actual window or surface was
 562 created by the application.
 563
 564 ### deactivateSurface(json_object *object)
 565
 566 **args: `{ 'kKeyDrawingName': 'application name' }`**
 567 This method is mainly intended for *manager* applications that control
 568 other applications. It instructs the window manager to deactivate the
 569 surface associated with the given label. Note, that deactivating a
 570 surface also means to implicitly activate another (the last active or if
 571 not available *main surface* or *HomeScreen*.)
 572
 573 This method only is effective after the actual window or surface was
 574 created by the application.
 575
 576 ### endDraw(json_object *object)
 577
 578 **args: `{ 'kKeyDrawingName': 'application name' }`**
 579 This function is called from a client application when it is done
 580 drawing its surface content.
 581
 582 It is not crucial to make this call at every time a drawing is finished
 583 - it is mainly intended to allow the window manager to synchronize
 584 drawing in case of layout switch. The exact semantics are explained in
 585 the next [Events](#_events) Section.
 586
 587 ### getDisplayInfo(json_object *object)
 588
 589 **args: `{ }`**
 590 This function gets the display information as follows:
 591  - width[pixel]
 592  - height[pixel]
 593  - width[mm]
 594  - height[mm]
 595
 596 It outputs the display information for json_object in the argument as follows:
 597   `{"width_pixel": int value of width[pixel], "height_pixel": int value of height[pixel],
 598     "width_mm": int value of width[mm], "height_mm": int value of height[mm]}`
 599
 600 It should be called after calling init().
 601 It should not be called in the event handler because it occurs hang-up.
 602
 603 #### NOTE
 604 It uses wl_output::geometry() for getting physical width[mm] and height[mm] of the display,
 605 but the value is different with measured value.
 606
 607  - value from wl_output::geometry(): width:320 height:520
 608  - measured value                  : width:193 height:343
 609
 610 ### getAreaInfo(json_object *in_obj, json_object *out_obj)
 611
 612 **args1: `{ 'kKeyDrawingName': 'application name' }`**
 613 **args2: `{ }`**
 614 This function gets the information of area drawn by the application as follows:
 615  - x-coordinate
 616  - y-coordinate
 617  - width
 618  - height
 619
 620 It outputs the area information for json_object in the 2nd argument as follows:
 621   `{"x": int value of x-coordinate, "y": int value of y-coordinate,
 622     "width": int value of width, "height": int value of height}`
 623
 624 It should be called after calling activateSurface().
 625 It should not be called in the event handler because it occurs hang-up.
 626
 627 #### NOTE
 628 The same information can given by SyncDraw event.
 629
 630 ### getAreaInfo(const char *label, json_object *out_obj)
 631
 632 **args1: String of application name**
 633 **args2: `{ }`**
 634 This function is same with `getAreaInfo(json_object *in_obj, json_object *out_obj)`,
 635 but only has difference of 1st argument.
 636
 637 ### set\_event\_handler(enum EventType et, handler_fun f)
 638
 639 This method needs to be used to register event handlers for the WM
 640 events described in the EventType enum. Only one hendler for each
 641 EventType is possible, i.e. if it is called multiple times with the same
 642 EventType the previous handler will be replaced.
 643
 644 The `func` handler functions will receive the label of the surface this
 645 event is targeted at.
 646
 647 See Section [Events](#_events) for mor detailed information about event
 648 delivery to client applications.
 649
 650 <div id="Errors"></div>
 651
 652 Errors
 653 ------
 654
 655 Methods returning an `int` signal successful operation when returning
 656 `0`. In case of an error, an error value is returned as a negative errno
 657 value. E.g. `-EINVAL` to signal that some input value was invalid.
 658
 659 Additionally, logging of error messages is done on the standard error
 660 file descriptor to help debugging the issue.
 661
 662 <div id="Usage"></div>
 663
 664 Usage
 665 -----
 666
 667 ### Initialization of LibWindowmanager
 668
 669 Before usage of the LibWindowmanager, the method `init()` must be
 670 called once, it will return `-errno` in case of en error and log
 671 diagnostic messages to stderr.
 672
 673 ### Request a surface
 674
 675 When creating a surface with *Qt* - it is necessary to request a surface
 676 from the WM, internally this will communicate with the window manager
 677 binding. Only after `requestSurface()` was successful, a surface should
 678 be created.
 679
 680 This is also true for *QML* applications, where only after the
 681 `requestSurface()` should the load of the resource be done. The method
 682 returns `surface id` a client application can use
 683 after the surface was requested successfully.
 684
 685 #### Workings of requestSurface()
 686
 687 `LibWindowmanager::requestSurface()` calls the AFB binding verb
 688 `requestsurface` of the `windowmanager` API. This API call will return a
 689 numeric ID to be used when creating the surface. This ID is never
 690 explicitly returned to the client application, instead, it is set in the
 691 application environment in order for *Qt* to then use it when creating
 692 the surface.
 693
 694 With the current *Qt* implementation this means, that only one surface
 695 will be available to client applications, as subsequent windows will
 696 increment this numeric ID internally - which then will lead to IDs that
 697 cannot be known by the window manager as there is no direct
 698 communication from *Qt* to the WM.
 699
 700 <div id="Events"></div>
 701
 702 Events
 703 ------
 704
 705 Events are a way for the *Window Manager* to propagate information to
 706 client applications. It was vital for the project to implement a number
 707 of events, that mirror functionality that is already present in the
 708 wayland protocol.
 709
 710 All events have the surface label as argument - a way to enable future
 711 multi-surface applications.
 712
 713 As already stated above, this is currently not possible with the way
 714 *Qt* implements its surface ID setting.
 715
 716 ### Active and Inactive Events
 717
 718 These events signal an application that it was activated or deactivated
 719 respectively. Usually this means it was switched visible - which means
 720 the surface will now be on the screen and therefor continue to render.
 721
 722 -   `Active(json_object *object)`
 723     args: { 'kKeyDrawingName': 'application name' }
 724     Signal that the surface with the name
 725     `kKeyDrawingName` is now active.
 726
 727 -   `Inactive(json_object *object)`
 728     args: { 'kKeyDrawingName': 'application name' }
 729     Signal that the surface with the
 730     name `kKeyDrawingName` is now inactive. This usually means, the layout
 731     got changed, and the surface is now considered inactive
 732     (or sleeping).
 733
 734 ### Visible and Invisible
 735
 736 These events signal an application that it was switched to be visible or
 737 invisible respectively. These events also are handled implicitly through
 738 the wayland protocol by means of `wl_surface::enter` and
 739 `wl_surface::leave` events to the client.
 740
 741 -   `Visible(json_object *object)`
 742     args: { 'kKeyDrawingName': 'application name' }
 743     Signal applications, that the
 744     surface with name `kKeyDrawingName` is now visible.
 745
 746 -   `Invisible(json_object *object)`
 747     args: { 'kKeyDrawingName': 'application name' }
 748     Signal applications that the
 749     surface with name `kKeyDrawingName` is now invisible.
 750
 751 ### SyncDraw and FlushDraw
 752
 753 These events instruct applications that they should redraw their surface
 754 contents - again, this is handled implicitly by the wayland protocol.
 755
 756 `SyncDraw` is sent to the application when it has to redraw its surface.
 757
 758 `FlushDraw` is sent to the application when it should swap its buffers,
 759 that is *signal* the compositor that its surface contains new content.
 760
 761 -   `SyncDraw(json_object *object)`
 762     args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout',
 763             'kKeyDrawingRect': { "x": int value of x-coordinate, "y": int value of y-coordinate,
 764                                  "width": int value of width, "height": int value of height } }
 765     Signal applications, that the
 766     surface with name `kKeyDrawingArea` needs to redraw its content
 767     in the layout with name `kKeyDrawingArea` - this
 768     usually is sent when the surface geometry changed.
 769     And the area position and size are included with name `kKeyDrawingRect`.
 770
 771 -   `FlushDraw(json_object *object)`
 772     args: { 'kKeyDrawingName': 'application name' }
 773     Signal applications, that the
 774     surface with name `kKeyDrawingArea` can now be swapped to its newly
 775     drawn content as the window manager is ready to activate a new
 776     layout (i.e. a new surface geometry).
 777
 778 <div id="Sample"></div>
 779
 780 Sample
 781 ============
 782
 783 In order to enable application to use the `WM` surface registration
 784 function the above described steps need to be implemented.
 785
 786 As a minimal example the usage and initialization can look like the
 787 following.
 788
 789 Repo: `apps/agl-service-homescreen-2017`
 790 Path: `sample/template/main.c`
 791