KWin 5 with ICC color correction effect
 
 
 
 
 
 
Go to file
Martin Gräßlin f48aca47a5 [kwin] Use ui-file for ShortcutDialog
At the same time switching to QKeySequenceEdit for capturing the
shortcut. This allows to get rid of xmlgui.
2014-02-27 10:18:37 +01:00
autotests [kwin] Use imported targets for all XCB libs 2014-02-25 15:48:39 +01:00
clients [kwin] Use imported targets for all XCB libs 2014-02-25 15:48:39 +01:00
data kde4support-- 2014-01-21 03:12:41 +05:30
effects [kwin] Use imported targets for all XCB libs 2014-02-25 15:48:39 +01:00
kcmkwin [kwin] Use imported targets for all XCB libs 2014-02-25 15:48:39 +01:00
killer Port to KF5 renaming changes 2013-12-11 21:41:47 +01:00
libkdecorations Replace NULL with nullptr in libkdecorations folder 2014-02-24 16:47:48 +01:00
libkwineffects [kwin] Use imported targets for all XCB libs 2014-02-25 15:48:39 +01:00
scripting [kwin] Remove dependency on KF5Declarative 2014-02-26 08:30:52 +01:00
scripts SVN_SILENT made messages (.desktop file) 2014-02-18 05:12:30 +00:00
shaders kwin: Add GLSL 1.40 versions of the scene shaders 2013-05-08 18:33:03 +02:00
tabbox Replace NULL with nullptr in tabbox folder 2014-02-24 16:42:43 +01:00
tests Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
CMakeLists.txt [kwin] Use ui-file for ShortcutDialog 2014-02-27 10:18:37 +01:00
COMPLIANCE Removing TopMenu 2011-06-24 12:27:56 +02:00
CONFIGURING Merging from old trunk: 2007-04-29 21:41:03 +00:00
ExtraDesktop.sh Add ExtraDestkop.sh files 2011-07-12 16:46:09 +01:00
HACKING HACKING moves to community.kde.org 2011-02-19 17:17:03 +01:00
Mainpage.dox Apidocs mainpage work. Just got Plasma and Solid to do here. 2007-07-24 18:30:36 +00:00
Messages.sh Improve message extraction 2011-02-20 16:02:33 +01:00
README Add a link to the techbase KWin page, which should be where all other docs and links are referenced. 2008-11-05 19:57:33 +00:00
activation.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
activities.cpp [kwin] Do not use camelcase includes for kactivities 2014-02-04 09:36:15 +01:00
activities.h Fix no cast to/from ASCII intrduced issues 2013-07-24 09:58:33 +02:00
appmenu.cpp [kwin] Generate dbus interface for Appmenu 2014-01-07 14:06:56 +01:00
appmenu.h [kwin] Generate dbus interface for Appmenu 2014-01-07 14:06:56 +01:00
atoms.cpp Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
atoms.h Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
bridge.cpp [kwin] Use a QIcon in Client for the icons instead of Pixmaps 2013-12-06 14:41:23 +01:00
bridge.h [kdecorations] Add a ::palette() to the decoration API 2013-11-25 09:44:23 +01:00
client.cpp Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
client.h Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
client_machine.cpp And we got rid of KDebug 2013-09-02 13:14:39 +02:00
client_machine.h Improved resolving whether a window is on local machine 2013-01-21 16:00:49 +01:00
composite.cpp Enforce compositing if required 2014-01-09 15:16:42 +01:00
composite.h Support frame callback in Wayland backend 2014-01-08 09:22:40 +01:00
compositingprefs.cpp Introduce a method shouldUseWaylandForCompositing() in KWin::Application 2014-01-09 15:16:42 +01:00
compositingprefs.h [kwin] Drop testapp for detecting whether direct rendering works on glx 2013-11-05 14:48:40 +01:00
config-kwin.h.cmake Adding version information to supportInformation 2013-01-11 08:49:25 +01:00
cursor.cpp Correctly detect mouseChanged between polls. 2013-09-04 14:39:44 +02:00
cursor.h Use Q_SLOTS and Q_SIGNALS instead of slots and signals 2013-07-24 09:46:54 +02:00
dbusinterface.cpp Remove deprecated methods in DBusInterface 2013-07-29 08:47:33 +02:00
dbusinterface.h Remove deprecated methods in DBusInterface 2013-07-29 08:47:33 +02:00
decorations.cpp Introduce a compositingChanged signal in KDecorationOptions 2013-09-12 09:27:38 +02:00
decorations.h Introduce a compositingChanged signal in KDecorationOptions 2013-09-12 09:27:38 +02:00
deleted.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
deleted.h Toplevel::frameId() becomes virtual 2013-09-10 15:30:10 +02:00
effects.cpp Keep KWin responsive while loading all effects 2014-01-28 07:41:57 +01:00
effects.h Keep KWin responsive while loading all effects 2014-01-28 07:41:57 +01:00
egl_wayland_backend.cpp [kwin] Drop unused includes to KDebug 2014-02-03 11:36:46 +01:00
egl_wayland_backend.h A Scene doesn't need to use an X11 Overlay Window 2014-01-08 09:22:40 +01:00
eglonxbackend.cpp Merge branch 'KDE/4.11' 2014-01-29 20:28:27 +01:00
eglonxbackend.h A Scene doesn't need to use an X11 Overlay Window 2014-01-08 09:22:40 +01:00
events.cpp Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
focuschain.cpp make minimized windows first of minimized 2013-05-22 22:24:35 +02:00
focuschain.h Use Q_SLOTS and Q_SIGNALS instead of slots and signals 2013-07-24 09:46:54 +02:00
geometry.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
geometrytip.cpp Remove dead code path from GeometryTip 2013-05-03 08:20:28 +02:00
geometrytip.h Remove dead code path from GeometryTip 2013-05-03 08:20:28 +02:00
glxbackend.cpp Merge branch 'KDE/4.11' 2014-01-29 20:28:27 +01:00
glxbackend.h A Scene doesn't need to use an X11 Overlay Window 2014-01-08 09:22:40 +01:00
group.cpp [kwin] Use a QIcon in Client for the icons instead of Pixmaps 2013-12-06 14:41:23 +01:00
group.h [kwin] Use a QIcon in Client for the icons instead of Pixmaps 2013-12-06 14:41:23 +01:00
killwindow.cpp Better activation check in KillWindow 2013-08-06 14:44:02 +02:00
killwindow.h Move killWindowId(Window) from Workspace to KillWindow 2013-04-15 10:09:04 +02:00
kwin.kcfg Remove labels from TabBox section in kcfg 2013-06-06 08:11:02 +02:00
kwin.notifyrc SVN_SILENT made messages (.desktop file) 2014-02-18 05:12:30 +00:00
kwinbindings.cpp [kwin] Do not use a KActionCollection for Workspace's global shortcut actions 2013-12-10 10:01:13 +01:00
lanczosfilter.cpp Do not check graphicsEffectsLevel for LanczosFilter 2013-09-09 06:03:35 +02:00
lanczosfilter.h Do not use stackingOrder in LanczosFilter to get all EffectWindows 2013-04-11 12:57:53 +02:00
layers.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
main.cpp Use KDE4WORKSPACE_VERSION as base for kwin's version number 2014-01-13 19:54:26 +01:00
main.h Enforce compositing if required 2014-01-09 15:16:42 +01:00
manage.cpp Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
netinfo.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
netinfo.h Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
options.cpp New QPainter based compositor called SceneQPainter 2014-01-09 13:29:40 +01:00
options.h Enforce compositing if required 2014-01-09 15:16:42 +01:00
org.kde.KWin.xml Remove deprecated methods in DBusInterface 2013-07-29 08:47:33 +02:00
org.kde.kwin.Compositing.xml Introduce dedicated suspend and resume methods on Compositing interface 2012-09-06 09:59:20 +02:00
org.kde.kwin.Effects.xml add effect debug interface and dbus export 2013-03-28 20:31:02 +01:00
outline.cpp Fix no cast to/from ASCII intrduced issues 2013-07-24 09:58:33 +02:00
outline.h Move ShortcutDialog to useractions 2013-04-26 08:53:13 +02:00
overlaywindow.cpp Strip module path from all Qt #include <> 2013-03-06 10:26:56 +01:00
overlaywindow.h Port OverlayWindow from XLib to XCB 2012-12-20 16:30:39 +01:00
ox16-app-kwin.png Optimize PNG files again. 2008-01-02 00:10:07 +00:00
ox32-app-kwin.png Optimize PNG files again. 2008-01-02 00:10:07 +00:00
ox48-app-kwin.png Optimize PNG files again. 2008-01-02 00:10:07 +00:00
oxsc-app-kwin.svgz remove crystal, remove with mono icons until oxygen icons get made 2007-11-20 16:47:36 +00:00
paintredirector.cpp New QPainter based compositor called SceneQPainter 2014-01-09 13:29:40 +01:00
paintredirector.h New QPainter based compositor called SceneQPainter 2014-01-09 13:29:40 +01:00
placement.cpp [kwin] Make KWin place the OSD 2014-02-12 10:53:10 +01:00
placement.h [kwin] Make KWin place the OSD 2014-02-12 10:53:10 +01:00
resources.qrc kwin: Add GLSL 1.40 versions of the scene shaders 2013-05-08 18:33:03 +02:00
rules.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
rules.h Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
scene.cpp Allow windows to specify that they should not get animated on window close 2014-01-28 09:01:55 +01:00
scene.h A Scene doesn't need to use an X11 Overlay Window 2014-01-08 09:22:40 +01:00
scene_opengl.cpp Merge branch 'KDE/4.11' 2014-01-28 08:18:41 +01:00
scene_opengl.h A Scene doesn't need to use an X11 Overlay Window 2014-01-08 09:22:40 +01:00
scene_qpainter.cpp Introduce a method shouldUseWaylandForCompositing() in KWin::Application 2014-01-09 15:16:42 +01:00
scene_qpainter.h New QPainter based compositor called SceneQPainter 2014-01-09 13:29:40 +01:00
scene_xrender.cpp Introduce a method shouldUseWaylandForCompositing() in KWin::Application 2014-01-09 15:16:42 +01:00
scene_xrender.h Wayland backend for the XRender scene 2014-01-08 09:22:40 +01:00
screenedge.cpp Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
screenedge.h Screenedge show support for Clients 2014-02-26 12:54:00 +01:00
screens.cpp [kwin] Introduce a currentChanged signal in screens 2013-12-12 09:37:29 +01:00
screens.h [kwin] Introduce a currentChanged signal in screens 2013-12-12 09:37:29 +01:00
settings.kcfgc Use KConfigXT in KWin::Options 2013-02-14 08:29:03 +01:00
shadow.cpp Pass creation of Shadow sub class instance to Scene 2014-01-07 15:34:19 +01:00
shadow.h Port reading the shadow property to XCB 2013-09-11 08:21:44 +02:00
shortcutdialog.ui [kwin] Use ui-file for ShortcutDialog 2014-02-27 10:18:37 +01:00
sm.cpp Merge branch 'KDE/4.11' 2014-01-29 20:28:27 +01:00
sm.h Do not build KWin::SessionManager for the time being 2013-09-09 06:03:35 +02:00
tabgroup.cpp [kwin] Use a QIcon in Client for the icons instead of Pixmaps 2013-12-06 14:41:23 +01:00
tabgroup.h Use Q_SLOTS and Q_SIGNALS instead of slots and signals 2013-07-24 09:46:54 +02:00
thumbnailitem.cpp [kwin] Use a QIcon in Client for the icons instead of Pixmaps 2013-12-06 14:41:23 +01:00
thumbnailitem.h Remove parent window id from ThumbnailItem 2013-08-13 09:57:51 +02:00
toplevel.cpp Allow windows to specify that they should not get animated on window close 2014-01-28 09:01:55 +01:00
toplevel.h Allow windows to specify that they should not get animated on window close 2014-01-28 09:01:55 +01:00
unmanaged.cpp Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
unmanaged.h Enable configure notify event handling in Unmanaged 2013-07-29 09:00:43 +02:00
useractions.cpp [kwin] Use ui-file for ShortcutDialog 2014-02-27 10:18:37 +01:00
useractions.h [kwin] Use ui-file for ShortcutDialog 2014-02-27 10:18:37 +01:00
utils.cpp Merge branch 'KDE/4.11' 2014-01-29 20:28:27 +01:00
utils.h Adjust kde-workspace to introduction of flags in NET classes 2014-02-05 17:40:19 +01:00
virtualdesktops.cpp [kwin] Do not use KActionCollection in VirtualDesktops 2013-12-10 09:11:16 +01:00
virtualdesktops.h [kwin] Do not use KActionCollection in VirtualDesktops 2013-12-10 09:11:16 +01:00
wayland_backend.cpp Introduce an OperationMode enum 2014-01-09 15:16:33 +01:00
wayland_backend.h Better re-using of Wayland::Buffer 2014-01-08 09:22:40 +01:00
workspace.cpp Port away from KWindowSystem::windowInfo 2014-02-12 18:23:29 +01:00
workspace.h [kwin] Drop handling for mouse motion event compression 2014-02-01 09:34:40 +01:00
xcbutils.cpp Provide pixmap format in XShm helper 2014-01-08 09:22:40 +01:00
xcbutils.h Provide pixmap format in XShm helper 2014-01-08 09:22:40 +01:00

