A session is a group of running applications, 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 difference between these types of shutdown. 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 older versions of Mac OS X and Microsoft Windows there is no session management for applications. They do support graceful logouts where applications have the opportunity 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.

ImplementingSession Management

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

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

For complete session management (only supported on X11R6 at present), you must also take care of saving the application's state, and potentially of restoring 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. Refer to QSessionManager for information on saving and restoring the state of a particular CopperSpice 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 data and restore the state of the application.

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::setObjectName()). 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 limited due to the lack of functionality in the operating system. To test your application launch another application before starting your application. This other application will get the shutdown message afterwards, thus permitting you to cancel the shutdown. Otherwise you will have to log in again after each test run which is time consuming.