Posted on

KWin Effects written in JavaScript

Today I cannot make such a nice announcement as Aaron yesterday, but I can at least try announce something I personally consider as awesome.

This weekend I tried to make it possible to write KWin effects in JavaScript. After about two hours of work the effect loader was adjusted to load a Qt script instead of the library written in C++. This is a quite important step for the future of effects in KWin. It finally makes it possible to share effects via Get Hot New Stuff, so that our users can download new effects directly from the control module.

For packaging effects we use the well established Plasma Package structure, so that our script developers only need to know this one common way. The API itself will share as much as possible with the KWin scripting API – of course with adjustments for effects. For animating the API is based on the AnimationEffect introduced in 4.8.

From a performance point of view using JavaScript does not change anything. Our effect system has two phases: one to react on changes in the window manager (e.g. a window got activated) and one to perform the rendering. The scripting API only interacts with the window manager, so all the rendering is still good old C++ code – a similar approach to QML.

Now I guess you want to know what you can do with it. So here I present for example a Fade like effect written in JavaScript (for comparison: C++ version is > 200 SLOC):

var duration = 250;
effects.windowAdded.connect(function(w) {
    effect.animate(w, Effect.Opacity, duration, 1.0);
});
effects.windowClosed.connect(function(w) {
    effect.animate(w, Effect.Opacity, duration, 0.0, 1.0);
});

For us KWin core developers the scripted effects will be an important step as well. For quite some time we have been unhappy with the fact that there are too many effects which become difficult to maintain – especially if we have to adjust the API. With effects written in JavaScript this becomes much simpler. As we do not have to keep the ABI (API compatibility is enough) stable we can move effects written in JavaScript out of the source tree and make them available for download.

At the moment the JavaScript API is just at the beginning. But I expect it to evolve over the course of the current release cycle. For me the scripts are rather important as it also provides us an easy way to have device specific adjustments.

As I wrote currently the scripts do not operate during the rendering. Because of that we don’t have bindings for WebGL. This would at the moment not make any sense. Nevertheless it might be that we allow to upload custom shaders, but I won’t pursue such a task in the 4.9 cycle.

Posted on

Create Temporary Desktops For Applications

There are applications which are more or less a mess for a window manager. For example The GIMP opens quite a lot of windows and you want to have all of those windows visible. In general you don’t want to have any other window on the same desktop

The solution to that is to move GIMP on it’s own desktop. But how? We can use static window rules to get this working, but what if there are already windows on that desktop? The perfect solution to that would be to have a desktop which gets created when you open GIMP and gets removed again when GIMP closes.

This was so far not yet possible without manual interaction. But with todays additions to KWin scripting this became possible. Here I present a KWin script which does exactly that:

workspace.clientAdded.connect(function(client) {
  if (client.resourceClass == "gimp-2.6" && client.windowRole == "gimp-image-window") {
    // create a new workspace for the Gimp image window (kind of the main window)
    // switch to the new desktop and send the gimp window to it
    workspace.desktops = workspace.desktops+1;
    workspace.currentDesktop = workspace.desktops;
    client.desktop = workspace.currentDesktop;
  } else if (client.resourceClass == "gimp-2.6") {
    // send all other gimp windows to the current desktop
    client.desktop = workspace.currentDesktop;
  }
});

workspace.clientRemoved.connect(function(client) {
  if (client.resourceClass == "gimp-2.6" && client.windowRole == "gimp-image-window") {
    // when closing the gimp window let's remove the last desktop
    workspace.desktops = workspace.desktops-1;
  }
});

I should really start to publish the quite useful example scripts I write to test the scripting functionality on places like kde-apps 🙂 The API for 4.9 is documented on Techbase

Posted on

The Importance of Mentoring

Currently the KWin team is rewriting the work of two past Google Summer of Code projects. This is of course the worst thing which can happen about the projects. In retrospection we clearly have to say that the projects actually were failures – at least for the developer community. But both students succeeded their project, so we cannot say it’s the fault of the students. On the other hand the projects had different mentors, so blaming the mentors is too easy as well.

In this blog post I want to reflect why we consider the projects after more than one (respectively two) years as failures. What did go wrong and what can be improved in future projects? I hope this can be a help for more projects than just KWin.

I will base all examples on scripting – the project I am currently rewriting. Just to give an example of the scope: when scripting got imported into trunk it consisted of 3200 SLOC and now after the rewrite is almost finished it is down to about 500 SLOC which are mostly written by me. At the same time the provided functionality increased.

Don’t expect Students to Understand Complex Code

The scripting project should make it possible to have scripts run when “something happens”. E.g. if a window gets maximized the scripts should be notified. In the Qt way the best way to achieve that is by emitting a signal. Now this is what our student did. But in all cases I found so far the signals were emitted in the wrong place. So what is wrong?

