libwindowmanager/doc/LibWindowmanager.txt

   1 = LibWindowmanager Library User Guide
   2 :doctype: book
   3 :toc:
   4 :icons:
   5 :data-uri:
   6 :lang: en
   7 :encoding: utf-8
   8
   9 == Introduction
  10 The LibWindowmanager library provides a simple interface to manipulate and
  11 query the state of the window manager application framework binding.
  12 It is needs to be integrated and called from the client application.
  13
  14 === Intended audience
  15 This document is intended to be useful to application developers.
  16
  17 === Scope of this Document
  18 This document describes the singleton class interface to the _Window
  19 Manager_ binding service.
  20
  21 == 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.
  25
  26 ---------------------------
  27 class LibWindowmanager
  28 {
  29 public:
  30     static LibWindowmanager &instance();
  31
  32     int init(int port, char const *token);
  33
  34     // WM API
  35     int requestSurface(const char *label);
  36     int activateSurface(const char *label);
  37     int deactivateSurface(const char *label);
  38     int endDraw(const char *label);
  39
  40     enum EventType {
  41        Event_Active,
  42        Event_Inactive,
  43        Event_Visible,
  44        Event_Invisible,
  45        Event_SyncDraw,
  46        Event_FlushDraw,
  47     };
  48
  49     void set_event_handler(enum EventType et,
  50          std::function<void(char const *label)> f);
  51 };
  52 ---------------------------
  53
  54 === Errors
  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 Surface labels are any valid strings. For `requestSurface()` these strings
  64 must match the _Window Manager_ configuration in order to be allowed to
  65 be displayed on one layer or the other. For all other calls the label
  66 must match the exact name of a requested surface.
  67
  68 === Methods
  69
  70 ==== LibWindowmanager::init(port, token)
  71 Initialize the Binding communication.
  72
  73 The `token` parameter is a string consisting of only alphanumeric characters.
  74 If these conditions are not met, the LibWindowmanager instance will not initialize,
  75 i.e. this call will return `-EINVAL`.
  76
  77 The `port` parameter is the port the afb daemon is listening on,
  78 an invalid port will lead to a failure of the call and return `-EINVAL`.
  79
  80 ==== LibWindowmanager::requestSurface(label)
  81 This method requests a surface with the label given from the _Window
  82 Manager_. It will return `0` for a successful surface request, and
  83 `-errno` on failure. Additionally, on the standard error, messages are
  84 logged to help debgging the issue.
  85
  86 ==== LibWindowmanager::activateSurface(label)
  87 This method is mainly intended for _manager_ applications that control
  88 other applications (think an application manager or the _HomeScreen_). It
  89 instructs the window manager to activate the surface with the given
  90 _label_.
  91
  92 This method only is effective after the actual window or surface was
  93 created by the application.
  94
  95 ==== LibWindowmanager::deactivateSurface(label)
  96 This method is mainly intended for _manager_ applications that control
  97 other applications. It instructs the window manager to deactivate the
  98 surface associated with the given label. Note, that deactivating a
  99 surface also means to implicitly activate another (the last active or
 100 if not available _main surface_ or _HomeScreen_.)
 101
 102 This method only is effective after the actual window or surface was
 103 created by the application.
 104
 105 ==== LibWindowmanager::endDraw(label)
 106 This function is called from a client application when it is done
 107 drawing its surface content.
 108
 109 It is not crucial to make this call at every time a drawing is finished -
 110 it is mainly intended to allow the window manager to synchronize drawing
 111 in case of layout switch. The exact semantics are explained in the next
 112 <<_events,Events>> Section.
 113
 114 ==== LibWindowmanager::set_event_handler(et, func)
 115 This method needs to be used to register event handlers for the WM
 116 events described in the EventType enum. Only one hendler for each
 117 EventType is possible, i.e. if it is called multiple times with the same
 118 EventType the previous handler will be replaced.
 119
 120 The `func` handler functions will receive the label of the surface this
 121 event is targeted at.
 122
 123 See Section <<_events,Events>> for mor detailed information about event
 124 delivery to client applications.
 125
 126 === Usage
 127
 128 ==== Initialization of LibWindowmanager
 129 Before usage of the LibWindowmanager, the method `init()` must be
 130 called once, it will return `-errno` in case of en error and log diagnostic
 131 messages to stderr.
 132
 133 ==== Request a surface
 134 When creating a surface with _Qt_ - it is necessary to request a surface
 135 from the WM, internally this will communicate with the window manager
 136 binding. Only after `requestSurface()` was successful, a surface should
 137 be created.
 138
 139 This is also true for _QML_ aplications, where only after the
 140 `requestSurface()` should the load of the resource be done. The method
 141 returns `0` after the surface was requested successfully.
 142
 143 ===== Workings of requestSurface()
 144 `LibWindowmanager::requestSurface()` calls the AFB binding verb
 145 `requestsurface` of the `windowmanager` API. This API call will return a
 146 numeric ID to be used when creating the surface. This ID is never
 147 explicitly returned to the client application, instead, it is set in the
 148 application environment in order for _Qt_ to then use it when creating the
 149 surface.
 150
 151 .Remarks
 152 ********************************
 153 With the current _Qt_ implementation this means, that only one surface
 154 will be available to client applications, as subsequent windows will
 155 increment this numeric ID internally - which then will lead to IDs that
 156 cannot be known by the window manager as there is no direct
 157 communication from _Qt_ to the WM.
 158 ********************************
 159
 160 === Events
 161 Events are a way for the _Window Manager_ to propagate information to
 162 client applications. It was vital for the project to implement a number
 163 of events, that mirror functionality that is already present in the
 164 wayland protocol.
 165
 166 All events have the surface `label` as argument - a way to enable future
 167 multi-surface applications.
 168
 169 .Remarks
 170 **************************
 171 As already stated above, this is currently not possible with the way
 172 _Qt_ implements its surface ID setting.
 173 **************************
 174
 175 ==== Active and Inactive Events
 176 These events signal an application that it was activated or deactivated
 177 respectively. Usually this means it was switched visible - which means
 178 the surface will now be on the screen and therefor continue to render.
 179
 180 ==== Visible and Invisible
 181 These events signal an application that it was switched to be visible or
 182 invisible respectively. These events too are handled implicitly through
 183 the wayland protocol by means of `wl_surface::enter` and
 184 `wl_surface::leave` events to the client.
 185
 186 ==== SyncDraw and FlushDraw
 187 These events instruct applications that they should redraw their surface
 188 contents - again, this is handled implicitly by the wayland protocol.
 189
 190 `SyncDraw` is sent to the application when it has to redraw its surface.
 191
 192 `FlushDraw` is sent to the application when it should swap its buffers,
 193 that is _signal_ the compositor that its surface contains new content.
 194
 195 === Example Use Case
 196 In order to enable application to use the `WM` surface registration
 197 function the above described steps need to be implemented.
 198
 199 As a minimal example the usage and initialization can look like the
 200 following.
 201
 202 -----------------------
 203     // Assume a program argc and argv.
 204     QGuiApplication app(argc, argv);
 205
 206     auto &wm = LibWindowmanager::instance();
 207
 208     // initialize the LibWindowmanager binding.
 209     if(wm.init(1234, "wmtest") != 0) {
 210         exit(EXIT_FAILURE);
 211     }
 212
 213     // Request a surface label from the WM.
 214     char const *surface_label = "AppMediaPlayer";
 215     if (wm.requestSurface(surface_label) != 0) {
 216         exit(EXIT_FAILURE);
 217     }
 218
 219     // Register an Active event handler.
 220     wm.set_event_handler(Event_Active,
 221          [](char const *label) {
 222             qDebug() << "Surface" << label << "got activated";
 223          });
 224
 225     // Initialize application window
 226     // ...
 227
 228     // request to activate the surface, this should usually
 229     // not be done by the client application.
 230     if (wm.activateSurface(surface_label) != 0) {
 231        fprintf(stderr, "Could not activate the surface\n");
 232        exit(EXIT_FAILURE);
 233     }
 234
 235     // e.g. exec the qt application
 236     app.exec();
 237
 238 // vim:set ft=asciidoc tw=72: