KDesktop Design Document

Author :
  David Faure, faure@kde.org
  Martin R. Jones, mjones@kde.org (screensaver)
  Geert Jansen, g.t.jansen@stud.tue.nl (background code)

Last modified: 24 Oct 1999


Overall design of KDesktop :
=============================

KDesktop is the program that handles the desktop icons,
the popup menus for the desktop, the mac menubar, and the
screensaver system.


Files :
=======

main.* : main
desktop.* : the icon container for the desktop icons
krootwm.* : right and middle mouse button popup menus, Mac menubar
bg*.*: Background renderer/manager.

icons.* : old code, not used anymore.
  We need to borrow ideas from it for positioning icons after a DnD
 (in kiconcontainer so that it works with konqueror as well)
 - well, only if we want dropped icons to remain where they have been
 dropped :)
  We also need to store the desktop icons position, like was done in kfm.
   and we need to do it for konqy as well.

KDesktopIface* : DCOP interface for kdesktop, used by kfmclient

lock* : screen saver/locker


Libs used by KDesktop
======================
 
tdecore, tdeui, tdefile  - usual stuff :)
libtdeio - I/O stuff, mimetypes, services, registry
libkonq - properties dialog, templates ("new") menu, dir lister, settings


Screensaver
===========

The screensaver now works in a similar way to xscreensaver, i.e. a driver
(kdesktop) provides the timeout, locking, and blanking functionality, but
does no actual drawing.  A separate stand-alone program capable of
drawing on a supplied window is used to do the actual fancy graphics.
xscreensaver's "hacks" will work with the KDE screensaver engine.

This makes adding new screensavers trivial, and means one less process that
must always be running (compared to KDE 1.x).

The screensaver is controlled via DCOP:

KScreensaverIface::configure()  Reloads the screensaver config from desktoprc.
KScreensaverIface::lock()       Locks the screen immediately.
KScreensaverIface::save()       Saves the screen immediately.
KScreensaverIface::isEnabled()  returns true if the screensaver is enabled.
KScreensaverIface::isBlanked()  returns true if the screen is currently blank.

Backgrounds
===========

The new background code is in bgrender.cpp and bgmanager.cpp. Some features:

* Support for xearth like programs.
* Can export a pixmap of the desktop background for pseudo transparency.


Multiple monitors
=================
Two monitors showing different things (not a mirror-setup) can be configured
in X to either use one X screen, or 2 X screens.  Difference is that if I
drag a window from one monitor to the other the application gets asked to
repaint itself on a 2 screen setup and a simple move of the window will be
done in memory (by XFree) if you have a 1 screen setup.

Monitors example:
    +----+ +-----+  2 monitors, with same resolution to keep it simple.
    |    | |     |
    +----+ +-----+

In case of 1 screen (xinerama)
    +------------+
    |            +   desktopGeometry == screenGeometry == 3200 x 1200
    +------------+

In case of 2 screen (multihead)
    +----+ +-----+
    |    | |     |  desktopGeometry = 3200 x 1200
    +----+ +-----+  screenGeometry = 1600 x 1200 (for each monitor)


Interaction between kdesktop and kdesktop_lock
==============================================
kdesktop and kdesktop_lock interact using POSIX signals to coordinate their activities.
Each time the screensaver or lock is activated and then stopped/unlocked, the current
kdesktop_lock process is terminated and respawned, while kdesktop waits for the new process
to be ready.

kdesktop to kdesktop_lock communication:
  kdesktop uses four signals to request different types of locks. These signals do not activate
  the lock/screensaver. Some of the signals can be combined together, for example to request a
  lock with blank screen.

   - USR1 : request lock of the screen
   - USR2 : request screensaver only, no lock
   - WINCH: request lock of the screen using SAK (Secure Attention Key)
   - TTIN : request blank screen for saver or lock

  The lock/screensaver is started using a fifth signal.
   - TTOU : activate the scrensaver or lock

kdesktop_lock to kdesktop communication:
  kdesktop_lock uses three signals to inform kdesktop of status changes.

   - TTIN: the lock process is ready. This is sent after the process has been created/respawned
   - USR2: the lock/screensaver has been activated
   - USR1: the lock/screensaver has been unlocked/stopped

Communication is handled by the screen saver engine defined in 'lockeng.{h,cpp}'.
The engine is split into two parts, the 'SaverEngine' running in the GUI thread and
the 'SaverEngineEventHandler' running in a separate thread and eventloop.
The 'SaverEngine' handles communication with X11, DCOP and DBUS while the
'SaverEngineEventHandler' handles communication with the actual lock process.
Several actions require cooperation of the two parts, so in various methods
there will be inter-thread calls (using timers or by emitting signals) to
trigger the other side remaining logic.
This complex design is necessary to avoid blocking the main GUI application event loop,
which has several tasks to manage and therefore can't affort to wait in a suspended state.
This was previously leading to deadlock when DCOP calls where executed on the secondary
thread/eventloop, for example when changing desktop while the lock process was restarting.