KWin core works in a way that a user action triggers a method. E.g. entering the fullScreen mode will end up in Client::setFullScreen. But this method does not just perform setting the window to fullScreen, it also evaluates first whether it is feasible to set the window to fullscreen. For example the user might have established a window specific rule to disallow this window to go fullscreen. In that case the method will not change the state of the window.

The common pattern our student introduced was to emit the signal before the method had evaluated whether the window will change the state. So the scripts are notified with potentially wrong state change information.

Of course we cannot expect that the student for whom the code is completely new will understand these concepts. If you don’t know the internals of an application the behavior is in fact unexpected especially if it is only partially documented or commented.

Given this experience it is important to give a student enough time to get familiar with the rather complex code base. In this time it is important to provide the required help. In the example above it would have been a good advice to emit the signals whenever the effects are invoked – which happens at the same place (nowadays the notification of scripting and effects are merged) through direct method invocation.

Work in master

The Scripting GSoC got implemented in an SVN branch. For me as a team member and not being the mentor it was difficult to follow the development. In the end the branch got merged into SVN trunk without a review done by the team.

Some of the issues are resolved nowadays thanks to the git migration. So even if a student works in an own branch the team mates would get the commit mails and would be able to do a post-commit review on each commit. But still working in a branch for a long time brings disadvantages. Most likely the student is disconnected from the work. The team mates might work on the same code area, making merging more difficult – especially for a young developer who also has to learn to work with a complex VCS such as git.

So I think that it is most important to have the work been done in master (or any other development branch) directly. This might be tricky as KDE SC’s release schedule does not align well with GSoC, but as soon as the release branch is created there is no reason to not work on master.

Even while master is frozen the student should follow the common pattern and propose each change as a Review Request. This gives early feedback to the student and moves the burden of mentoring to the shoulders of the complete team. The team mates know what the student is working on and can provide early help and spot potential problems even if the mentor does not spot them. Remember: it’s not your student, it’s the team’s student.

Interfere before the student runs in the wrong direction

One of the tasks of a mentor should be to provide guidance to the student and ensure that the project goes in the right direction. I remember that my mentor did exactly that at one point were I started to do fancy stuff.

In case of the scripting project the student started to implement a kind of JavaScript extension for “Lazy Logic”. This was clearly not in the scope of the project, it might have been fun to implement for the student, but it’s nothing which is needed in a window manager. That’s just the wrong place to design new language features for JavaScript.

Given that the code was undocumented and I did not find any documentation explaining how this language feature works or why I would need it and last but not least I did not understand the code, it was one of the first code parts I dropped. This would not have been needed. The student should have concentrated on the task he is proposed to do.

Remember that the world is round

Yes, there are time zones. Yes most mentors have a day job and are restricted in the time they are available. It is no help to the project if the student works while the mentor sleeps and the student has to wait a day when he needs to ask questions to continue the project.

I remember that we had one project with the student living in Mexico and the mentor living in Australia. Of course this is a rather sub optimal combination. Don’t expect that the student will adjust his sleep rhythm. Even as a GSoC student he has the right for a normal social life.

Personally I decided not to mentor a student who doesn’t live in a European timezone. I just acknowledge with that, that I am constrained in time and that also all team members live in Europe, so we just cannot mentor students living on the other side of the world.

Communicate!

Communication is in my opinion one of the central aspects for a successful projects. During the project I mentored last year I tried to discuss the state of the project each day. And with communication I do not only mean e-mail or IRC, but also phone and personal meetings. If you live close to each other it might be a good idea to meet at least once, if the student lives in Europe Akademy is a must!

But communication is not only important with the mentor. Also with the complete team. The student should subscribe to the mailing list, read and answer review requests, be present in the IRC channel. His project benefits from it and the chances are better that the student stays after noticing how great the KDE community works.

Require Documentation

No code should be merged without documentation and without unit tests (if your project uses them). There is no excuse for a young developer to not write documentation. If the student works on a new area of code it is extremely important to have everything documented in a way that any of your team members can continue working with the code.

In case of scripting the code was lacking any documentation not even a high level description of the design was provided. This made it impossible to continue to work with the project. Trying to understand undocumented code can be more difficult than rewriting from scratch.

During a GSoC project you have the chance to enforce documentation. Make it clear that the student will not pass the final evaluation if the code is not documented. Documentation is not a nice candy, but at least as important as the code itself. Undocumented code is just unacceptable in the year 2012.

Be Prepared for the Worst

The worst for the developer team is that the student stops working with the last day of GSoC. This is bad but happens. The team has to be able to take over the project. A code dump is no solution and in doubt better not merge in the project than introduce bugs and instability. Yes that means that a GSoC project was wasted but it prevents a degeneration of the code base and does not bind your teammates to fix up the code.

In case of scripting we got a code dump which was completely undocumented and basically we have never seen anything of the student again. For me it would have been easier to just write the bindings from scratch than to fix up the project. Between the end of the project and my rewrite I had to fight several times with strange things done in scripting. So overall the project costs for the core team were higher than the benefits.

