diff options
Diffstat (limited to 'libwindowmanager/doc/LibWindowmanager.txt')
| -rw-r--r-- | libwindowmanager/doc/LibWindowmanager.txt | 238 |
1 files changed, 0 insertions, 238 deletions
diff --git a/libwindowmanager/doc/LibWindowmanager.txt b/libwindowmanager/doc/LibWindowmanager.txt deleted file mode 100644 index 87394af..0000000 --- a/libwindowmanager/doc/LibWindowmanager.txt +++ /dev/null @@ -1,238 +0,0 @@ -= LibWindowmanager Library User Guide -:doctype: book -:toc: -:icons: -:data-uri: -:lang: en -:encoding: utf-8 - -== Introduction -The LibWindowmanager library provides a simple interface to manipulate and -query the state of the window manager application framework binding. -It is needs to be integrated and called from the client application. - -=== Intended audience -This document is intended to be useful to application developers. - -=== Scope of this Document -This document describes the singleton class interface to the _Window -Manager_ binding service. - -== class LibWindowmanager -This is the public interface of the class `LibWindowmanager`. Private members -and methods are not reproduced as they will not affect usage of the -class by client applications. - ---------------------------- -class LibWindowmanager -{ -public: - static LibWindowmanager &instance(); - - int init(int port, char const *token); - - // WM API - int requestSurface(const char *label); - int activateSurface(const char *label); - int deactivateSurface(const char *label); - int endDraw(const char *label); - - enum EventType { - Event_Active, - Event_Inactive, - Event_Visible, - Event_Invisible, - Event_SyncDraw, - Event_FlushDraw, - }; - - void set_event_handler(enum EventType et, - std::function<void(char const *label)> f); -}; ---------------------------- - -=== Errors -Methods returning an `int` signal successful operation when returning -`0`. In case of an error, an error value is returned as a negative errno -value. E.g. `-EINVAL` to signal that some input value was invalid. - -Additionally, logging of error messages is done on the standard error -file descriptor to help debugging the issue. - -=== Labels -Surface labels are any valid strings. For `requestSurface()` these strings -must match the _Window Manager_ configuration in order to be allowed to -be displayed on one layer or the other. For all other calls the label -must match the exact name of a requested surface. - -=== Methods - -==== LibWindowmanager::init(port, token) -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, -i.e. this call will return `-EINVAL`. - -The `port` parameter is the port the afb daemon is listening on, -an invalid port will lead to a failure of the call and return `-EINVAL`. - -==== LibWindowmanager::requestSurface(label) -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 -logged to help debgging the issue. - -==== LibWindowmanager::activateSurface(label) -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 -_label_. - -This method only is effective after the actual window or surface was -created by the application. - -==== LibWindowmanager::deactivateSurface(label) -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 -surface also means to implicitly activate another (the last active or -if not available _main surface_ or _HomeScreen_.) - -This method only is effective after the actual window or surface was -created by the application. - -==== LibWindowmanager::endDraw(label) -This function is called from a client application when it is done -drawing its surface content. - -It is not crucial to make this call at every time a drawing is finished - -it is mainly intended to allow the window manager to synchronize drawing -in case of layout switch. The exact semantics are explained in the next -<<_events,Events>> Section. - -==== LibWindowmanager::set_event_handler(et, func) -This method needs to be used to register event handlers for the WM -events described in the EventType enum. Only one hendler for each -EventType is possible, i.e. if it is called multiple times with the same -EventType the previous handler will be replaced. - -The `func` handler functions will receive the label of the surface this -event is targeted at. - -See Section <<_events,Events>> for mor detailed information about event -delivery to client applications. - -=== Usage - -==== Initialization of LibWindowmanager -Before usage of the LibWindowmanager, the method `init()` must be -called once, it will return `-errno` in case of en error and log diagnostic -messages to stderr. - -==== Request a surface -When creating a surface with _Qt_ - it is necessary to request a surface -from the WM, internally this will communicate with the window manager -binding. Only after `requestSurface()` was successful, a surface should -be created. - -This is also true for _QML_ aplications, where only after the -`requestSurface()` should the load of the resource be done. The method -returns `0` after the surface was requested successfully. - -===== Workings of requestSurface() -`LibWindowmanager::requestSurface()` calls the AFB binding verb -`requestsurface` of the `windowmanager` API. This API call will return a -numeric ID to be used when creating the surface. This ID is never -explicitly returned to the client application, instead, it is set in the -application environment in order for _Qt_ to then use it when creating the -surface. - -.Remarks -******************************** -With the current _Qt_ implementation this means, that only one surface -will be available to client applications, as subsequent windows will -increment this numeric ID internally - which then will lead to IDs that -cannot be known by the window manager as there is no direct -communication from _Qt_ to the WM. -******************************** - -=== Events -Events are a way for the _Window Manager_ to propagate information to -client applications. It was vital for the project to implement a number -of events, that mirror functionality that is already present in the -wayland protocol. - -All events have the surface `label` as argument - a way to enable future -multi-surface applications. - -.Remarks -************************** -As already stated above, this is currently not possible with the way -_Qt_ implements its surface ID setting. -************************** - -==== Active and Inactive Events -These events signal an application that it was activated or deactivated -respectively. Usually this means it was switched visible - which means -the surface will now be on the screen and therefor continue to render. - -==== Visible and Invisible -These events signal an application that it was switched to be visible or -invisible respectively. These events too are handled implicitly through -the wayland protocol by means of `wl_surface::enter` and -`wl_surface::leave` events to the client. - -==== SyncDraw and FlushDraw -These events instruct applications that they should redraw their surface -contents - again, this is handled implicitly by the wayland protocol. - -`SyncDraw` is sent to the application when it has to redraw its surface. - -`FlushDraw` is sent to the application when it should swap its buffers, -that is _signal_ the compositor that its surface contains new content. - -=== Example Use Case -In order to enable application to use the `WM` surface registration -function the above described steps need to be implemented. - -As a minimal example the usage and initialization can look like the -following. - ------------------------ - // Assume a program argc and argv. - QGuiApplication app(argc, argv); - - auto &wm = LibWindowmanager::instance(); - - // initialize the LibWindowmanager binding. - if(wm.init(1234, "wmtest") != 0) { - exit(EXIT_FAILURE); - } - - // Request a surface label from the WM. - char const *surface_label = "AppMediaPlayer"; - if (wm.requestSurface(surface_label) != 0) { - exit(EXIT_FAILURE); - } - - // Register an Active event handler. - wm.set_event_handler(Event_Active, - [](char const *label) { - qDebug() << "Surface" << label << "got activated"; - }); - - // Initialize application window - // ... - - // request to activate the surface, this should usually - // not be done by the client application. - if (wm.activateSurface(surface_label) != 0) { - fprintf(stderr, "Could not activate the surface\n"); - exit(EXIT_FAILURE); - } - - // e.g. exec the qt application - app.exec(); - -// vim:set ft=asciidoc tw=72: |