README

- A collection of various documents and links related to KWin is at http://techbase.kde.org/Projects/KWin .


- The mailing list for KWin is kwin@kde.org (https://mail.kde.org/mailman/listinfo/kwin).

- If you want to develop KWin, see file HACKING.

- If you want to check KWin's compliance with specifications, see file COMPLIANCE.

- File CONFIGURATION includes some details on configuring KWin.

- Below is some info for application developers about application interaction
  with the window manager, but it'd need some cleanup.








 This README is meant as an explanation of various window manager related
mechanisms that application developers need to be aware of. As some of these
concepts may be difficult to understand for people not having the required
background knowledge (since sometimes it's difficult even for people who
do have the knowledge), the mechanisms are first briefly explained, and
then an example of fixing the various problems is given.

 For comments, questions, suggestions and whatever use the kwin@kde.org
mailing list.


Table of contents:
==================

- Window relations
    - how to make the window manager know which windows belong together
- Focus stealing prevention
    - how to solve cases where focus stealing prevention doesn't work
      properly automatically



Window relations:
=================

(For now, this explanation of window relations is mainly meant for
focus stealing prevention. To be extended later.)

 All windows created by an application should be organized in a tree
with the root being the application's main window. Note that this is about
toplevel windows, not widgets inside the windows. For example, if you
have KWrite running, with a torn-off toolbar (i.e. a standalone toolbar),
a file save dialog open, and the file save dialog showing a dialog
for creating a directory, the window hiearchy should look like this:


             KWrite mainwindow
              /             \
             /               \
      file save dialog      torn-off toolbar
            \
             \
          create directory dialog

 Each subwindow (i.e. all except for the KWrite mainwindow) points to its
main window (which in turn may have another main window, as in the case
of the file save dialog). When the window manager knows these relations,
it can better arrange the windows (keeping subwindows above their
main windows, preventing activation of a main window of a modal dialog,
and similar). Failing to provide this information to the window manager
may have various results, for example having dialogs positioned below
the main window,

The window property used by subwindows to point to their mainwindows is
called WM_TRANSIENT_FOR. It can be seen by running
'xprop | grep WM_TRANSIENT_FOR' and clicking on a window. If the property
is not present, the window does not (claim to) have any mainwindow.
If the property is present, it's value is the window id of its main window;
window id of any window can be found out by running 'xwininfo'. A window
having WM_TRANSIENT_FOR poiting to another window is said to be transient
for that window.

 In some cases, the WM_TRANSIENT_FOR property may not point to any other
existing window, having value of 0, or pointing to the screen number
('xwininfo -root'). These special values mean that the window is transient
for all other windows in its window group. This should be used only
in rare cases, everytime a specific main window is known, WM_TRANSIENT_FOR
should be pointing to it instead of using one of these special values.
(The explanation why is beyond the scope of this document - just accept it
as a fact.)

 With Qt, the WM_TRANSIENT_FOR property is set by Qt automatically, based
on the toplevel widget's parent. If the toplevel widget is of a normal
type (i.e. not a dialog, toolbar, etc.), Qt doesn't set WM_TRANSIENT_FOR
on it. For special widgets, such as dialogs, WM_TRANSIENT_FOR is set
to point to the widget's parent, if it has a specific parent, otherwise
WM_TRANSIENT_FOR points to the root window.

 As already said above, WM_TRANSIENT_FOR poiting to the root window should
be usually avoided, so everytime the widget's main widget is known, the widget
should get it passed as a parent in its constructor.
(TODO KDialog etc. classes should not have a default argument for the parent
argument, and comments like 'just pass 0 as the parent' should go.)



Focus stealing prevention:
==========================

 Since KDE3.2 KWin has a feature called focus stealing prevention. As the name
suggests, it prevents unexpected changes of focus. With older versions of KWin,
if any application opened a new dialog, it became active, and
if the application's main window was on another virtual desktop, also
the virtual desktop was changed. This was annoying, and also sometimes led
to dialogs mistakenly being closed because they received keyboard input that
was meant for the previously active window.

 The basic principle of focus stealing prevention is that the window with most
recent user activity wins. Any window of an application will become active
when being shown only if this application was the most recently used one.
KWin itself, and some of the related kdecore classes should take care
of the common cases, so usually there's no need for any special handling
in applications. Qt/KDE applications, that is. Applications using other
toolkits should in most cases work fine too. If they don't support
the window property _NET_WM_USER_TIME, the window manager may fail to detect
the user timestamp properly, resulting either in other windows becoming active
while the user works with this application, or this application may sometimes
steal focus (this second case should be very rare though).

 There are also cases where KDE applications needs special handling. The two
most common cases are when windows relations are not setup properly to make
KWin realize that they belong to the same application, and when the user
activity is not represented by manipulating with the application windows
themselves.

 Also note that focus stealing prevention implemented in the window manager
can only help with focus stealing between different applications.
If an application itself suddenly pops up a dialog, KWin cannot do anything about
it, and its the application's job to handle this case.


Window relations:
-----------------

 The common case here is when a dialog is shown for an application, but this
dialog is not provided by the application itself, but by some other process.
For example, dialogs with warnings about accepted cookies are provided
by KCookieJar, instead of being shown by Konqueror. In the normal case,
from KWin's point of view the cookie dialog would be an attempt of another
application to show a dialog, and KWin wouldn't allow activation of this
window.

 The solution is to tell the window manager about the relation between
the Konqueror main window and the cookie dialog, by making the dialog
point to the mainwindow. Note that this is not special to focus stealing
prevention, subwindows such as dialogs, toolbars and similar should always
point to their mainwindow. See the section on window relations for full
description.

 The WM_TRANSIENT_FOR property that's set on dialogs to point to their
mainwindow should in the cookie dialog case point to the Konqueror window
for which it has been shown. This is solved in kcookiejar by including
the window id in the DCOP call. When the cookie dialog is shown, its
WM_TRANSIENT_FOR property is manually set using the XSetTransientForHint()
call (see kdelibs/kioslave/http/kcookiejar/kcookiewin.cpp). The arguments
to XSetTransientForHint() call are the X display (i.e. QX11Info::display()),
the window id on which the WM_TRANSIENT_FOR property is to be set
(i.e. use QWidget::winId()), and the window id of the mainwindow.


  Simple short HOWTO:
  
 To put it simply: Let's say you have a daemon application that has
DCOP call "showDialog( QString text )", and when this is called, it shows
a dialog with the given text. This won't work properly with focus stealing
prevention. The DCOP call should be changed to
"showDialog( QString text, long id )". The caller should pass something like
myMainWindow->winId() as the second argument. In the daemon, before
the dialog is shown, a call to XSetTransientHint() should be added:

 XSetTransientForHint( QX11Info::display(), dialog->winId(), id_of_mainwindow );
 
 That's it.

Non-standard user activity:
---------------------------

 The most common case in KDE will be DCOP calls. For example, KDesktop's DCOP
call "KDesktopIface popupExecuteCommand". Executing this DCOP call e.g.
from Konsole as 'dcop kdesktop KDesktopIface popupExecuteCommand" will lead
to showing the minicli, but the last user activity timestamp gained from events
sent by X server will be older than user activity timestamp of Konsole, and
would normally result in minicli not being active. Therefore, before showing
the minicli, kdesktop needs to call KApplication::updateUserTimestamp().

 However, this shouldn't be done with all DCOP calls. If a DCOP call is not
a result of direct user action, calling KApplication::updateUserTimestamp()
would lead to focus stealing. For example, let's assume for a moment
that KMail would use this DCOP call in case it detects the modem is not
connected, allowing to you to start KPPP or whatever tool you use. If KMail
would be configured to check mail every 10 minutes, this would lead to minicli
possibly suddenly showing up at every check. Basically, doing the above change
to kdesktop's minicli means that the popupExecuteCommand() DCOP call is only
for user scripting. (TODO write about focus transferring?)

 Simply said, KApplication::updateUserTimestamp() should be called only
as a result of user action. Unfortunately, I'm not aware of any universal
way how to handle this, so every case will have to be considered separately.