Question

Definitions

A session is a group of applications running, each of which has a
particular state. The session is controlled by a service called the session manager. The applications participating in the session are
called session clients.

The session manager issues commands to its clients on behalf of the
user. These commands may cause clients to commit unsaved changes (for
example by saving open files), to preserve their state for future
sessions or to terminate gracefully. The set of these operations is
called session management.

In the common case, a session consists of all applications that a
user runs on their desktop at a time. Under Unix/X11, however, a
session may include applications running on different computers and
may span multiple displays.

Shutting a session down

A session is shut down by the session manager, usually on behalf of
the user when they want to log out. A system might also
perform an automatic shutdown in an emergency situation, for example,
if power is about to be lost. Clearly there is a significant big difference
between both shutdowns. During the first, the user may want to
interact with the application, specifying exactly which files should be
saved and which should be discarded. In the latter case, there's no
time for interaction. There may not even be a user sitting in front of
the machine!

Protocols and support on different platforms

On Mac OS X and MS-Windows, there is nothing like complete session
management for applications yet, i.e. no restoring of previous
sessions. They do support graceful logouts where applications
have the chance to cancel the process after getting confirmation from
the user. This is the functionality that corresponds to the QApplication::commitData() method.

X11 has supported complete session management since X11R6.

Getting session management to work with Qt

Start by reimplementing QApplication::commitData() to
enable your application to take part in the graceful logout process. If
you target the MS-Windows platform only, this is all you can and have
to provide. Ideally, your application should provide a shutdown dialog
similar to the following one:

Example code to this dialog can be found in the documentation of QSessionManager::allowsInteraction().

For complete session management (only supported on X11R6 at present), you also
have to take care of saving the state of the application and
potentially restore the state in the next life cycle of the session.
This saving is done by reimplementing QApplication::saveState(). All state data you are saving in this
function, should be marked with the session identifier QApplication::sessionId(). This application specific identifier is
globally unique, so no clashes will occur. (See QSessionManager for
information on saving/restoring the state of a particular Qt
application.)

Restoration is usually done in the application's main()
function. Check if QApplication::isSessionRestored() is TRUE. If
that's the case, use the session identifier QApplication::sessionId() again to access your state date and restore
the state of the application.

Important: In order to allow the window manager to
restore window attributes such as stacking order or geometry
information, you must identify your top level widgets with
unique application-wide object names (see QObject::setName()). When
restoring the application, you must ensure that all restored
top level widgets are given the same unique names they had before.

Testing and debugging session management

Session management support on Mac OS X and Windows is fairly limited
due to the lack of this functionality in the operating system
itself. Simply shut the session down and verify that your application
behaves as wanted. It may be a good idea to launch another
application, usually the integrated development environment, before
starting your application. This other application will get the
shutdown message afterwards, thus permitting you to cancel the
shutdown. Otherwise you would have to log in again after each test
run, which is not a problem per se but time consuming.

On Unix you can either use a desktop environment that supports
standard X11R6 session management or, the recommended method, use the
session manager reference implementation provided by the X Consortium.
This sample manager is called xsm and is part of a standard X11R6
installation. As always with X11, a useful and informative manual page
is provided. Using xsm is straightforward (apart from the clumsy
Athena-based user interface). Here's a simple approach:

• Run X11R6.
• Create a dot file .xsmstartup in your home directory which
  contains the single line

  xterm
  

  This tells xsm that the default/failsafe session is just an xterm
  and nothing else. Otherwise xsm would try to invoke lots of
  clients including the windowmanager twm, which isn't very helpful.

• Now launch xsm from another terminal window. Both a session
  manager window and the xterm will appear. The xterm has a nice
  property that sets it apart from all the other shells you are
  currently running: within its shell, the SESSION_MANAGER
  environment variable points to the session manager you just started.

• Launch your application from the new xterm window. It will
  connect itself automatically to the session manager. You can check
  with the ClientList push button whether the connect was successful.
  Note: Never keep the ClientList open when you
  start or end session managed clients! Otherwise xsm is likely to
  crash.

• Use the session manager's Checkpoint and Shutdown buttons
  with different settings and see how your application behaves. The save
  type local means that the clients should save their state. It
  corresponds to the QApplication::saveState() function. The global save type asks application to save their unsaved changes in the
  permanent, globally accessible storage. It invokes QApplication::commitData().

• Whenever something crashes, blame xsm and not Qt. xsm is far
  from being a usable session manager on a user's desktop. It is,
  however, stable and useful enough to serve as testing environment.