+ all our wayland needs. These files are in master. In eel, the name
+ of these files are `wayland.cpp` / `wayland.hpp`
+
+<div id="Sequence"></div>
+
+Sequence
+===============
+
+To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/windowmanager).
+
+
+<div id="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.
+
+<div id="LibWindowmanager"></div>
+
+LibWindowmanager
+------
+
+This is the public interface of the class `LibWindowmanager`.
+
+ class LibWindowmanager
+ {
+ public:
+ LibWindowmanager();
+ ~LibWindowmanager();
+
+ enum EventType {
+ Event_Active = 0,
+ Event_Inactive,
+
+ Event_Visible,
+ Event_Invisible,
+
+ Event_SyncDraw,
+ Event_FlushDraw,
+ };
+
+ int init(int port, char const *token);
+
+ // Window manager API
+ 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 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);
+
+ };
+
+<div id="Methods"></div>
+
+Methods
+-------
+
+### init(int port, char const *token)
+
+Initialize the Binding communication.
+
+The `token` parameter is a string consisting of only alphanumeric characters.
+If these conditions are not met, the LibWindowmanager instance will not initialize,
+i.e. this call will return `-EINVAL`.
+
+The `port` parameter is the port the afb daemon is listening on, an
+invalid port will lead to a failure of the call and return `-EINVAL`.
+
+### requestSurface(json_object *object)
+
+**args: `{ 'kKeyDrawingName': 'application name' }`**
+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
+logged to help debugging the issue.
+
+### activateSurface(json_object *object)
+
+**args: `{ 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }`**
+This method is mainly intended for *manager* applications that control
+other applications (think an application manager or the *HomeScreen*).
+It instructs the window manager to activate the surface with the given
+*label*.
+
+This method only is effective after the actual window or surface was
+created by the application.
+
+### deactivateSurface(json_object *object)
+
+**args: `{ 'kKeyDrawingName': 'application name' }`**
+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.
+
+### endDraw(json_object *object)
+
+**args: `{ 'kKeyDrawingName': 'application name' }`**
+This function is called from a client application when it is done
+drawing its surface content.
+
+It is not crucial to make this call at every time a drawing is finished
+- it is mainly intended to allow the window manager to synchronize
+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
+events described in the EventType enum. Only one hendler for each
+EventType is possible, i.e. if it is called multiple times with the same
+EventType the previous handler will be replaced.
+
+The `func` handler functions will receive the label of the surface this
+event is targeted at.
+
+See Section [Events](#_events) for more detailed information about event
+delivery to client applications.
+
+<div id="Errors"></div>
+
+Errors
+------
+
+Methods returning an `int` signal successful operation when returning
+`0`. In case of an error, an error value is returned as a negative errno
+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.
+
+<div id="Usage"></div>
+
+Usage
+-----
+
+### Initialization of LibWindowmanager
+
+Before usage of the LibWindowmanager, the method `init()` must be
+called once, it will return `-errno` in case of an error and log
+diagnostic messages to stderr.
+
+### Request a surface
+
+When creating a surface with *Qt* - it is necessary to request a surface
+from the WM, internally this will communicate with the window manager
+binding. Only after `requestSurface()` was successful, a surface should
+be created.
+
+This is also true for *QML* applications, where only after the
+`requestSurface()` should the load of the resource be done. The method
+returns `surface id` a client application can use
+after the surface was requested successfully.
+
+#### Workings of requestSurface()
+
+`LibWindowmanager::requestSurface()` calls the AFB binding verb
+`requestsurface` of the `windowmanager` API. This API call will return a
+numeric ID to be used when creating the surface. This ID is never
+explicitly returned to the client application, instead, it is set in the
+application environment in order for *Qt* to then use it when creating
+the surface.
+
+With the current *Qt* implementation this means, that only one surface
+will be available to client applications, as subsequent windows will
+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.
+
+<div id="Events"></div>
+
+Events
+------
+
+Events are a way for the *Window Manager* to propagate information to
+client applications. It was vital for the project to implement a number
+of events, that mirror functionality that is already present in the
+wayland protocol.
+
+All events have the surface label as argument - a way to enable future
+multi-surface applications.
+
+As already stated above, this is currently not possible with the way
+*Qt* implements its surface ID setting.
+
+### Active and Inactive Events
+
+These events signal an application that it was activated or deactivated
+respectively. Usually this means it was switched visible - which means
+the surface will now be on the screen and therefor continue to render.
+
+- `Active(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name' }
+ Signal that the surface with the name
+ `kKeyDrawingName` is now active.
+
+- `Inactive(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name' }
+ Signal that the surface with the
+ name `kKeyDrawingName` is now inactive. This usually means, the layout
+ got changed, and the surface is now considered inactive
+ (or sleeping).
+
+### Visible and Invisible
+
+These events signal an application that it was switched to be visible or
+invisible respectively. These events also are handled implicitly through
+the wayland protocol by means of `wl_surface::enter` and
+`wl_surface::leave` events to the client.
+
+- `Visible(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name' }
+ Signal applications, that the
+ surface with name `kKeyDrawingName` is now visible.
+
+- `Invisible(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name' }
+ Signal applications that the
+ surface with name `kKeyDrawingName` is now invisible.
+
+### SyncDraw and FlushDraw
+
+These events instruct applications that they should redraw their surface
+contents - again, this is handled implicitly by the wayland protocol.
+
+`SyncDraw` is sent to the application when it has to redraw its surface.
+
+`FlushDraw` is sent to the application when it should swap its buffers,
+that is *signal* the compositor that its surface contains new content.
+
+- `SyncDraw(json_object *object)`
+ 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
+ surface with name `kKeyDrawingArea` needs to redraw its content
+ in the layout with name `kKeyDrawingArea` - this
+ 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' }
+ Signal applications, that the
+ surface with name `kKeyDrawingArea` can now be swapped to its newly
+ drawn content as the window manager is ready to activate a new
+ layout (i.e. a new surface geometry).
+
+<div id="Sample"></div>
+
+Sample
+============
+
+In order to enable application to use the `WM` surface registration
+function the above described steps need to be implemented.
+
+As a minimal example the usage and initialization can look like the
+following.
Code Review / apps / agl-service-windowmanager-2017.git / blobdiff