libwindowmanager/doc/LibWindowmanager.md

   1 Introduction
   2 ============
   3
   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.
   7
   8 Intended audience
   9 -----------------
  10
  11 This document is intended to be useful to application developers.
  12
  13 Scope of this Document
  14 ----------------------
  15
  16 This document describes the singleton class interface to the *Window
  17 Manager* binding service.
  18
  19 class LibWindowmanager
  20 ===============
  21
  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.
  25
  26     class LibWindowmanager
  27     {
  28     public:
  29         static LibWindowmanager &instance();
  30
  31         int init(int port, char const *token);
  32
  33         // WM API
  34         int requestSurface(const char *label);
  35         int activateSurface(const char *label);
  36         int deactivateSurface(const char *label);
  37         int endDraw(const char *label);
  38
  39         enum EventType {
  40            Event_Active,
  41            Event_Inactive,
  42            Event_Visible,
  43            Event_Invisible,
  44            Event_SyncDraw,
  45            Event_FlushDraw,
  46         };
  47
  48         void set_event_handler(enum EventType et,
  49              std::function<void(char const *label)> f);
  50     };
  51
  52 Errors
  53 ------
  54
  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.
  58
  59 Additionally, logging of error messages is done on the standard error
  60 file descriptor to help debugging the issue.
  61
  62 Labels
  63 ------
  64
  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.
  69
  70 Methods
  71 -------
  72
  73 ### LibWindowmanager::init(port, token)
  74
  75 Initialize the Binding communication.
  76
  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`.
  80
  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`.
  83
  84 ### LibWindowmanager::requestSurface(label)
  85
  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.
  90
  91 ### LibWindowmanager::activateSurface(label)
  92
  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
  96 *label*.
  97
  98 This method only is effective after the actual window or surface was
  99 created by the application.
 100
 101 ### LibWindowmanager::deactivateSurface(label)
 102
 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*.)
 108
 109 This method only is effective after the actual window or surface was
 110 created by the application.
 111
 112 ### LibWindowmanager::endDraw(label)
 113
 114 This function is called from a client application when it is done
 115 drawing its surface content.
 116
 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.
 121
 122 ### LibWindowmanager::set\_event\_handler(et, func)
 123
 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.
 128
 129 The `func` handler functions will receive the label of the surface this
 130 event is targeted at.
 131
 132 See Section [Events](#_events) for mor detailed information about event
 133 delivery to client applications.
 134
 135 Usage
 136 -----
 137
 138 ### Initialization of LibWindowmanager
 139
 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.
 143
 144 ### Request a surface
 145
 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
 149 be created.
 150
 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.
 154
 155 #### Workings of requestSurface()
 156
 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
 162 the surface.
 163
 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.
 169
 170 Events
 171 ------
 172
 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
 176 wayland protocol.
 177
 178 All events have the surface `label` as argument - a way to enable future
 179 multi-surface applications.
 180
 181 As already stated above, this is currently not possible with the way
 182 *Qt* implements its surface ID setting.
 183
 184 ### Active and Inactive Events
 185
 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.
 189
 190 ### Visible and Invisible
 191
 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.
 196
 197 ### SyncDraw and FlushDraw
 198
 199 These events instruct applications that they should redraw their surface
 200 contents - again, this is handled implicitly by the wayland protocol.
 201
 202 `SyncDraw` is sent to the application when it has to redraw its surface.
 203
 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.
 206
 207 Example Use Case
 208 ----------------
 209
 210 In order to enable application to use the `WM` surface registration
 211 function the above described steps need to be implemented.
 212
 213 As a minimal example the usage and initialization can look like the
 214 following.
 215
 216         // Assume a program argc and argv.
 217         QGuiApplication app(argc, argv);
 218
 219         auto &wm = LibWindowmanager::instance();
 220
 221         // initialize the LibWindowmanager binding.
 222         if(wm.init(1234, "wmtest") != 0) {
 223             exit(EXIT_FAILURE);
 224         }
 225
 226         // Request a surface label from the WM.
 227         char const *surface_label = "AppMediaPlayer";
 228         if (wm.requestSurface(surface_label) != 0) {
 229             exit(EXIT_FAILURE);
 230         }
 231
 232         // Register an Active event handler.
 233         wm.set_event_handler(Event_Active,
 234              [](char const *label) {
 235                 qDebug() << "Surface" << label << "got activated";
 236              });
 237
 238         // Initialize application window
 239         // ...
 240
 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");
 245            exit(EXIT_FAILURE);
 246         }
 247
 248         // e.g. exec the qt application
 249         app.exec();
 250