< KWin
Revision as of 16:12, 19 February 2011 by Mgraesslin (talk | contribs) (Initial Import of HACKING page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)



Mailing list

The KWin mailing list is [email protected]. It's rather low traffic.


The bugs.kde.org product for KWin is 'kwin'. Information about the various components and the priority system is documented on KWin/Bugzilla.

KWin parts

KWin consists of several parts:

  • The KWin core, located in kde-worksapce/kwin/*, which implements the actual functionality.
  • The decoration plugins, located in kde-worksapce/kwin/clients and kdeartwork/kwin-styles, which are responsible for the visual representation of the windows.
  • The effects plugins, located in kde-worksapce/kwin/effects, which are responsible for compositing effects
  • The libkdecorations library, located in kde-worksapce/kwin/libkdecorations/*, which is used for communication between the core and the decoration, and also implements some shared functionality for the decorations.
  • The libkwineffects library, located in kde-worksapce/kwin/libkdecorations/*, which is used for communication between the core and the effects and also implements some shared functionality for the effects and the compositor.
  • KControl modules, located in kde-worksapce/kwin/kcmkwin.

KWin structure

KWin has relatively few classes. The two main classes are Client, which represents windows on the screen, and Workspace, which represents the whole screen and manages windows. Since KWin also needs to track unmanaged windows for compositing, there is a base class Toplevel for all windows, from which Client inherits, and from which also class Unmanaged inherits. A third inheriting class Deleted keeps a copy of the window pixmap for animation when a window is closed. These classes are rather large, because they fulfill complicated tasks. In other to reduce size of their source files these some functionality is in separate .cpp file grouped by the purpose:

  • workspace.* - core of class Workspace
  • client.* - core of class Client
  • deleted.* - core of class Deleted
  • toplevel.* - core of the base class Toplevel
  • unmanaged.* - core of the class Unmanaged
  • activation.cpp - focus handling and window activation
  • composite.cpp - code related to redirecting windows to pixmaps and tracking their damage
  • events.cpp - event handling is in events.cpp
  • geometry.cpp - geometry-related code
  • layers.cpp - stacking-related code
  • manage.cpp - code dealing with new windows
  • placement.cpp - window placements algorithms
  • rules.cpp - code for window-specific settings
  • sm.cpp - session management code
  • useractions.cpp - handling of the Alt+F3 menu, shortcuts and other user actions

The rest of the files contain additional helper classes:

  • atoms.* - so-called atoms (symbolic names for constants in X)
  • bridge.* - communication with the decoration plugin
  • effects.* - support for compositing effects
  • desktopchangeosd.* - showing temporary information such as virtual desktop name when switching desktops
  • geometrytip.* - window displaying window geometry while moving/resizing
  • group.* - grouping related windows together (warning! This is currently really messy and scary code that should be rewritten).
  • killwindow.* - handling of the Ctrl+Esc feature
  • kwinbindings.cpp - KWin's keyboard shortcuts (used by kdebase/kcontrol/keys)
  • notifications.* - for KNotify
  • lanczosfilter.* - Lanczos Filter for improved OpenGL based thumbnail rendering
  • options.* - all configuration options for KWin are stored in this class
  • paintredierctor.* - Redirects painting of decoration widget into a pixmap
  • plugins.* - loading of the right decoration plugin
  • scene.* - base class for compositing backends, with shared functionality
  • scene_basic.* - a very simple testing compositing code
  • scene_opengl.* - compositing backed using OpenGL
  • scene_opengl_egl.cpp - egl specific part of OpenGL compositing backend
  • scene_opengl_glx.cpp - glx specific part of OpenGL compositing backend
  • scene_xrender.* - compositing backend using XRender
  • tabbox.* - the Alt+Tab dialog
  • utils.* - various small utility functions/classes

KWin also uses code from kdelibs, specifically files netwm.cpp, netwm.h, netwm_def.h and netwm_p.h from kdelibs/kdecore. These files implement support for the EWMH window manager specification, originally called NETWM (hence the filenames).

KWin Decorations

If you want to develop a decoration plugin for KWin, you can use follow this HOWTO. The HOWTO does not include the latest changes in KDE 4. These plugins have to be written in C++.

If you prefer designing a theme, you can use Aurorae (shipped with KWin), deKorator or Smaragd. For Aurorae there is a tutorial on techbase and it is recommended to use AuroraeDesigner.

Developing KWin

Restarting KWin

Since KWin takes care of focus handling, first killing KWin and then launching new instance can cause focus trouble. Therefore it's possible to run 'kwin --replace', which will start new KWin instance and tell the old one to quit.

Handling the case when KWin crashes

Again, without KWin running there may be focus problems. To restart KWin when not being able to focus KRunner or a Konsole switch to text console, and run 'DISPLAY=:0 kwin --replace' (and then you can run 'kwin --replace' again from X).

If KWin is temporarily unusable because of some change and e.g. crashes during startup, it is possible to run another window manager, for example Metacity, Compiz, OpenBox or FVWM (the command is similar to restarting KWin, i.e. 'metacity --replace', 'compiz --replace', 'openbox --replace' or 'fvwm -replace').

Debugging KWin

Focus problems once more. It is not possible to debug KWin in gdb in the X session that KWin is managing, because that'd block focus and window operations. It is necessary to switch to a text console and attach to the running KWin instance from there, or launch it as 'DISPLAY=:0 gdb kwin'.

Since KWin is such an important component of KDE, it is usually better to start another X for development.

Starting separate X for testing KWin: use a separate user, login to a text console and run "( X vt10 :1 -terminate &); sleep 5; DISPLAY=:1 xterm". This launches another X with DISPLAY=:1 on virtual console 10 (Ctrl+Alt+F10) with xterm. Then it's normally possible to run just KWin or whole KDE with startkde (in which case it's a good idea to disable xterm from session management in KControl->KDE components->Session manager).

Window manager spec

The EWMH window manager specification, also known as NETWM, is located at the freedesktop.org site, http://standards.freedesktop.org/wm-spec/wm-spec-latest.html. It defines how the window manager communicates information with the applications and other desktop utilities such as the taskbar or pager.


So, you feel brave, huh? But KWin is not THAT difficult. Some parts, especially the X-related ones, can be very complicated, but for many parts even knowledge of X and Xlib is not necessary. Most X code is wrapped in helper functions. However, although many features don't require touching X/Xlib directly, still X/Xlib may impose their semantics on the way things are done. When in doubt, simply ask.

All patches for KWin should be sent to ReviewBoard for review first. Even seemingly harmless changes may have extensive consequences.

Various notes:

  • kDebug has overloaded operator << for the Client class, so you can e.g. use 'kDebug() << this;'

in class Client and it will print information about the window.

  • KWin itself cannot create any normal windows, because it would have trouble managing its own windows. For such cases (which should be rare) a small external helper application is needed (kdialog should often do, and for special cases such a utility needs to be written like kwin/killer).

Coding style

KWin follows the kdelibs coding style.

The source repository was reformatted with git commit 4fd08556.


X documentation

As already said, many parts of KWin don't need knowledge of Xlib or even how X actually works. Some parts do, and it may be also useful to have at least a basic understand for general understanding. A reference manual for Xlib can be found e.g. at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/xlib.pdf , a tutorial explaining basic can be found e.g. at http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html (note that you don't need to know that all - e.g. GC's are very rarely needed and the section on fonts is today outdated). At http://www.sbin.org/doc/Xlib/index_contents.html can be found an Xlib programming manual (some of those are more or less obsolete these days, but there is e.g. an extensive section related to window management).

Content is available under Creative Commons License SA 4.0 unless otherwise noted.