workspace/kwin/HACKING

   1 Mailing list and bugzilla:
   2 ==========================
   3
   4 The KWin mailing list is kwin@kde.org . It's rather low traffic.
   5
   6 The bugs.kde.org product for KWin is 'kwin'. Currently the components are 'general' (KWin core),
   7 'decorations' (decoration plugins), 'compatibility' (problems with non-KDE WMs/apps),
   8 'eyecandy' (transparency and similar effects), 'xinerama' (problems with Xinerama) and
   9 'multihead' (non-Xinerama multihead, without maintainer).
  10 There are also two kcontrol components 'kcmkwindecoration' and 'kcmkwinoptions' related
  11 to KWin's KControl modules.
  12
  13 KWin parts:
  14 ===========
  15
  16 There are four parts of KWin:
  17 - The KWin core, located in kdebase/kwin/*, which implements the actual functionality.
  18 - The decoration plugins, located in kdebase/kwin/clients and kdeartwork/kwin-styles, which
  19   are responsible for the visual representation of the windows.
  20 - The libkdecoration library, located in kdebase/kwin/lib/*, which is used for communication
  21   between the core and the decoration, and also implements some shared functionality
  22   for the decorations.
  23 - KControl modules, located in kdebase/kwin/kcmkwin.
  24
  25
  26 KWin decorations:
  27 =================
  28
  29 If you want to develop a decoration plugin for KWin, a HOWTO is available at
  30 http://www.usermode.org/docs/kwintheme.html . It is currently not possible to create
  31 a new decoration without knowledge of C++, but it should be possible to write a themeable
  32 decoration (I'm not aware of any such decoration though).
  33
  34
  35 Restarting KWin:
  36 ================
  37
  38 Since KWin takes care of focus handling, first killing KWin and then launching new instance
  39 can cause focus trouble. Therefore it's possible to run 'kwin --replace', which will start
  40 new KWin instance and tell the old one to quit.
  41
  42
  43 Handling the case when KWin crashes:
  44 ====================================
  45
  46 Again, without KWin running there may be focus problems. The simplest way to solve them
  47 is to add the 'Run Command' applet to Kicker - it can receive focus even without KWin running.
  48 If you can't add the applet or can reach it for some reason, switch to text console, and run
  49 'DISPLAY=:0 kwin --replace' (and then you can run 'kwin --replace' again from X).
  50
  51 If KWin is temporarily unusable because of some change and e.g. crashes during startup, it
  52 is possible to run another window manager, for example Metacity, OpenBox or FVWM (the command
  53 is similar to restarting KWin, i.e. 'metacity --replace', 'openbox --replace' or 'fvwm -replace').
  54
  55
  56 Debugging KWin:
  57 ===============
  58
  59 Focus problems once more. It is not possible to debug KWin in gdb in the X session that KWin is managing,
  60 because that'd block focus and window operations. It is necessary to switch to a text console
  61 and attach to the running KWin instance from there, or launch it as 'DISPLAY=:0 gdb kwin'.
  62
  63 Since KWin is such an important component of KDE, it is usually better to start another X for development.
  64 Note that XNest is quite buggy and is therefore not recommended to use.
  65
  66 Starting separate X for testing KWin: I myself use a separate user, login to a text console and run
  67 "( X vt10 :1 -terminate &); sleep 5; DISPLAY=:1 xterm". This launches another X with DISPLAY=:1
  68 on virtual console 10 (Ctrl+Alt+F10) with xterm. Then it's normally possible to run just KWin
  69 or whole KDE with startkde (in which case it's a good idea to disable xterm from session management
  70 in KControl->KDE components->Session manager).
  71
  72 Window manager spec:
  73 ====================
  74
  75 The EWMH window manager specification, also known as NETWM, is located at the freedesktop.org site,
  76 http://standards.freedesktop.org/wm-spec/wm-spec-latest.html . It defines how the window manager
  77 communicates information with the applications and other desktop utilities such as the taskbar
  78 or pager.
  79
  80
  81 KWin structure:
  82 ===============
  83
  84 KWin has relatively few classes. The two main classes are Client, which represents windows
  85 on the screen, and Workspace, which represents the whole screen and manages windows. Since
  86 KWin also needs to track unmanaged windows for compositing, there is a base class Toplevel
  87 for all windows, from which Client inherits, and from which also class Unmanaged inherits.
  88 These classes are rather large, because they fulfil complicated tasks. In other to reduce size
  89 of their source files these some functionality is in separate .cpp file grouped by the purpose:
  90
  91 - workspace.* - core of class Workspace
  92 - client.* - core of class Client
  93 - toplevel.* - core of the base class Toplevel
  94 - unmanaged.* - core of the class Unmanaged
  95 - activation.cpp - focus handling and window activation
  96 - composite.cpp - code related to redirecting windows to pixmaps and tracking their damage
  97 - events.cpp - event handling is in events.cpp
  98 - geometry.cpp - geometry-related code
  99 - layers.cpp - stacking-related code
 100 - manage.cpp - code dealing with new windows
 101 - placement.cpp - window placements algorithms
 102 - rules.cpp - code for window-specific settings
 103 - sm.cpp - session management code
 104 - useractions.cpp - handling of the Alt+F3 menu, shortcuts and other user actions
 105
 106 The rest of the files contain additional helper classes:
 107
 108 - atoms.* - so-called atoms (symbolic names for constants in X)
 109 - bridge.* - communication with the decoration plugin
 110 - effects.* - support for compositing effects
 111 - geometrytip.* - window displaying window geometry while moving/resizing
 112 - group.* - grouping related windows together (warning! This is currently really messy and scary code
 113   that should be rewritten).
 114 - killwindow.* - handling of the Ctrl+Esc feature
 115 - kwinbindings.cpp - KWin's keyboard shortcuts (used by kdebase/kcontrol/keys)
 116 - notifications.* - for KNotify
 117 - options.* - all configuration options for KWin are stored in this class
 118 - plugins.* - loading of the right decoration plugin
 119 - popupinfo.* - showing temporary information such as virtual desktop name when switching desktops
 120 - scene.* - base class for compositing backends, with shared functionality
 121 - scene_basic.* - a very simple testing compositing code
 122 - scene_opengl.* - compositing backed using OpenGL
 123 - scene_xrender.* - compositing backend using XRender
 124 - tabbox.* - the Alt+Tab dialog
 125 - utils.* - various small utility functions/classes
 126
 127 KWin also uses code from kdelibs, specifically files netwm.cpp, netwm.h, netwm_def.h and netwm_p.h
 128 from kdelibs/kdecore. These files implement support for the EWMH window manager specification,
 129 originally called NETWM (hence the filenames).
 130
 131
 132 Developing KWin:
 133 ================
 134
 135 So, you feel brave, huh? But KWin is not THAT difficult. Some parts, especially the X-related ones,
 136 can be very complicated, but for many parts even knowledge of X and Xlib is not necessary. Most X
 137 code is wrapped in helper functions, and I can handle problems there ;) . However, although many
 138 features don't require touching X/Xlib directly, still X/Xlib may impose their semantics on the way
 139 things are done. When in doubt, simply ask.
 140
 141 All patches for KWin core should be sent to kwin@kde.org for review first. Even seemingly harmless
 142 changes may have extensive consequences.
 143
 144 Various notes:
 145
 146 - kDebug has overloaded operator << for the Client class, so you can e.g. use 'kDebug() << this;'
 147 in class Client and it will print information about the window.
 148
 149 - KWin itself cannot create any normal windows, because it would have trouble managing its own windows.
 150 For such cases (which should be rare) a small external helper application is needed (kdialog should often
 151 do, and for special cases such a utility needs to be written like kwin/killer).
 152
 153
 154 X documentation:
 155 ================
 156
 157 As already said, many parts of KWin don't need knowledge of Xlib or even how X actually works.
 158 Some parts do, and it may be also useful to have at least a basic understand for general
 159 understanding. A reference manual for Xlib can be found e.g.
 160 at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/xlib.pdf , a tutorial explaining basic can be found
 161 e.g. at http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html
 162 (note that you don't need to know that all - e.g. GC's are very rarely needed and the
 163 section on fonts is today outdated). At http://www.sbin.org/doc/Xlib/index_contents.html can
 164 be found an Xlib programming manual (some of those are more or less obsolete these days, but
 165 there is e.g. an extensive section related to window management).
 166
 167
 168 Coding style:
 169 =============
 170
 171 There are these rules for patches for KWin:
 172
 173 - the code should be relatively nice and clean. Seriously. Rationale: Any messy code can be hard to comprehend,
 174 but if the code is in a window manager it will be twice as difficult.
 175
 176 - unless the functionality of the code is obvious, there should be either at least a short comment explaining
 177 what it does, or it should be obvious from the commit log. If there's a hack needed, if there's a potentional
 178 problem, if something is just a temporary fix, say so. Comments like "this clever trick is necessary"
 179 don't count. See above for rationale. I needed more than two years to understand all of KWin,
 180 and there were parts I never got and had to rewrite in order to fix a problem with them.
 181
 182 - indentation is 4 spaces, not tabs. Rationale: The code looks like a mess if this is not consistent.
 183
 184 - { and } enclosing a block are aligned with the block, neither with the above level nor there is any
 185 trailing { (i.e. { and } are indented in the same column like the code they surround). See above for rationale.
 186 If this feel weird or whatever, put them wherever you want first and when the changes are done, check
 187 "svn diff" and fix it. If I can handle about half a dozen different formatting styles when working
 188 on various parts of KDE, this shouldn't be that much work for you (and yes, I've even done
 189 the "fix-before-submit" thing).
 190
 191 - there is not space before (, i.e. it's "foo(", not "foo (". Rationale: This makes it simpler to grep for functions.
 192
 193 - a null pointer is NULL, not a zero. Not that I really insist on this one, but the only reason for using 0
 194 is being way too lazy to type. Rationale: NULL says it's a pointer, and with many compilers it actually is a pointer,
 195 making it possible to detect some mistakes.
 196
 197 That's all. Bonus points if you try to follow the existing coding style in general, but I don't think
 198 I really care about the rest, as long as these rules are followed. If I find out I care about more,
 199 I'll add them here.
 200
 201
 202 Branches:
 203 =========
 204
 205 In revision history, there is a commit (r251608) saying 'Merging kwin core from kwin_iii back to HEAD.' ,
 206 but SVN doesn't give any simple way to find this branch. It is in branches/kwin/kwin_iii.