Window Metadata

Rationale

Window Thumbnails as scaled down window content are hardly useable. Windows of same application are hardly distinguishable from each other which eliminates all advantages from thumbnails in first place.

In addition on Wayland it is difficult to get access to live-updating window thumbnails in the desktop shell. While the compositor has access to the window content, other applications do not. This would require a custom protocol to pass the window content from the compositor to the desktop shell. A protocol would be required which would be fairly close to being an own Wayland server.

This document describes how to put the application more in control of the window thumbnail which will be rendered.

General Architecture

The protocol will be implemented using DBus to be windowing system agnostic. The window manager registers a DBus service "org.kde.kwin.windowmetadata1" and the object path "/org/kde/kwin/WindowMetadata1". On this interface there is a call "register" which allows an application to call it and to indicate that it supports the protocol.

The window manager is able to map windows to the DBus peer through the PID. On both X11 and Wayland the window manager has access to the PID. In case of Wayland this is only possible for the window manager, thus the DBus service must be bound on the window manager.

When a thumbnail is required the window manager informs the application for which window and in which size a thumbnail is needed. In addition it passes a filedescriptor of a pipe to the application. The application renders the thumbnail and writes the rendering result into the pipe and closes the pipe once the rendering is finished. The application can render a thumbnail of different size if this of more use. To support that a small binary protocol on the pipe is required. It needs to describe:

size (width/height)
stride
image format
byte count
binary data

Obviously the server side needs to sanity check the values.

The protocol is not meant to have life-updating previews. There is a DBus call for the application to indicate that it has new data available, but it's the responsibility of the server to initiate the process. By that the server can control the updates to a sensible amount.

Passing thumbnail to Desktop Shell

Internal implementation detail, to be defined.

Window Actions

An additional idea is to allow the application to specify additional actions through the DBus interface. E.g. a "reload" action in a browser. This is intended to be implemented in a future release.

Task Manager Progress

Another idea is to let the application display progress of certain jobs for the task manager, eg. a download progress or compiling in an IDE. The progress will be indicated by the respective task bar item gradually filling up. There can also be an indeterminate step where the progress bar will cycle.

Furthermore, an interrupted job could be indicated by the progress changing color, eg. yellow or red. An interrupted job is a job that is waiting for user input or reports a fatal error and that cannot continue otherwise, but not a job the user manually paused.

Using the KJobUiDelegate is still prefered but only if the application itself does not provide sufficient job monitoring capabilities, ie. compiling in an IDE is fine for the task bar only, whereas copying or receiving a file should still show up in the notification area. Also, short-lived jobs or jobs that the user didn't explicitly start, such as fetching or filtering emails, should not be indicated in the task manager to not unneccessarily draing attention to them.

Ideally, the API in Window Metadata could be given a/multiple KJob(s) which it monitors and updates task bar progress automatically.

Implementation

The implementation will be provided through a tier1 framework. It will be windowing system agnostic and only depends on DBus. For the application it will be as simple as just rendering to a QImage (through QPainter) or using a special QtQuick import.