HACKING moves to community.kde.org
This commit is contained in:
Martin Gräßlin
parent
f970eab391
commit
9d9bd615fc
1 changed files with 4 additions and 179 deletions
183
HACKING
183
HACKING
|
|
@ -1,180 +1,5 @@
|
|||
Mailing list and bugzilla:
|
||||
==========================
|
||||
Developer documentation can be found in the KDE Community Wiki:
|
||||
|
||||
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://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.
|
||||
|
||||
|
||||
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:
|
||||
=============
|
||||
|
||||
KWin follows the kdelibs coding style. See: http://techbase.kde.org/Policies/Kdelibs_Coding_Style
|
||||
|
||||
The source repository was reformatted with git commit 4fd08556a1702462335f4f1307da663c2c54b2c2
|
||||
|
||||
|
||||
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.
|
||||
* http://community.kde.org/KWin - KWin start page
|
||||
* http://community.kde.org/KWin/Hacking - Hacking information
|
||||
* http://community.kde.org/KWin/Class_Diagram - Class Diagram
|
||||
|
|
|
|||
Loading…
Reference in a new issue