About KDE and X11 session management

KDE supports the legacy X11R4 and ICCCM session
management protocols. Legacy applications that define the WM_COMMAND
property or support the WM_SAVE_YOURSELF protocol will be restarted
with the specified command. The window geometries will be restored on a best
effort basis.

Since version 2.0, KDE also supports and uses the standard X11R6
session management protocol XSMP. The official documentation of the
standard can be download from the X Consortium's FTP server
ftp.x.org. Unlike these legacy protocols, the new X11R6
session management gives a chance to save application
dependent settings when you log out. A text
editor, for instance, would save the names of the loaded files and would
reload them when you log in again. Another major advantage of the new
protocol is the support for a clean and safe logout procedure even if the
users decides not to restore the session next time. The protocol gives
applications the possibility to interact with the user in case they are in
danger to lose some data, and to cancel the shutdown process if necessary.

Further Reading

An introductive overview of session management functionality and
the Qt API for it is available from doc.trolltech.com.

Please read the respective class documentation, especially the one of
KMainWindow, for a detailed interface description. With the advanced
functionality in KMainWindow, it's really just a matter of a few lines to get even a multi-window application to retains its state between
different user sessions.

Implementing session management in your application

Here's just a brief overview how things are done. Again, see the
respective class documentation for details.

Implementing session management in KDE is easy. If your main window inherits from KMainWindow, you have just 2 things to do:

Reimplement some virtual functions of KMainWindow

KMainWindow will save its position, geometry and positions of toolbars and menubar on logout. To save additional data, reimplement saveProperties() and (to read them again on next login) readProperties(). (For a text editor, that would be the loaded files, for example.) To warn the user that the application or some windows have unsaved data on close or logout (and to give him the possibility to save them), reimplement queryClose(). These functions are called automatically by KMainWindow respectively by the session manager. Note that it is not determined if saveProperties() is called before or after queryClose()! Please read documentation of the respective functions before reimplementing them.

To save your application-wide properties (data that is only needed once per application, and not for each main window) reimplement saveGlobalProperties() and it's counterpart readGlobalProperties. Normally, you don't need these functions.

For one kind of toplevel widget

If your client has only one kind of toplevel widgets (which should be pretty usual) then you should use the RESTORE-macro.

Imagine you have an
application with a main window MyWindow inherited from
KMainWindow (or from
KXmlGuiWindow, which inherits from
KMainWindow). In your main() function, you would then create/restore the
application windows with something like:

KApplication app;
if ( app.isSessionRestored() ) {

RESTORE( MyWindow )

} else {

// create default application as usual
// for example:
MyWindow* window = new MyWindow();
// # will be replaced with numbers that are guaranteed
// to be unique in the application:
window->setObjectName("MainWindow#");
window->show();

}
return app.exec();

RESTORE will create as many instances of MyWindow as have existed in the last session. Note that QWidget::show() is called.

With this you can easily restore all toplevel windows of your application.

For several kinds of toplevel widgets

It is also possible to
restore different types of toplevel windows within one application. In
that case, the RESTORE macro is too primitive. If you have more than one
kind of toplevel widget (each derived from KMainWindow, of course), you
can use the templated kRestoreMainWindows() global functions:

Internals

Appendix: Architecture of the KDE session manager

The session management server in KDE is called ksmserver and it is
part of the kdebase package. The server interacts with the KDE window
manager kwin to save and restore the window geometries and to perform
legacy session management. To make session management work, ksmserver
has to be started as last process of the X login procedure. This happens
automatically at the end of the startkde script.