Add gitreview file for flounder branch
[apps/agl-service-windowmanager-2017.git] / doc / ApplicationGuide.md
index b74dfdd..2240bb1 100644 (file)
@@ -1,11 +1,14 @@
 **Window Manager Application Guide**
 ====
 **Window Manager Application Guide**
 ====
-<div align="right">Revision: 0.2Final</div>
+<div align="right">Revision: 0.5</div>
 <div align="right">TOYOTA MOTOR CORPORATION</div>
 <div align="right">TOYOTA MOTOR CORPORATION</div>
-<div align="right">23rd/Oct/2017</div>
+<div align="right">20th/Mar/2018</div>
 
 * * *
 
 * * *
-## **<div id="Table\ of\ content">Table of content</div>**
+<div id="Table\ of\ content"></div>
+
+Table of content
+============
 - [Introduction](#Introduction)
        - [Intended audience](#Intended\ audience)
        - [Scope of this Document](#Scope\ of\ this\ Document)
 - [Introduction](#Introduction)
        - [Intended audience](#Intended\ audience)
        - [Scope of this Document](#Scope\ of\ this\ Document)
@@ -21,7 +24,6 @@
        - [Dependencies](#Dependencies)
        - [Build Configuration](#Build\ Configuration)
 - [Implementation Notes](#Implementation\ Notes)
        - [Dependencies](#Dependencies)
        - [Build Configuration](#Build\ Configuration)
 - [Implementation Notes](#Implementation\ Notes)
-       - [Binding code generation](#Binding\ code\ generation)
        - [Structure](#Structure)
 - [Sequence](#Sequence)
 - [Binding API](#Binding\ API)
        - [Structure](#Structure)
 - [Sequence](#Sequence)
 - [Binding API](#Binding\ API)
 - [Sample](#Sample)
 
 
 - [Sample](#Sample)
 
 
-<div id="Introduction">Introduction</div>
+<div id="Introduction"></div>
+
+Introduction
 ============
 
 ============
 
-This WindowManager implements simple layout switching of applications on
+This window manager implements simple layout switching of applications on
 multiple layers and with different layer layouts.
 
 multiple layers and with different layer layouts.
 
-<div id="Intended\ audience">Intended audience</div>
+<div id="Intended\ audience"></div>
+
+Intended audience
 -----------------
 
 -----------------
 
-This documentation is intended for developers and system integrators who
+This document is intended for developers and system integrators who
 need to know, how the window manager works and how it is to be used.
 
 need to know, how the window manager works and how it is to be used.
 
-<div id="Scope\ of\ this\ Document">Scope of this Document</div>
+<div id="Scope\ of\ this\ Document"></div>
+
+Scope of this Document
 ----------------------
 
 This document covers the window manager that was implemented for TMC and
 ----------------------
 
 This document covers the window manager that was implemented for TMC and
@@ -54,17 +62,19 @@ implementation details, concepts of operation, configuration and usage.
 
 It does not include
 
 
 It does not include
 
--   documentation of the underlying architecture, see
+-   document of the underlying architecture, see
     [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
 
     [HMI-Framework](https://wiki.automotivelinux.org/hmiframework).
 
--   documentation of the AGL application framework and its technologies,
+-   document of the AGL application framework and its technologies,
     see [AGL Application
     Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
 
 It is highly recommended to have a good understanding of these documents
 and projects before using the window manager.
 
     see [AGL Application
     Framework](https://wiki.automotivelinux.org/agl-distro/app-framework).
 
 It is highly recommended to have a good understanding of these documents
 and projects before using the window manager.
 
-<div id="Known\ Issues">Known Issues</div>
+<div id="Known\ Issues"></div>
+
+Known Issues
 ------------
 
 Currently there is a one known issues:
 ------------
 
 Currently there is a one known issues:
@@ -73,28 +83,33 @@ Currently there is a one known issues:
     libwindowmanager library. This is a limitation of how Qt creates surface
     IDs for the ivi-application interface.
 
     libwindowmanager library. This is a limitation of how Qt creates surface
     IDs for the ivi-application interface.
 
-<div id="External\ libraries">External libraries</div>
+<div id="External\ libraries"></div>
+
+External libraries
 ------------------
 
 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
 library by Niels Lohmann](https://github.com/nlohmann/json).
 
 ------------------
 
 This project includes a copy of version 2.1.1 the excellent [C++11 JSON
 library by Niels Lohmann](https://github.com/nlohmann/json).
 
-<div id="Client\ Library">Client Library</div>
+<div id="Client\ Library"></div>
+
+Client Library
 --------------
 
 A client library implementation that internally uses the *libafbwsc*, is
 --------------
 
 A client library implementation that internally uses the *libafbwsc*, is
-provided in the subdirectory `libwindowmanager/` with its own documentation
-directory.
+provided in the `libwindowmanager`.
 
 
-The client library is built together with the window manager itself.
+<div id="Concepts"></div>
 
 
-<div id="Concepts">Concepts</div>
+Concepts
 ========
 
 The window manager implements a couple of concepts in order to allow
 efficient implementation.
 
 ========
 
 The window manager implements a couple of concepts in order to allow
 efficient implementation.
 
-<div id="Layers">Layers</div>
+<div id="Layers"></div>
+
+Layers
 ------
 
 Layers are entities that are stacked on top of each other. Each layer
 ------
 
 Layers are entities that are stacked on top of each other. Each layer
@@ -112,7 +127,9 @@ currently used layer.
 It is possible to deactivate these surfaces on lower layers explicitly
 using the `DeactivateSurface` API call.
 
 It is possible to deactivate these surfaces on lower layers explicitly
 using the `DeactivateSurface` API call.
 
-<div id="Surfaces">Surfaces</div>
+<div id="Surfaces"></div>
+
+Surfaces
 --------
 
 Surfaces are *placed* on layers according to their name. The surface
 --------
 
 Surfaces are *placed* on layers according to their name. The surface
@@ -120,19 +137,24 @@ will then be resized to dimensions, according to the layer's layout
 configuration.
 
 
 configuration.
 
 
-<div id="Configuration">Configuration</div>
+<div id="Configuration"></div>
+
+Configuration
 =============
 
 The window manager is configured with the *layers.json* configuration
 =============
 
 The window manager is configured with the *layers.json* configuration
-file, by default it is searched in `/etc/layers.json` but through the
-use of the environment variable `LAYERS_JSON` the WM can be instructed
-to use different file. Note, that the WM will not run unless this
-configuration is found and valid.
+file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`.
+Note, that the window manager will use default configuration unless this configuration is found.
 
 A sample configuration is provided with the window manager
 
 A sample configuration is provided with the window manager
-implementation, this sample is installed to /etc/layers.json.
+implementation, this sample is installed to ${AFM_APP_INSTALL_DIR}/etc/layers.json.
+
+Note:
+Currently, window manager doesn't block the application displaying because "Fallback" is set by default. If the "Fallback" is not set in layers.json, window manager blocks the application displaying. In such a situation, you have to add your role(application name) at "role" in layers.json.
+
+<div id="Configuration\ Items"></div>
 
 
-<div id="Configuration\ Items">Configuration Items</div>
+Configuration Items
 -------------------
 
 This section describes configuration items available through
 -------------------
 
 This section describes configuration items available through
@@ -166,7 +188,7 @@ This configuration item is a list of surface-name to layer mappings.
          "name": "HomeScreen",
          "layer_id": 1000,
          "area": { "type": "full" },
          "name": "HomeScreen",
          "layer_id": 1000,
          "area": { "type": "full" },
-         "comment": "Single layer map for the HomeScreen, XXX: type is redundant, could also check existence of id/first_id+last_id"
+         "comment": "Single layer map for the HomeScreen"
       },
       {
          "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
       },
       {
          "role": "MediaPlayer|Radio|Phone|Navigation|HVAC|Settings|Dashboard|POI|Mixer",
@@ -197,7 +219,7 @@ Each mapping defines the following items to map corresponding surfaces
 to a layer.
 
 -   `role` defines a regular expression that application drawing names
 to a layer.
 
 -   `role` defines a regular expression that application drawing names
-    are matched against. If applications match tis regular expression,
+    are matched against. If applications match this regular expression,
     the surface will be visible on this layer.
 
 -   `name` is just a name definition for this layer, it has no
     the surface will be visible on this layer.
 
 -   `name` is just a name definition for this layer, it has no
@@ -218,7 +240,7 @@ layer, this is mostly useful for the main\_surface or HomeScreen layer.
 coordinates `x` and `y` as well as its dimensions `width` and `height`.
 
 The dimensions can be specified relative to the screen dimensions. For
 coordinates `x` and `y` as well as its dimensions `width` and `height`.
 
 The dimensions can be specified relative to the screen dimensions. For
-this negative values for width and height mus be used.
+this negative values for width and height must be used.
 
 For example, a full-screen surface can have the following `rect`
 definition:
 
 For example, a full-screen surface can have the following `rect`
 definition:
@@ -278,19 +300,21 @@ A split layout object has the following attributes:
     surface of this layout.
 
 In the above example only the surface with drawing name
     surface of this layout.
 
 In the above example only the surface with drawing name
-`App MPlayer Main` will be used as the *main* surface, but all surfaces
-that begin with `App MPlayer Sub` can be used as a *sub* surface for
+`Navigation` will be used as the *main* surface, and the surfaces
+with drawing name `HVAC` or `MediaPlayer` can be used as a *sub* surface for
 this layout.
 
 this layout.
 
-The names must still match the layers role match!
+The names must still match the layer's role match!
 
 
-<div id="Building\ and\ Running">Building and Running</div>
+<div id="Building\ and\ Running"></div>
+
+Building and Running
 ====================
 
 ====================
 
-<div id="Dependencies">Dependencies</div>
-------------
+<div id="Dependencies"></div>
 
 
-This project is intended to be build with the 4.0 release of AGL.
+Dependencies
+------------
 
 Build dependencies are as follows:
 
 
 Build dependencies are as follows:
 
@@ -300,115 +324,81 @@ Build dependencies are as follows:
 
 -   wayland-client &gt;= 1.11
 
 
 -   wayland-client &gt;= 1.11
 
--   cmake &gt;= 3.6.1
+-   wayland-ivi-extension &gt;= 2.0.2 (until eel, wayland-ivi-extension &gt;= 1.13)
+
+-   cmake &gt;= 2.8
 
 
-<div id="Build\ Configuration">Build Configuration</div>
+<div id="Supported environment"></div>
+
+Supported environment
+-------------------
+
+| Item        | Description                       |
+|:------------|:----------------------------------|
+| AGL version | Electric Eel                      |
+| Hardware    | Renesas R-Car Starter Kit Pro(M3) |
+
+
+<div id="Build\ Configuration"></div>
+
+Build Configuration
 -------------------
 
 **Download recipe**
 If repo is already done, please start with git clone
 -------------------
 
 **Download recipe**
 If repo is already done, please start with git clone
+
 ```
 $ mkdir WORK
 $ cd WORK
 ```
 $ mkdir WORK
 $ cd WORK
-$ repo init -b dab -m dab_4.0.0_xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
+$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
 $ repo sync
 $ repo sync
-$ git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework
 
 ```
 
 Then you can get the following recipe.
 
 ```
 
 Then you can get the following recipe.
-* `meta-hmi-framework/windowmanager`
 
 
+* `meta-agl-devel/meta-hmi-framework/recipes-graphics/agl-service-windowmanager-2017`
+
+* `meta-agl-devel/meta-hmi-framework/recipes-graphics/libwindowmanager`
 
 **Bitbake**
 
 **Bitbake**
+
 ```
 ```
-$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
-$ bitbake agl-service-windowmanager-2017
+$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo
+$ bitbake agl-demo-platform
 ```
 
 ```
 
+<div id="Implementation\ Notes"></div>
 
 
-A couple of build options to configure the build are available:
-
--   `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
-    output from the window manager, use --verbose three times on an
-    afb-daemon instance to see the debug messages.
-
--   `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
-    used for a rather small portion of the window manager code. However,
-    it is used quite extensively in the libwindowmanager implementation.
-
-By default these options will be disabled.
-
-
-<div id="Implementation\ Notes">Implementation Notes</div>
+Implementation Notes
 ====================
 
 The window manager is implemented as a app-framework-binder binding.
 That means, the build produces one shared object that exports a binding
 interface.
 
 ====================
 
 The window manager is implemented as a app-framework-binder binding.
 That means, the build produces one shared object that exports a binding
 interface.
 
-<div id="Binding\ code\ generation">Binding code generation</div>
------------------------
-
-The binding API is rather simple; functions receive a json object
-describing arguments and return a json object describing the result or
-an error. In order to simplify development, the
-`generate-binding-glue.py` script was added, that contains a description
-of the API as a python dictionary. This script generates the header
-`afb_binding_api.hpp` and the afb binding functions as
-`afb_binding_glue.inl`. Where the latter is included in `main.cpp`.
-
-Each function for the AFB binding that is generated does the following:
-
--   Lock the binding mutex, so that we serialize all access to
-    the binding.
+<div id="Structure"></div>
 
 
--   Do some debug logging (if wanted).
-
--   Check the binding state, i.e. the compositor might have exited
-    unexpectedly at which point it would not make sense to continue.
-
--   Extract the arguments from the json object that is provided (doing
-    some primitive type checking).
-
--   Call the afb\_binding\_api method corresponding to this binding
-    function
-
--   Check the afb\_binding\_api’s function return value, log an error
-    state and return the result to the afb request.
-
-The generated functions do also check for any "loose" exception that
-comes out of the afb\_binding\_api call (which in turn might call the
-actual non-trivial implementation in `App`). However, **IF** an
-exception is thrown and not handled inside the afb\_binding\_call, that
-internal state of the window manager might be broken at this time (hence
-the talkative error log).
-
-<div id="Structure">Structure</div>
+Structure
 ---------
 
 The implementation is loosely split across the following source files:
 
 -   `main.cpp`: The program entry point as used by the afb-daemon. This
 ---------
 
 The implementation is loosely split across the following source files:
 
 -   `main.cpp`: The program entry point as used by the afb-daemon. This
-    file defines the afbBindingV2 symbol tat is used by the afb-daemon
+    file defines the afbBindingV2 symbol that is used by the afb-daemon
     in order to load a binding. It also defines the wayland fd event
     dispatcher and some globals to be used (as context for the afb calls
     we receive).
 
     in order to load a binding. It also defines the wayland fd event
     dispatcher and some globals to be used (as context for the afb calls
     we receive).
 
--   `afb_binding_api.cpp`: The implementation of the afb
-    binding functions. The actual functions are generated by
-    `generate-binding-glue.py` which generates a **.inl** file that is
-    included by `main.cpp`.
-
--   `app.cpp` / `app.hpp`: This is the main application
+-   `app.cpp` / `app.hpp`: This is the main window manager
     logic implementation.
 
 -   `config.cpp` / `config.hpp`: Very simple configuration
     item interface.
 
 -   `controller_hooks.hpp`: hook functions called by the wayland
     logic implementation.
 
 -   `config.cpp` / `config.hpp`: Very simple configuration
     item interface.
 
 -   `controller_hooks.hpp`: hook functions called by the wayland
-    controller to call into the App instance. Only a very limited number
-    of events are passed to the Application, which allowed the usage of
+    controller to call into the window manager instance. Only a very limited number
+    of events are passed to the window manager, which allowed the usage of
     such a simple interface.
 
 -   `json_helper.cpp` / `json_helper.hpp`: Smaller json related
     such a simple interface.
 
 -   `json_helper.cpp` / `json_helper.hpp`: Smaller json related
@@ -416,7 +406,7 @@ The implementation is loosely split across the following source files:
 
 -   `layers.cpp` / `layers.hpp`: Actually hold all the data from
     layers.json configuration, do some transformations and service the
 
 -   `layers.cpp` / `layers.hpp`: Actually hold all the data from
     layers.json configuration, do some transformations and service the
-    App implementation.
+    window manager implementation.
 
 -   `layout.cpp` / `layout.hpp`: Very simple layout state for the
     implementation of split layouts and tracking of the
 
 -   `layout.cpp` / `layout.hpp`: Very simple layout state for the
     implementation of split layouts and tracking of the
@@ -433,24 +423,31 @@ The implementation is loosely split across the following source files:
 -   `util.cpp` / `util.hpp`: general utility functions and structs - and
     preprocessor definitions (e.g. `log*()` to AFB logging functions.
 
 -   `util.cpp` / `util.hpp`: general utility functions and structs - and
     preprocessor definitions (e.g. `log*()` to AFB logging functions.
 
--   `wayland.cpp` / `wayland.hpp`: A C++ object-oriented
+-   `wayland_ivi_wm.cpp` / `wayland_ivi_wm.hpp`: A C++ object-oriented
     libwayland-client wrapper. It is instanced in `main.cpp` and handles
     libwayland-client wrapper. It is instanced in `main.cpp` and handles
-    all our wayland needs.
+    all our wayland needs. These files are in master. In eel, the name
+    of these files are `wayland.cpp` / `wayland.hpp`
 
 
-<div id="Sequence">Sequence</div>
+<div id="Sequence"></div>
+
+Sequence
 ===============
 
 ===============
 
-To understand the sequence between application and window manager, refer to the [spec documentation](https://wiki.automotivelinux.org/windowmanager).
+To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/windowmanager).
+
 
 
+<div id="Binding\ API"></div>
 
 
-<div id="Binding\ API">Binding API</div>
+Binding API
 ===============
 
 Each function returns a reply containing at least a failed or successful
 result of the call, additionally, when calls return something, it is
 noted.
 
 ===============
 
 Each function returns a reply containing at least a failed or successful
 result of the call, additionally, when calls return something, it is
 noted.
 
-<div id="LibWindowmanager">LibWindowmanager</div>
+<div id="LibWindowmanager"></div>
+
+LibWindowmanager
 ------
 
 This is the public interface of the class `LibWindowmanager`.
 ------
 
 This is the public interface of the class `LibWindowmanager`.
@@ -474,17 +471,24 @@ This is the public interface of the class `LibWindowmanager`.
 
         int init(int port, char const *token);
 
 
         int init(int port, char const *token);
 
-        // WM API
+        // Window manager API
         int requestSurface(json_object *object);
         int requestSurface(json_object *object);
+        int requestSurfaceXDG(json_object *object);
         int activateSurface(json_object *object);
         int deactivateSurface(json_object *object);
         int endDraw(json_object *object);
         int activateSurface(json_object *object);
         int deactivateSurface(json_object *object);
         int endDraw(json_object *object);
+        int getDisplayInfo(json_object *object);
+        int getAreaInfo(json_object *in_obj, json_object *out_obj);
+
+        int getAreaInfo(const char *label, json_object *out_obj);
 
         void set_event_handler(enum EventType et, handler_fun f);
 
     };
 
 
         void set_event_handler(enum EventType et, handler_fun f);
 
     };
 
-<div id="Methods">Methods</div>
+<div id="Methods"></div>
+
+Methods
 -------
 
 ### init(int port, char const *token)
 -------
 
 ### init(int port, char const *token)
@@ -501,10 +505,18 @@ invalid port will lead to a failure of the call and return `-EINVAL`.
 ### requestSurface(json_object *object)
 
 **args: `{ 'kKeyDrawingName': 'application name' }`**
 ### requestSurface(json_object *object)
 
 **args: `{ 'kKeyDrawingName': 'application name' }`**
-This method requests a surface with the label given from the *Window
-Manager*. It will return `0` for a successful surface request, and
+This method requests a surface with the label given from the *Window Manager*.
+It will return `surface id` a client application can use, and
+`-errno` on failure. Additionally, on the standard error, messages are
+logged to help debugging the issue.
+
+### requestSurfaceXDG(json_object *object)
+
+**args: `{ 'kKeyDrawingName': 'application name', 'kKeyIviId': 'ivi id' }`**
+This method is mainly intended for *xdglauncher* that controls xdg application such as chromium.
+It will return `surface id` xdglauncher uses, and
 `-errno` on failure. Additionally, on the standard error, messages are
 `-errno` on failure. Additionally, on the standard error, messages are
-logged to help debgging the issue.
+logged to help debugging the issue.
 
 ### activateSurface(json_object *object)
 
 
 ### activateSurface(json_object *object)
 
@@ -520,11 +532,9 @@ created by the application.
 ### deactivateSurface(json_object *object)
 
 **args: `{ 'kKeyDrawingName': 'application name' }`**
 ### deactivateSurface(json_object *object)
 
 **args: `{ 'kKeyDrawingName': 'application name' }`**
-This method is mainly intended for *manager* applications that control
-other applications. It instructs the window manager to deactivate the
-surface associated with the given label. Note, that deactivating a
-surface also means to implicitly activate another (the last active or if
-not available *main surface* or *HomeScreen*.)
+This method is mainly intended for *manager* applications that control other applications.
+In adition, this is for applications that overrides other applications such like popup message.
+In this case, popup surface requests to be hidden. It instructs the window manager to deactivate the surface associated with the given label. Note, that deactivating a surface also means to implicitly activate another (the last active or if not available *main surface* or *HomeScreen*.)
 
 This method only is effective after the actual window or surface was
 created by the application.
 
 This method only is effective after the actual window or surface was
 created by the application.
@@ -540,6 +550,56 @@ It is not crucial to make this call at every time a drawing is finished
 drawing in case of layout switch. The exact semantics are explained in
 the next [Events](#_events) Section.
 
 drawing in case of layout switch. The exact semantics are explained in
 the next [Events](#_events) Section.
 
+### getDisplayInfo(json_object *object)
+
+**args: `{ }`**
+This function gets the display information as follows:
+ - width[pixel]
+ - height[pixel]
+ - width[mm]
+ - height[mm]
+
+It outputs the display information for json_object in the argument as follows:
+  `{"width_pixel": int value of width[pixel], "height_pixel": int value of height[pixel],
+    "width_mm": int value of width[mm], "height_mm": int value of height[mm]}`
+
+It should be called after calling init().
+It should not be called in the event handler because it occurs hang-up.
+
+#### NOTE
+It uses wl_output::geometry() for getting physical width[mm] and height[mm] of the display,
+but the value is different with measured value.
+
+ - value from wl_output::geometry(): width:320 height:520
+ - measured value                  : width:193 height:343
+
+### getAreaInfo(json_object *in_obj, json_object *out_obj)
+
+**args1: `{ 'kKeyDrawingName': 'application name' }`**
+**args2: `{ }`**
+This function gets the information of area drawn by the application as follows:
+ - x-coordinate
+ - y-coordinate
+ - width
+ - height
+
+It outputs the area information for json_object in the 2nd argument as follows:
+  `{"x": int value of x-coordinate, "y": int value of y-coordinate,
+    "width": int value of width, "height": int value of height}`
+
+It should be called after calling activateSurface().
+It should not be called in the event handler because it occurs hang-up.
+
+#### NOTE
+The same information can given by SyncDraw event.
+
+### getAreaInfo(const char *label, json_object *out_obj)
+
+**args1: String of application name**
+**args2: `{ }`**
+This function is same with `getAreaInfo(json_object *in_obj, json_object *out_obj)`,
+but only has difference of 1st argument.
+
 ### set\_event\_handler(enum EventType et, handler_fun f)
 
 This method needs to be used to register event handlers for the WM
 ### set\_event\_handler(enum EventType et, handler_fun f)
 
 This method needs to be used to register event handlers for the WM
@@ -550,10 +610,12 @@ EventType the previous handler will be replaced.
 The `func` handler functions will receive the label of the surface this
 event is targeted at.
 
 The `func` handler functions will receive the label of the surface this
 event is targeted at.
 
-See Section [Events](#_events) for mor detailed information about event
+See Section [Events](#_events) for more detailed information about event
 delivery to client applications.
 
 delivery to client applications.
 
-<div id="Errors">Errors</div>
+<div id="Errors"></div>
+
+Errors
 ------
 
 Methods returning an `int` signal successful operation when returning
 ------
 
 Methods returning an `int` signal successful operation when returning
@@ -563,13 +625,15 @@ value. E.g. `-EINVAL` to signal that some input value was invalid.
 Additionally, logging of error messages is done on the standard error
 file descriptor to help debugging the issue.
 
 Additionally, logging of error messages is done on the standard error
 file descriptor to help debugging the issue.
 
-<div id="Usage">Usage</div>
+<div id="Usage"></div>
+
+Usage
 -----
 
 ### Initialization of LibWindowmanager
 
 Before usage of the LibWindowmanager, the method `init()` must be
 -----
 
 ### Initialization of LibWindowmanager
 
 Before usage of the LibWindowmanager, the method `init()` must be
-called once, it will return `-errno` in case of en error and log
+called once, it will return `-errno` in case of an error and log
 diagnostic messages to stderr.
 
 ### Request a surface
 diagnostic messages to stderr.
 
 ### Request a surface
@@ -581,7 +645,8 @@ be created.
 
 This is also true for *QML* applications, where only after the
 `requestSurface()` should the load of the resource be done. The method
 
 This is also true for *QML* applications, where only after the
 `requestSurface()` should the load of the resource be done. The method
-returns `0` after the surface was requested successfully.
+returns `surface id` a client application can use
+after the surface was requested successfully.
 
 #### Workings of requestSurface()
 
 
 #### Workings of requestSurface()
 
@@ -598,7 +663,9 @@ increment this numeric ID internally - which then will lead to IDs that
 cannot be known by the window manager as there is no direct
 communication from *Qt* to the WM.
 
 cannot be known by the window manager as there is no direct
 communication from *Qt* to the WM.
 
-<div id="Events">Events</div>
+<div id="Events"></div>
+
+Events
 ------
 
 Events are a way for the *Window Manager* to propagate information to
 ------
 
 Events are a way for the *Window Manager* to propagate information to
@@ -658,10 +725,14 @@ contents - again, this is handled implicitly by the wayland protocol.
 that is *signal* the compositor that its surface contains new content.
 
 -   `SyncDraw(json_object *object)`
 that is *signal* the compositor that its surface contains new content.
 
 -   `SyncDraw(json_object *object)`
-    args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout'  }
+    args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout',
+            'kKeyDrawingRect': { "x": int value of x-coordinate, "y": int value of y-coordinate,
+                                 "width": int value of width, "height": int value of height } }
     Signal applications, that the
     Signal applications, that the
-    surface with name `kKeyDrawingArea` needs to redraw its content - this
+    surface with name `kKeyDrawingArea` needs to redraw its content
+    in the layout with name `kKeyDrawingArea` - this
     usually is sent when the surface geometry changed.
     usually is sent when the surface geometry changed.
+    And the area position and size are included with name `kKeyDrawingRect`.
 
 -   `FlushDraw(json_object *object)`
     args: { 'kKeyDrawingName': 'application name' }
 
 -   `FlushDraw(json_object *object)`
     args: { 'kKeyDrawingName': 'application name' }
@@ -670,7 +741,9 @@ that is *signal* the compositor that its surface contains new content.
     drawn content as the window manager is ready to activate a new
     layout (i.e. a new surface geometry).
 
     drawn content as the window manager is ready to activate a new
     layout (i.e. a new surface geometry).
 
-<div id="Sample">Sample</div>
+<div id="Sample"></div>
+
+Sample
 ============
 
 In order to enable application to use the `WM` surface registration
 ============
 
 In order to enable application to use the `WM` surface registration