Adjust the proposed projects to the fact that the student will not be around after the project. $SUPERAWESOMEFEATURE is just bit crap if it cannot be maintained by your team. Use projects were you are sure that it will benefit the team even if the student will never touch the code again.

Adjust Your Own Expectations

Many mentors try to get just “cheap” work done and have the dream to get a new team member which might some day replace their position in the team. This might happen, but is rather unlikely. If that is your aim, you might head in the wrong direction. Now I can say lots about it, but there are people who can do that better, so I recommend to read the slides by Leslie Hawthorn from this years linux.conf.au.

The KWin team has learned from the experience with our failed projects. During last years project I was holding the hand of my student. For me it was important to get good code written and not much code or have him working on new areas. Also this year I will not mentor a project which would introduce a new area in KWin. E.g. Wayland support is out of bounds for a GSoC.

Posted on

Aurorae 3: Window Decorations with QtQuick

Once upon a time there was a window decoration which was KDE’s default decoration. But years ago it fell into a deep sleep. The world changed while the decoration slept. Compositing was added, decorations received shadows, Qt introduced the graphics system raster and many many more changes.

Now after years the decoration temporarily woke up, but it is no longer a beauty, but ugly and old. The changing world made the decoration break. The decoration’s bits started to rot and this is visible. The truth is that the decoration will stay in the broken state as there is nobody who would want to fix it or anybody knowing the code.

What I just highlighted here is true for basically all old decorations. Of the decorations we ship only Oxygen and my theme engine Aurorae are maintained. This is a situation which can no longer continue. We have to face the truth and remove all old decorations.

But of course we don’t want to remove decorations without adequate replacement and this leads us to the story of Aurorae.

Aurorae was written to experiment with new features introduced in KWin 4.3. It was based on our common decoration API and by that is rather limited. So for 4.5 I decided to port it to the generic decoration API and reimplement with GraphicsScene instead of QWidgets. Aurorae allowed to download decorations through Get Hot New Stuff.

But given that it is a theme engine the possibilities are still very limited. Only what the theme engine supports can be rendered. Porting our old decorations to the theme engine might not be possible and not to be recommended.

But still we would like to have those decorations on a modern basis without the maintenance costs. So I started to port Aurorae to QML. This does not only give us a more powerful theme engine but also introduces QML bindings for window decorations, allowing everybody to write decorations with QtQuick.

So we can write themes without the limitations of a theme engine 🙂 This does not only remove 3000 lines of C++ code and replaces it by around 1000 lines of QML code, but also gives us an interactive decoration control module.

Interactive decoration control module

For Aurorae based themes all the buttons are interactive giving our users the possibility to really try the decoration before using it. But that’s not where it will end. I want to have new themes not based on Aurorae but using QML directly. For that I want to use the Plasma Package structure and would love to see integration in Plasmate. Another idea is to support deKorator themes inside QML.

But as always this does not come without disadvantages. Not all features which were possible with Aurorae will be available in Aurorae 3. Some features will also be dropped because hardly any theme makes use of the features, for example special backgrounds for non-composited setups. Aurorae 3 will hardly work without compositing, so it might be that we will make it a hard requirement somehow.

I hope to see many innovative QML based window decorations in 4.9.

Posted on

What’s new in KWin Scripting?

First of all a happy and successful 2012 to everyone. Let’s work together to make this year a great success for KDE!

One of the big topics in 2012 for my development efforts in KWin will be JavaScript bindings and QML. This is a technology which will allow our users to build their own custom window manager giving even greater power to our static window rules as before. It will also reduce our maintenance need when major parts of our UI can be transitioned to either QML or JavaScript.

The work on this area has already started and the first code set has been merged into master (aka 4.9). The old scripting API had manually crafted bindings for around 30 properties for windows. Now the API is generated and everything that is available for effects is also exported to JavaScript, which means more than 60 properties, more properties than before are writable and many more signals are available. Interestingly I could drop several hundreds lines of code by exporting more properties and the code becomes cleaner and better documented. These are changes I really like 🙂

The API documentation of KWin scripting is now auto-generated through Doxygen and already imported to techbase together with detailed Update Notes on what changed. If you run master and use KWin scripting be aware that you have to adjust the script. Exactly the same API will be available in QML and also the Effects API is very close – given that the property names are inspired by the Effects API.

One of my favorite changes is that our Plasma Desktop Console is now able to execute KWin Scripts:
Plasma Desktop Console executing a KWin script

To open just use KRunner and type the new keyword “wm console” or start the desktop console and switch using the toolbar button.

This is a very important change for me during development as I can easily test whether my scripts are correct and most important my implementation. But also for users it means that scripts can be tried at runtime and don’t require a KWin restart any more. So adjusting the runtime behavior becomes possible.

So what’s next? I am currently with the progress quite satisfied with the work done so far on scripting and will now concentrate on two other areas first: getting my unmerged kickoff-qml and screenlocker branch into master. Both require still a little bit of work. After that scripting and QML get my number one priority again.