Because agl-doc converter doesn't work on current document,
some HTML tags was changed.
Change-Id: Ie04449e9c7c892cda155c180169b75ea02317741
Signed-off-by: Yuta Doi <yuta-d@witz-inc.co.jp>
<div align="right">23rd/Oct/2017</div>
* * *
<div align="right">23rd/Oct/2017</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)
-<div id="Introduction">Introduction</div>
+<div id="Introduction"></div>
+
+Introduction
============
This WindowManager implements simple layout switching of applications on
multiple layers and with different layer layouts.
============
This WindowManager implements simple layout switching of applications on
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
need to know, how the window manager works and how it is to be used.
-----------------
This documentation 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">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
It is highly recommended to have a good understanding of these documents
and projects before using the window manager.
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:
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
The client library is built together with the window manager itself.
The client library is built together with the window manager itself.
-<div id="Concepts">Concepts</div>
+<div id="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
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
-<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
A sample configuration is provided with the window manager
implementation, this sample is installed to /etc/layers.json.
A sample configuration is provided with the window manager
implementation, this sample is installed to /etc/layers.json.
-<div id="Configuration\ Items">Configuration Items</div>
+<div id="Configuration\ Items"></div>
+
+Configuration Items
-------------------
This section describes configuration items available through
-------------------
This section describes configuration items available through
that begin with `App MPlayer Sub` can be used as a *sub* surface for
this layout.
that begin with `App MPlayer Sub` can be used as a *sub* surface for
this layout.
-The names must still match the layer’s role match!
+The names must still match the layer's role match!
+
+<div id="Building\ and\ Running"></div>
-<div id="Building\ and\ Running">Building and Running</div>
-<div id="Dependencies">Dependencies</div>
+<div id="Dependencies"></div>
+
+Dependencies
------------
This project is intended to be build with the 4.0 release of AGL.
------------
This project is intended to be build with the 4.0 release of AGL.
-<div id="Build\ Configuration">Build Configuration</div>
+<div id="Build\ Configuration"></div>
+
+Build Configuration
-------------------
**Download recipe**
-------------------
**Download recipe**
By default these options will be disabled.
By default these options will be disabled.
-<div id="Implementation\ Notes">Implementation Notes</div>
+<div id="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>
+<div id="Binding\ code\ generation"></div>
+
+Binding code generation
-----------------------
The binding API is rather simple; functions receive a json object
-----------------------
The binding API is rather simple; functions receive a json object
internal state of the window manager might be broken at this time (hence
the talkative error log).
internal state of the window manager might be broken at this time (hence
the talkative error log).
-<div id="Structure">Structure</div>
+<div id="Structure"></div>
+
+Structure
---------
The implementation is loosely split across the following source files:
---------
The implementation is loosely split across the following source files:
libwayland-client wrapper. It is instanced in `main.cpp` and handles
all our wayland needs.
libwayland-client wrapper. It is instanced in `main.cpp` and handles
all our wayland needs.
-<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 documentation](https://wiki.automotivelinux.org/windowmanager).
-<div id="Binding\ API">Binding API</div>
+<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.
===============
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`.
-<div id="Methods">Methods</div>
+<div id="Methods"></div>
+
+Methods
-------
### init(int port, char const *token)
-------
### init(int port, char const *token)
Initialize the Binding communication.
The `token` parameter is a string consisting of only alphanumeric characters.
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
i.e. this call will return `-EINVAL`.
The `port` parameter is the port the afb daemon is listening on, an
### requestSurface(json_object *object)
### 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 `0` for a successful surface request, and
`-errno` on failure. Additionally, on the standard error, messages are
This method requests a surface with the label given from the *Window
Manager*. It will return `0` for a successful surface request, and
`-errno` on failure. Additionally, on the standard error, messages are
### activateSurface(json_object *object)
### 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
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)
### deactivateSurface(json_object *object)
-**args: `{ 'kKeyDrawingName': 'application name' }`**
+**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
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
### endDraw(json_object *object)
### 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.
This function is called from a client application when it is done
drawing its surface content.
See Section [Events](#_events) for mor detailed information about event
delivery to client applications.
See Section [Events](#_events) for mor detailed information about event
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
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
-----
### Initialization of LibWindowmanager
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
respectively. Usually this means it was switched visible - which means
the surface will now be on the screen and therefor continue to render.
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.
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
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.
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.
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.
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.
`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' }
+- `SyncDraw(json_object *object)`
+ args: { 'kKeyDrawingName': 'application name', 'kKeyDrawingArea': 'layout' }
Signal applications, that the
surface with name `kKeyDrawingArea` needs to redraw its content - this
usually is sent when the surface geometry changed.
Signal applications, that the
surface with name `kKeyDrawingArea` needs to redraw its content - this
usually is sent when the surface geometry changed.
-- `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
layout (i.e. a new surface geometry).
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">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
As a minimal example the usage and initialization can look like the
following.
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`