tdebase/twin/HACKING

Mailing list and bugzilla:
==========================

The KWin mailing list is twin@kde.org . It's rather low traffic.

The bugs.kde.org product for KWin is 'twin'. Currently the components are 'general' (KWin core),
'decorations' (decoration plugins), 'compatibility' (problems with non-KDE WMs/apps) and
'eyecandy' (transparency and similar effects).
There are also two kcontrol components 'kcmtwindecoration' and 'kcmtwinoptions' related
to KWin's KControl modules.


KWin parts:
===========

There are four parts of KWin:
- The KWin core, located in kdebase/twin/*, which implements the actual functionality.
- The decoration plugins, located in kdebase/twin/clients and kdeartwork/twin-styles, which
  are responsible for the visual representation of the windows.
- The libkdecoration library, located in kdebase/twin/lib/*, which is used for communication
  between the core and the decoration, and also implements some shared functionality
  for the decorations.
- KControl modules, located in kdebase/twin/kcmtwin.


KWin decorations:
=================

If you want to develop a decoration plugin for KWin, a HOWTO is available at
http://www.usermode.org/docs/twintheme.html . It is currently not possible to create
a new decoration without knowledge of C++, but it should be possible to write a themeable
decoration (I'm not aware of any such decoration though).


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 'twin --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. The simplest way to solve them
is to add the 'Run Command' applet to Kicker - it can receive focus even without KWin running.
If you can't add the applet or can reach it for some reason, switch to text console, and run
'DISPLAY=:0 twin --replace' (and then you can run 'twin --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, OpenBox or FVWM (the command
is similar to restarting KWin, i.e. 'metacity --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 twin'.

Since KWin is such an important component of KDE, it is usually better to start another X for development.
Note that XNest is quite buggy and is therefore not recommended to use.


Window manager spec:
====================

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


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. Both these
classes are rather large, because they fulfil 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
- activation.cpp - focus handling and window activation
- 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
- 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
- twinbindings.cpp - KWin's keyboard shortcuts (used by kdebase/kcontrol/keys)
- notifications.* - for KNotify
- options.* - all configuration options for KWin are stored in this class
- plugins.* - loading of the right decoration plugin
- popupinfo.* - showing temporary information such as virtual desktop name when switching desktops
- 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/tdecore. These files implement support for the EWMH window manager specification,
originally called NETWM (hence the filenames).


Developing KWin:
================

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, and I can handle problems there ;) . 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 core should be sent to twin@kde.org for review first. Even seemingly harmless
changes may have extensive consequences.

Various notes:

- kdDebug has overloaded operator << for the Client class, so you can e.g. use 'kdDebug() << this << endl;'
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 twin/killer).


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 ttp://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).


Coding style:
=============

There are only three rules for patches for KWin:

- the code should be relatively nice and clean. Seriously. Any messy code can be hard to comprehend,
but if the code is in a window manager it will be twice as difficult.

- unless the functionality of the code is obvious, there should be either at least a short comment explaining
what it does, or it should be obvious from the commit log. If there's a hack needed, if there's a potentional
problem, if something is just a temporary fix, say so. Comments like "this clever trick is necessary"
don't count. See rule #1 above for reasons. I needed more than two years to understand all of KWin,
and there were parts I never got and had to rewrite in order to fix a problem with them.

- put matching opening { and closing } in the same column. That's the only formatting rule I ask for.
I don't really care if they're aligned with the block one level higher or if they're aligned with the block
they surround like I do (which is the only thing about the "weird coding style in KWin") or if you align them
with something else, just put them in the same column. If I can handle about half a dozen different formatting
styles when working on various parts of KDE, this shouldn't be much work for you (and you can do that only
right before sending the patch). I don't care where you do and don't put spaces or what exactly you call local
variables, as long as I can read it (trying to make it look like the rest of the code is bonus points though ;) ).


twin@kde.org