diff options
Diffstat (limited to 'doc/ApplicationGuide.md')
| -rw-r--r-- | doc/ApplicationGuide.md | 365 |
1 files changed, 196 insertions, 169 deletions
diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md index 6278315..ae6ab0a 100644 --- a/doc/ApplicationGuide.md +++ b/doc/ApplicationGuide.md @@ -1,14 +1,6 @@ # **Window Manager Application Guide** -<div align="right">Revision: 0.7</div> -<div align="right">TOYOTA MOTOR CORPORATION</div> -<div align="right">12th/Oct/2018</div> - -* * * - -<div id="Table\ of\ content"></div> - -# Table of content +## Table of content - [Target reader of this document](#Target\ reader\ of\ this\ document) - [Overview](#Overview) @@ -29,9 +21,11 @@ - [Enabling split](#Enabling\ split) - [Release Note](#Release\ Note) -* * * +| Version | Author | Updated at | +|:-:|:-:|:-:| +| 0.8 | TOYOTA MOTOR CORPORATION| 22th/Feb/2019 | -<div id="Target\ reader\ of\ this\ document"></div> +* * * ## Target reader of this document @@ -61,8 +55,6 @@ and projects before using Window manager. * * * -<div id="Overview"></div> - # Overview Window Manager is the service process which provides **window management based on policy**. @@ -70,12 +62,12 @@ And implements a layout switching of applications on multiple layers and with different layer layouts. Window Manager is based on ivi layer management from GENIVI and AGL application framework. -Window Manager consists of +Window Manager consists of - afb-binder - service binding library - shared library for policy management -- configuration files +- configuration files In order to understand Window Manager, the below figure shows the one of typical usecases. In this example, there are two mode for window management. @@ -87,25 +79,25 @@ In this example, there are two mode for window management. The important points are: -- **Window transition should be done by Window Manager** +- **Window transition should be done by Window Manager** + Window Manager switch application displayed on top layer by user operation(touch shortcut button). In this example, when an user touches `navigation` shortcut button, Window Manager displays `navigation` and hide `launcher`. Next, when an user touches `videoplayer` shortcut button, Window Manager divides a screen into two parts and display two applications. -- **There is a priority `role` for each application.** +- **There is a priority `role` for each application.** + Window Manager realizes state transition change based on the policy which consists of `role`. According to the state transition table, it controls the visibility of application window, layout change, and so on. The reasons why this is necessary are - - to support user driving - - not to disturb a driver concerns on driving for safety +- to support user driving +- not to disturb a driver concerns on driving for safety In this example, for safety, when the car starts running, Window Manager set up the role `videoplayer` to be masked and uncontrollable by user not to disturb driver concerns. - And, for supporting driving, set up `navigation` role to be displayed 3 seconds after the car ran. + And, for supporting driving, set up `navigation` role to be displayed 3 seconds after the car ran. In `Car Run` state, the user can't switch to other application from Navigation application until car stops. -<div id="Supported\ usecase"></div> - ## Supported usecase 1. Window Management @@ -118,13 +110,9 @@ The important points are: * * * -<div id="Getting\ Started"></div> - -# Getting Started +## Getting Started -<div id="Build"></div> - -## Build +### Build by SDK ```bash git clone https://gerrit.automotivelinux.org/gerrit/apps/agl-service-windowmanager @@ -144,9 +132,7 @@ ls package/ root windowmanager-service.wgt ``` -<div id="Install"></div> - -## Install +### Install Copy windowmanager-service.wgt to the file system then execute the following command. @@ -154,8 +140,6 @@ Copy windowmanager-service.wgt to the file system then execute the following com afm-util install windowmanager-service.wgt ``` -<div id="Bitbake"></div> - ## Bitbake You can make Window Manager object files with the following two stage operations. @@ -178,11 +162,9 @@ bitbake agl-demo-platform * * * -<div id="Enable\ to\ call\ Window\ Manager"></div> - ## Enable to call Window Manager -To call Window Manager, it is important to enable the permission from security framework. +To call Window Manager, it is important to enable the permission from security framework. To use Window Manager API, an application or a service shall add the following configuration definition into "config.xml" of your application. ```xml @@ -192,7 +174,7 @@ To use Window Manager API, an application or a service shall add the following c ``` To call Window Manager function easily, Window Manager provides a library which is called "libwindowmanager". -This library provides a function style API calling interface. +This library provides a function style API calling interface. So you can include the libwindowmanager.hpp header file, and can link against this library. Please also refer to the sample application. @@ -200,18 +182,16 @@ See also our [Sample code](#Sample\ code). * * * -<div id="Software\ Architecture"></div> - -# Software Architecture +## Software Architecture The static relationship with other components is shown below. The actual logic of Window Manager is the binding in Binder(afb-daemon). Window Manager is based on AGL application framework, so the IPC via websocket is protected by AGL application framework. -The upper binder is for the application side security context. +The upper binder is for the application side security context. The lower binder is the Window Manager for the server side security context. -Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Window Manager. +Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Window Manager. On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications. An application can use libwindowmanager.so to call Window Manager API simply. @@ -220,27 +200,23 @@ Window Manager is based on the GENIVI layer management system.  -## Layers +### Layers Layers are entities that means the application stack group defined in `layers.json`. This doesn't mean layer ID defined in GENIVI ivi layer. The layer ID is used for application itself in Window Manager. Currently, application can't have multiple surfaces in Window Manager. -<div id="Layers"></div> - -## Surfaces +### Surfaces Surfaces are *placed* on layers . The surface -will then be resized to dimensions, according to the name of `areas.db` +will then be resized to dimensions, according to the name of `areas.json` application requests by `activateWindow` or policy management. As default, `normal.full` is set by libwindowmanager for native application. -<div id="Configuration"></div> +### Configuration -## Configuration - -The window manager is configured with the *layers.json*, *areas.db*, *roles.db* configuration +The window manager is configured with the *layers.json*, *areas.json*, *roles.db* configuration files. By default they are searched in `${AFM_APP_INSTALL_DIR}/etc/`. Sample configurations are provided with the window manager @@ -248,12 +224,13 @@ implementation, these samples are installed to ${AFM_APP_INSTALL_DIR}/etc/ . This configuration is supposed to be configured by policy designer which means OEM or Tier1. -### layers.json +#### layers.json + +`layers.json` has three roles. -`layers.json` has three roles. -First, to create application containers `Layer`. -Second, to set id range for applications. -Third, to attach application to `Layer` according to the role application requests. +1. Create application containers `Layer`. +1. Set id range for applications. +1. Attach application to `Layer` according to the role application requests. The sample configuration is here @@ -307,7 +284,8 @@ to a layer. functional use apart from identifying a layer with a name. - `layer_id` is the id used in GENIVI IVI layer management control. -`Layer` stacks from beginning to end. +`Layer` stacks from beginning to end. + The above `Layer` example image is below.  @@ -322,12 +300,10 @@ Note: `BackGroundLayer` name of `Layer` is exception for work around. This layer is fallback layer not to stop event loop of application when it becomes invisible. The problem is issued in <https://jira.automotivelinux.org/browse/SPEC-1484>. -<div id="Configuration\ Items"></div> +#### areas.json -### areas.db - -Area means abstract expressions of 2-dimensional size and position. -areas.db defines the area which an application is set. +Area means abstract expressions of 2-dimensional size and position. +`areas.json` defines the area which an application is set. ```json { @@ -372,7 +348,8 @@ areas.db defines the area which an application is set. } ``` -The image of the above setting is described below. +The image of the above setting is described below. +  - `name` is an abstract data of rectangle. @@ -381,21 +358,21 @@ The image of the above setting is described below. The dimensions can be specified absolute to the screen dimensions. But if `fullscreen` is not suitable to screen dimensions, Window Manager scales the area automatically. -Note: +Note: + `fullscreen` must be set because this is the base size of scaling in Window Manger. -Note: +Note: + The direction of the coordinates depends on `transform` in weston.ini. Currently, agl-demo-platform set `transform=270`. This suppose to use screen vertically. -### roles.db +#### roles.db * * * -<div id="Sequence"></div> - -# Sequence +## Sequence To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/hmiframework). @@ -407,10 +384,10 @@ The typical sequence to render your application, follow the sequence below. The above sequence is the initialization phase of your application to use Window Manager. An Application has to register your `role` to Window Manager. For ivi-shell application, Window Manager generates surfaceID to input it into the function -to create surface. -And also it is important for synchronization to get `syncDraw` event for receiving the request for resize and redraw, and notifying Window Manager of `endDraw`, so register callback function with setEventHandler for `syncDraw`. +to create surface. And also it is important for synchronization to get `syncDraw` event for receiving the request for resize and redraw, and notifying Window Manager of `endDraw`, so register callback function with setEventHandler for `syncDraw`. + +[requestSurface](#requestSurface) -[requestSurface](#requestSurface) [setEventHandler](#wm_subscribe) setEventHandler is API of libwindowmanager. This calls wm_subscribe internally. @@ -422,21 +399,23 @@ setEventHandler is API of libwindowmanager. This calls wm_subscribe internally. To display your window, your application has to request `activateWindow` with `role` and `area` to Window Manager. Window Manager checks the app should be visible on the `area` according to the policy table using `role` . If it is accepted, afb_req_success will be returned, and next Window Manager -will push the event `syncDraw` to applications which will be displayed. -If it is denied, afb_req_fail will be returned. -In this sample sequence, `syncDraw` is emitted to the apps who requested only, +will push the event `syncDraw` to applications which will be displayed. If it is denied, afb_req_fail will be returned. In this sample sequence, `syncDraw` is emitted to the apps who requested only, but this shall be emitted to other applications whose size shall be changed. -[activateWindow](#activateWindow) -[syncDraw](#syncDraw) -[endDraw](#endDraw) +[activateWindow](#activateWindow) + +[syncDraw](#syncDraw) + +[endDraw](#endDraw) + [flushDraw](#flushDraw) 3. Activate OnScreen Window  -[deactivateWindow](#deactivateWindow) +[deactivateWindow](#deactivateWindow) + [See sample code for more detail about OnScreen Window.](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps%2Fonscreenapp.git;a=summary) The above sequence shows the sample of OnScreen Window. @@ -447,11 +426,9 @@ Note : Above repository is currently empty, so please refer to the sandbox branc * * * -<div id="API\ reference"></div> +## API reference -# API reference - -## Request to Window Manager +### Request to Window Manager | Use | verb | version | |:-:|:-:|:-:| @@ -461,7 +438,9 @@ Note : Above repository is currently empty, so please refer to the sandbox branc |Activate/Deactivate| activateWindow | from 0.7 | | | deactivateWindow | from 0.7 | | | endDraw | from 0.7 | +| Change area size | changeAreaSize | from 0.8 | | Get Infomation | getDisplayInfo | from 0.7 | +| | getAreaList | from 0.8 | Note: We created this table from 0.7 @@ -469,19 +448,13 @@ The data of IPC via websocket consists of JSON. This section describes the verb of API and key. Normally, the body of requesting API will be here. -<div id="Request\ to\ Widnow \Manager"></div> - -## Initialize - -<div id="requestSurface"></div> +### Initialize -### *requestSurface* +#### *requestSurface* -Register your role to Window Manager and get surfaceID for ivi-shell. -The role is used for policy management. -SurfaceID is supposed to be set to the API `ivi_application_surface_create` of ivi-application protocol or set it to environment variable `QT_IVI_SURFACE_ID` if your app is Qt and integrate ivi-shell. +Register your role to Window Manager and get surfaceID for ivi-shell. The role is used for policy management. SurfaceID is supposed to be set to the API `ivi_application_surface_create` of ivi-application protocol or set it to environment variable `QT_IVI_SURFACE_ID` if your app is Qt and integrate ivi-shell. -- verb : "requestSurface" +- verb : "requestSurface" - argument : {"drawing_name":"your role"} the value must be selected in layers.json. @@ -494,21 +467,19 @@ argument example : } ``` -### *requestSurfaceXDG* +#### *requestSurfaceXDG* This API is for XDGLauncher, so it is not necessary for normal application. XDGLauncher is created for XDG application for desktop app without editing for HMI-Framework. Please see the repository in detail. <https://gerrit.automotivelinux.org/gerrit/gitweb?p=staging%2Fxdg-launcher.git;a=summary> -<div id="wm_subscribe"></div> - -### *wm_subscribe* +#### *wm_subscribe* Subscribe the Window Manager's event. Application must subscribe `syncDraw` event. -- verb : "wm_subscribe" +- verb : "wm_subscribe" - argument : {"event" : *event number*} argument example : @@ -531,11 +502,9 @@ The event is abstracted with a number (enumeration). | 5 | "flushDraw" | | 6 | "screenUpdated" | -## Activate/Deactivate - -<div id="activateWindow"></div> +### Activate/Deactivate -### *activateWindow* +#### *activateWindow* Request to display your application with `role` on the `area` to Window Manager. Window Manager checks the app should be visible on the `area` and change layout according to the policy table using `role` . @@ -543,7 +512,7 @@ If it is accepted, afb_req_success will be returned, and next Window Manager will push the event `syncDraw` to applications which will be displayed. If it is denied, afb_req_fail will be returned. -- verb : "activateWindow" +- verb : "activateWindow" - argument : {"drawing_name" : "your role", "drawing_area" : "your area"} the value must be selected among layers.json. @@ -557,24 +526,18 @@ argument example : } ``` -<div id="deactivateWindow"></div> - -### *deactivateWindow* +#### *deactivateWindow* Request to hide your application to Window Manager. This verb is supposed to be used by high priority application which are for example popup application or system UI application such like alert. If Window Manager set the priority of popup high in the policy, Window Manager may not hide the popup even if normal applications -send `activateWindow` until popup application send `deactivateWindow` . This behavior depends on the policy table. -After this request, Window Manager checks which app should be visible -and change layout according to the policy table. +send `activateWindow` until popup application send `deactivateWindow` . This behavior depends on the policy table. After this request, Window Manager checks which app should be visible and change layout according to the policy table. -- verb : "deactivateWindow" +- verb : "deactivateWindow" - argument : None -<div id="endDraw"></div> - -### *endDraw* +#### *endDraw* Notify Window Manager of application finishes drawing. This function must be sent in event `syncDraw`. @@ -591,16 +554,36 @@ argument example : } ``` -## Get Information +#### *changeAreaSize* + +Request to change the size of area and location. Then Window Manager sends `syncDraw` to the applications whose size and location will be changed. +The caller has responsible of appearance of layouts. + +The use case of this function is shown in below. +The system application such like HomeScreen call this function, then the layout changes. The trigger may be user request on GUI, or system events and so on. + + + +The sequence is below. -### *getDisplayInfo* + + +- verb : "changeAreaSize" +- argument : {"areas" : [{"name":"area_name","rect":{"x":int,"y":int,"w":int,"h":int}, ...}]} + +Note: Only the application whose role is written in whitelist is allowed to call this API. This is because marcious application can change the layouts. The layout should be controled by system application. + +### Get Information + +#### *getDisplayInfo* Get screen information such as resolution. - verb : "getDisplayInfo" - argument : None -Return : The screen information will return. +Return : The screen information will return. + Return example : ```json @@ -621,13 +604,55 @@ Return example : } ``` -Note : +Note : + "width_mm", "height_mm" is from output which is one of the wayland object. These items lack reliability, so recommend not to use. -<div id="Event\ from\ Window \Manager"></div> +#### *getAreaList* -## Event from Window Manager +Get area definition defined in areas.json. + +- verb : "getAreaList" +- argument : None + +Return : The area definition list. + +Return example : + +```json +{ + "response":{ + "areas":[ + { + "name":"on_screen", + "rect":{ + "x":0, + "y":218, + "w":1080, + "h":1488 + } + }, + { + "name":"restriction.split.sub", + "rect":{ + "x":0, + "y":962, + "w":1080, + "h":744 + } + } + ] + }, + "jtype":"afb-reply", + "request":{ + "status":"success", + "uuid":"0e6b8835-0df0-4a34-9718-125e6258b378" + } +} +``` + +### Event from Window Manager | Number | Event | version | |:-:|:-:|:-:| @@ -657,7 +682,7 @@ The data of event is contained in `data` such like the message of event. This section describes "event" and the contents of "data". -### active +#### active This event means when the application becomes active state. @@ -674,7 +699,7 @@ example : } ``` -### inactive +#### inactive This event means when the application becomes inactive state. @@ -691,7 +716,7 @@ example : } ``` -### visible +#### visible This event is issued when the application is visible state. @@ -708,7 +733,7 @@ example : } ``` -### invisible +#### invisible This event is issued when the application is invisible state. @@ -725,9 +750,7 @@ example : } ``` -<div id="syncDraw"></div> - -### syncDraw +#### syncDraw This event is issued by Window Manager state change operation in policy to the following cases. @@ -764,12 +787,9 @@ example : An application which gets this event must send `endDraw`. For details, please see the sequence. -<div id="flushDraw"></div> +#### flushDraw -### flushDraw - -This event is issued after Window Manager receives all `endDraw` from applications who recieved `syncDraw` . -After this event, Window Manager expects applications to update its surface. +This event is issued after Window Manager receives all `endDraw` from applications who recieved `syncDraw` . After this event, Window Manager expects applications to update its surface. example : @@ -784,10 +804,9 @@ example : } ``` -### screenUpdated +#### screenUpdated -This event is issued after the visible application changes as a state transition change. This contains resized applications and visible applications. This event is issued to all subscriber. -Typical usecase is only for HomeScreen. If HomeScreen has an animation until the started application is visible such as progress bar, this signal may become a switch to stop the animation. +This event is issued after the visible application changes as a state transition change. This contains resized applications and visible applications. This event is issued to all subscriber. Typical usecase is only for HomeScreen. If HomeScreen has an animation until the started application is visible such as progress bar, this signal may become a switch to stop the animation. ```json { @@ -804,9 +823,7 @@ Typical usecase is only for HomeScreen. If HomeScreen has an animation until the "ids" is the application_id described in config.xml of application. -<div id="Client library"></div> - -## Client library +### Client library A client library implementation that internally uses the *libafbwsc*, is provided in the `libwindowmanager`. @@ -816,9 +833,7 @@ Regarding more detail, please refer to <https://gerrit.automotivelinux.org/gerri * * * -<div id="Sample\ Code"></div> - -# Sample code +## Sample code In order to enable application to activate application(render on layer), above described steps need to be implemented. @@ -826,21 +841,21 @@ above described steps need to be implemented. As a minimal example the usage and initialization can look like the following. -Repo: `git clone https://gerrit.automotivelinux.org/gerrit/src/libhomescreen` -Path: `sample/simple-egl/main.c` Typical implementation of C++ application. -Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/radio` +- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/src/libhomescreen` + - Path: `sample/simple-egl/main.c` + Typical implementation of Qt application. -Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/videoplayer` -This is the good example to write more simply for Qt application using QtAGLExtra. +- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/radio` +- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/videoplayer` -<div id="Policy Manager"></div> +This is the good example to write more simply for Qt application using QtAGLExtra. -# Policy Manager +## Policy Manager -## Concepts +### Concepts Policy Manager decides next layout by using input event data and current state based on the policy table. @@ -848,22 +863,24 @@ based on the policy table. And PolicyManager is plugin for WindowManager. Therefore the OEMs can replace it. -<div id="Enabling\ split"></div> +### Enabling split -## Enabling split - -Window Manager supports split layout to change policy and `areas.db`. -This section describes how to play split layout. -The sample image is here. +Window Manager supports split layout to change policy and `areas.json`. +This section describes how to play split layout. The sample image is here.  To play the split layout, -1. Edit in `policy_manager/CMakeLists.txt` as follows: - #set(STM_DIR stub) - set(STM_DIR zipc) - This results in using source code generated by ZIPC. +1. Edit in `policy_manager/CMakeLists.txt` as follows: + +```cmake:policy_manager/CMakeList.txt + #set(STM_DIR stub) + set(STM_DIR zipc) +``` + +This results in using source code generated by ZIPC. + 1. Set bool value "ON" to TRY_SPLIT_LAYOUT at line 28 in policy_manager/CMakeLists.txt as follows: set(TRY_SPLIT_LAYOUT ON CACHE BOOL "Enable to show split layout") 1. compile @@ -872,25 +889,35 @@ To play the split layout, As a result, if application requests `navi` with `activateWindow` when current layout is `video` or `mediaplayer`, Window Manager change layout to split window. The reverse is true. -Note: -Currently, the policy manager force application change the size even if the application which has the role doesn't have the split design. -In that case, the view of application may be ugly. -Window Manager supposes that applications may have multi designs according to system design by OEM. -For example, if OEM sets 2 pattern layout for `navi`, the application which requests `navi` should have 2 pattern designs. +Note: -* * * +Currently, the policy manager force application change the size even if the application which has the role doesn't have the split design. In that case, the view of application may be ugly. Window Manager supposes that applications may have multi designs according to system design by OEM. For example, if OEM sets 2 pattern layout for `navi`, the application which requests `navi` should have 2 pattern designs. -<div id="Release\ Note"></div> +* * * -# Release Note +## Release Note -## version: 0.7 +### version: 0.8 -### New Feature +#### New Feature - Add Policy Manager -### Limitation +### version: 0.7 + +#### New Features + +- Add API of getting area list and changing area size on runtime + +#### Changes + +- Reduce binary size to use ilmControl library. +- Change layer management. Client has one ivi-layer and can have multi surfaces. +- Stop conversion table which is compatible with old role to avoid complexity. +- Upgrade bindings v3. +- Add configuration file over-ride mechanism. + +#### Limitation - Only single-surface Qt applications are support through the libwindowmanager library. This is a limitation of how Qt creates surface |