New KWin Scripting Feature in 4.11

Today is the feature freeze for 4.11 which is a good point in time to blog about the new functionality in KWin Scripting in the upcoming 4.11 release.

Configuration Interfaces

Since 4.11 our scripted components support configuration interfaces. Already in previous releases it was possible to define a KConfigXT file which can be read in the script. In 4.11 it’s now possible to have a ui-file bound to the KConfigXT file and KWin generates a config module from these two files. All that is needed is to modify the metadata.desktop file so that KWin knows that this script comes with a config interface:

X-KDE-PluginInfo-Name=kwin4_effect_foo
X-KDE-PluginKeyword=kwin4_effect_foo
X-KDE-Library=kcm_kwin4_genericscripted
X-KDE-ParentComponents=kwin4_effect_foo

The X-KDE-Library needs to be set to “kcm_kwin4_effect_genericscripted” and X-KDE-ParentComponents and X-KDE-PluginKeyword need to have the same value as X-KDE-PluginInfo-Name. The KConfigXT file is expected in contents/config/main.xml and the ui-file is expected in contents/ui/config.ui.

If these few steps are followed the effect respectively the script KCM shows a configuration button for the component.

Set and Cancel Animations

The animation API got a small addition: each animation has an id which can be canceled later on with the id. Cancel stops the animation immediately, it is not reverting the animation. So if one wants to revert the animation one still needs to schedule an additional animation.

Canceling an animation for itself is not that interesting, but in combination with another new feature it becomes very important: set animations. The new set animations are just like a normal animation but they stay in the final animation position until the animation gets canceled. A normal animation just performs the state changes, e.g. fading in or out a window. But it’s not possible to fade out a window and keep it faded out. When the animation ended the window will be visible again. Now the new set animation will keep the window faded out. This is used for example in the JavaScript version of the translucency effect to animate the moving of a window:

moveResize: {
    start: function (window) {
        window.translucencyMoveResizeAnimations = set({
            window: window,
            duration: translucencyEffect.settings.duration,
            animations: [{
                type: Effect.Opacity,
                to: translucencyEffect.settings.moveresize / 100.0
            }]
        });
    },
    finish: function (window) {
        if (window.translucencyMoveResizeAnimations !== undefined) {
            // start revert animation
            animate({
                window: window,
                duration: translucencyEffect.settings.duration,
                animations: [{
                    type: Effect.Opacity,
                    from: translucencyEffect.settings.moveresize / 100.0
                }]
            });
            // and cancel previous animation
            cancel(window.translucencyMoveResizeAnimations);
            window.translucencyMoveResizeAnimations = undefined;
        }
    }
}

This code snippet shows how to use the set animation and where one can best store the returned id: just use dynamic properties on the window. Also it shows how the animation can be reverted by specifying an animation in the opposite direction.

When using the set functionality one needs to be aware of one aspect of the behavior which can be considered as a disadvantage: the window will considered to be rendered with this animation until it gets canceled. Even if the window gets closed, minimized, activity changed or virtual desktop changes. The window will be there. So one needs to connect to events which could make windows go away and cancel the animations. Also when a window becomes visible again one should start the set animation again. There is a very easy test to see whether a window is currently visible: a new property called visible which is defined on the EffectWindow. It’s true if the window is currently not minimized, on the current desktop and on the current activity.

New Animation Types

4.11 also allows to animate in two new ways. There is Effect.DecorationOpacity which allows to just animate the opacity of the window decoration without changing the opacity of the whole window. Like before using Effect.Opacity animates both window content and window decoration. Obviously this only works with server side decorations.

The other new animation type is Effect.CrossFadePrevious which is a rather interesting new animation type for improving animations when the size of the window changes. When used KWin will keep the previous window texture and render it on top of the current window texture. This allows to cross fade from the previous window size to the new window size. If one wants to see it in action: the maximize effect is using it. This feature is currently only available in the OpenGL compositors.

New QML Components

The KWin QML Scripting API got extended by one new component: DesktopThumbnailItem. This component can render a preview of a virtual desktop:

KWin.DesktopThumbnailItem {
    id: thumbnailItem
    clip: true
    desktop: model.desktop
    anchors {
        fill: parent
    }
}

This component is used for example in one of the new desktop switchers.

Client Models

4.11 comes with a set of new models which can be instantiated in QML.

ClientFilterModel {
    id: filterModel
    clientModel: ClientModelByScreen {
        exclusions: ClientModel.DockWindowsExclusion
    }
    filter: screens.filter
}

These models are meant to be the base for functionality like Desktop Grid or Present Windows. 4.11 includes a SimpleClientModel, ClientModelByScreen and ClientModelByScreenAndDesktop. More models can easily be added, just let me know what you need. Also there is the ClientFilterModel which is a helper model to perform searches like known from the Present Windows effect.

Although these models are shipped in 4.11 KWin does not yet use them. They are meant to replace Present Windows and Desktop Grid in future, but this has to wait for QtQuick 2.