kwin/HACKING

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

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

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

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

There are four parts of KWin:
- The KWin core, located in kdebase/kwin/*, which implements the actual functionality.
- The decoration plugins, located in kdebase/kwin/clients and kdeartwork/kwin-styles, which
  are responsible for the visual representation of the windows.
- The libkdecoration library, located in kdebase/kwin/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/kwin/kcmkwin.


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

If you want to develop a decoration plugin for KWin, a HOWTO is available at
http://www.usermode.org/docs/kwintheme.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 '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. 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 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, 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 kwin'.

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.

Starting separate X for testing KWin: I myself 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://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. 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.
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
- 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
- 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
- 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
- scene.* - base class for compositing backends, with shared functionality
- scene_basic.* - a very simple testing compositing code
- scene_opengl.* - compositing backed using OpenGL
- 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).


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 kwin@kde.org 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).


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).


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

There are these rules for patches for KWin:

- the code should be relatively nice and clean. Seriously. Rationale: 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 above for rationale. 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.

- indentation is 4 spaces, not tabs. Rationale: The code looks like a mess if this is not consistent.

- { and } enclosing a block are aligned with the block, neither with the above level nor there is any
trailing { (i.e. { and } are indented in the same column like the code they surround). See above for rationale.
If this feel weird or whatever, put them wherever you want first and when the changes are done, check
"svn diff" and fix it. If I can handle about half a dozen different formatting styles when working
on various parts of KDE, this shouldn't be that much work for you (and yes, I've even done
the "fix-before-submit" thing).

- there is not space before (, i.e. it's "foo(", not "foo (". Rationale: This makes it simpler to grep for functions.

- a null pointer is NULL, not a zero. Not that I really insist on this one, but the only reason for using 0
is being way too lazy to type. Rationale: NULL says it's a pointer, and with many compilers it actually is a pointer,
making it possible to detect some mistakes.

That's all. Bonus points if you try to follow the existing coding style in general, but I don't think
I really care about the rest, as long as these rules are followed. If I find out I care about more,
I'll add them here.


Branches:
=========

In revision history, there is a commit (r251608) saying 'Merging kwin core from kwin_iii back to HEAD.' ,
but SVN doesn't give any simple way to find this branch. It is in branches/kwin/kwin_iii.