**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">23rd/Oct/2017</div>
+<div align="right">20th/Mar/2018</div>
* * *
<div id="Table\ of\ content"></div>
-Table of content
+Table of content
============
- [Introduction](#Introduction)
- [Intended audience](#Intended\ audience)
- [Dependencies](#Dependencies)
- [Build Configuration](#Build\ Configuration)
- [Implementation Notes](#Implementation\ Notes)
- - [Binding code generation](#Binding\ code\ generation)
- [Structure](#Structure)
- [Sequence](#Sequence)
- [Binding API](#Binding\ API)
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.
<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.
<div id="Scope\ of\ this\ Document"></div>
It does not include
-- documentation of the underlying architecture, see
+- document of the underlying architecture, see
[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).
The window manager is configured with the *layers.json* configuration
file, by default it is searched in `${AFM_APP_INSTALL_DIR}/etc/layers.json`.
-Note, that the WM will not run unless this configuration is found and valid.
+Note, that the window manager will use default configuration unless this configuration is found.
A sample configuration is provided with the window manager
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>
Configuration Items
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:
Dependencies
------------
-This project is intended to be build with the 4.0 release of AGL.
-
Build dependencies are as follows:
- afb-daemon >= 1.0
- wayland-client >= 1.11
-- cmake >= 3.6.1
+- wayland-ivi-extension >= 2.0.2 (until eel, wayland-ivi-extension >= 1.13)
+
+- cmake >= 2.8
<div id="Supported environment"></div>
**Bitbake**
```
-$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
+$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo
$ bitbake agl-demo-platform
```
That means, the build produces one shared object that exports a binding
interface.
-<div id="Binding\ code\ generation"></div>
-
-Binding code generation
------------------------
-
-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.
-
-- 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"></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
- 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).
-- `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
- 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
- `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
- `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
- 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"></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>
int init(int port, char const *token);
- // WM API
+ // 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);
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,
+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
### requestSurface(json_object *object)
-**args: `{ 'kKeyDrawingName': 'application name' }`**
+**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 debgging the issue.
+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' }`**
+**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
### 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*.)
+**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' }`**
+**args: `{ 'kKeyDrawingName': 'application name' }`**
This function is called from a client application when it is done
drawing its surface content.
### getDisplayInfo(json_object *object)
-**args: `{ }`**
+**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:
+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]}`
### getAreaInfo(json_object *in_obj, json_object *out_obj)
-**args1: `{ 'kKeyDrawingName': 'application name' }`**
-**args2: `{ }`**
+**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:
+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}`
### getAreaInfo(const char *label, json_object *out_obj)
-**args1: String of application name**
-**args2: `{ }`**
+**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.
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.
<div id="Errors"></div>
### 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
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' }
+- `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' }
+- `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
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' }
+- `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' }
+- `Invisible(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name' }
Signal applications that the
surface with name `kKeyDrawingName` is now invisible.
`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)`
+- `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 } }
+ "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' }
+- `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
As a minimal example the usage and initialization can look like the
following.
-Repo: `apps/agl-service-homescreen-2017`
-Path: `sample/template/main.c`
+Repo: `apps/agl-service-homescreen-2017`
+Path: `sample/template/main.c`
Code Review / apps / agl-service-windowmanager.git / commitdiff