4 The LibWindowmanager library provides a simple interface to manipulate and
5 query the state of the window manager application framework binding.
6 It is needs to be integrated and called from the client application.
11 This document is intended to be useful to application developers.
13 Scope of this Document
14 ----------------------
16 This document describes the singleton class interface to the *Window
17 Manager* binding service.
19 class LibWindowmanager
22 This is the public interface of the class `LibWindowmanager`. Private members
23 and methods are not reproduced as they will not affect usage of the
24 class by client applications.
26 class LibWindowmanager
29 static LibWindowmanager &instance();
31 int init(int port, char const *token);
34 int requestSurface(const char *label);
35 int activateSurface(const char *label);
36 int deactivateSurface(const char *label);
37 int endDraw(const char *label);
48 void set_event_handler(enum EventType et,
49 std::function<void(char const *label)> f);
55 Methods returning an `int` signal successful operation when returning
56 `0`. In case of an error, an error value is returned as a negative errno
57 value. E.g. `-EINVAL` to signal that some input value was invalid.
59 Additionally, logging of error messages is done on the standard error
60 file descriptor to help debugging the issue.
65 Surface labels are any valid strings. For `requestSurface()` these
66 strings must match the *Window Manager* configuration in order to be
67 allowed to be displayed on one layer or the other. For all other calls
68 the label must match the exact name of a requested surface.
73 ### LibWindowmanager::init(port, token)
75 Initialize the Binding communication.
77 The `token` parameter is a string consisting of only alphanumeric characters.
78 If these conditions are not met, the LibWindowmanager instance will not initialize,
79 i.e. this call will return `-EINVAL`.
81 The `port` parameter is the port the afb daemon is listening on, an
82 invalid port will lead to a failure of the call and return `-EINVAL`.
84 ### LibWindowmanager::requestSurface(label)
86 This method requests a surface with the label given from the *Window
87 Manager*. It will return `0` for a successful surface request, and
88 `-errno` on failure. Additionally, on the standard error, messages are
89 logged to help debgging the issue.
91 ### LibWindowmanager::activateSurface(label)
93 This method is mainly intended for *manager* applications that control
94 other applications (think an application manager or the *HomeScreen*).
95 It instructs the window manager to activate the surface with the given
98 This method only is effective after the actual window or surface was
99 created by the application.
101 ### LibWindowmanager::deactivateSurface(label)
103 This method is mainly intended for *manager* applications that control
104 other applications. It instructs the window manager to deactivate the
105 surface associated with the given label. Note, that deactivating a
106 surface also means to implicitly activate another (the last active or if
107 not available *main surface* or *HomeScreen*.)
109 This method only is effective after the actual window or surface was
110 created by the application.
112 ### LibWindowmanager::endDraw(label)
114 This function is called from a client application when it is done
115 drawing its surface content.
117 It is not crucial to make this call at every time a drawing is finished
118 - it is mainly intended to allow the window manager to synchronize
119 drawing in case of layout switch. The exact semantics are explained in
120 the next [Events](#_events) Section.
122 ### LibWindowmanager::set\_event\_handler(et, func)
124 This method needs to be used to register event handlers for the WM
125 events described in the EventType enum. Only one hendler for each
126 EventType is possible, i.e. if it is called multiple times with the same
127 EventType the previous handler will be replaced.
129 The `func` handler functions will receive the label of the surface this
130 event is targeted at.
132 See Section [Events](#_events) for mor detailed information about event
133 delivery to client applications.
138 ### Initialization of LibWindowmanager
140 Before usage of the LibWindowmanager, the method `init()` must be
141 called once, it will return `-errno` in case of en error and log
142 diagnostic messages to stderr.
144 ### Request a surface
146 When creating a surface with *Qt* - it is necessary to request a surface
147 from the WM, internally this will communicate with the window manager
148 binding. Only after `requestSurface()` was successful, a surface should
151 This is also true for *QML* aplications, where only after the
152 `requestSurface()` should the load of the resource be done. The method
153 returns `0` after the surface was requested successfully.
155 #### Workings of requestSurface()
157 `LibWindowmanager::requestSurface()` calls the AFB binding verb
158 `requestsurface` of the `windowmanager` API. This API call will return a
159 numeric ID to be used when creating the surface. This ID is never
160 explicitly returned to the client application, instead, it is set in the
161 application environment in order for *Qt* to then use it when creating
164 With the current *Qt* implementation this means, that only one surface
165 will be available to client applications, as subsequent windows will
166 increment this numeric ID internally - which then will lead to IDs that
167 cannot be known by the window manager as there is no direct
168 communication from *Qt* to the WM.
173 Events are a way for the *Window Manager* to propagate information to
174 client applications. It was vital for the project to implement a number
175 of events, that mirror functionality that is already present in the
178 All events have the surface `label` as argument - a way to enable future
179 multi-surface applications.
181 As already stated above, this is currently not possible with the way
182 *Qt* implements its surface ID setting.
184 ### Active and Inactive Events
186 These events signal an application that it was activated or deactivated
187 respectively. Usually this means it was switched visible - which means
188 the surface will now be on the screen and therefor continue to render.
190 ### Visible and Invisible
192 These events signal an application that it was switched to be visible or
193 invisible respectively. These events too are handled implicitly through
194 the wayland protocol by means of `wl_surface::enter` and
195 `wl_surface::leave` events to the client.
197 ### SyncDraw and FlushDraw
199 These events instruct applications that they should redraw their surface
200 contents - again, this is handled implicitly by the wayland protocol.
202 `SyncDraw` is sent to the application when it has to redraw its surface.
204 `FlushDraw` is sent to the application when it should swap its buffers,
205 that is *signal* the compositor that its surface contains new content.
210 In order to enable application to use the `WM` surface registration
211 function the above described steps need to be implemented.
213 As a minimal example the usage and initialization can look like the
216 // Assume a program argc and argv.
217 QGuiApplication app(argc, argv);
219 auto &wm = LibWindowmanager::instance();
221 // initialize the LibWindowmanager binding.
222 if(wm.init(1234, "wmtest") != 0) {
226 // Request a surface label from the WM.
227 char const *surface_label = "AppMediaPlayer";
228 if (wm.requestSurface(surface_label) != 0) {
232 // Register an Active event handler.
233 wm.set_event_handler(Event_Active,
234 [](char const *label) {
235 qDebug() << "Surface" << label << "got activated";
238 // Initialize application window
241 // request to activate the surface, this should usually
242 // not be done by the client application.
243 if (wm.activateSurface(surface_label) != 0) {
244 fprintf(stderr, "Could not activate the surface\n");
248 // e.g. exec the qt application