QSessionManager Class Reference
[QtGui module]

Detailed Description

The QSessionManager class provides access to the session manager.

A session manager in a desktop environment (in which Qt GUI applications live) keeps track of a session, which is a group of running applications, each of which has a particular state. The state of an application contains (most notably) the documents the application has open and the position and size of its windows.

The session manager is used to save the session, e.g., when the machine is shut down, and to restore a session, e.g., when the machine is started up. We recommend that you use QSettings to save an application's settings, for example, window positions, recently used files, etc. When the application is restarted by the session manager, you can restore the settings.

QSessionManager provides an interface between the application and the session manager so that the program can work well with the session manager. In Qt, session management requests for action are handled by the two virtual functions QApplication::commitData() and QApplication::saveState(). Both provide a reference to a session manager object as argument, to allow the application to communicate with the session manager. The session manager can only be accessed through these functions.

No user interaction is possible unless the application gets explicit permission from the session manager. You ask for permission by calling allowsInteraction() or, if it is really urgent, allowsErrorInteraction(). Qt does not enforce this, but the session manager may.

You can try to abort the shutdown process by calling cancel(). The default commitData() function does this if some top-level window rejected its closeEvent().

For sophisticated session managers provided on Unix/X11, QSessionManager offers further possibilities to fine-tune an application's session management behavior: setRestartCommand(), setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2(). See the respective function descriptions for further details.

See also QApplication and Session Management.

Member Type Documentation

 void MyApplication::commitData(QSessionManager& manager)
 {
     if (manager.allowsInteraction()) {
         int ret = QMessageBox::warning(
                     mainWindow,
                     tr("My Application"),
                     tr("Save changes to document?"),
                     QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);

         switch (ret) {
         case QMessageBox::Save:
             manager.release();
             if (!saveDocument())
                 manager.cancel();
             break;
         case QMessageBox::Discard:
             break;
         case QMessageBox::Cancel:
         default:
             manager.cancel();
         }
     } else {
         // we did not get permission to interact, then
         // do something reasonable instead
     }
 }

 foreach (QString command, mySession.discardCommand())
     do_something(command);

 foreach (QString command, mySession.restartCommand())
     do_something(command);

 appname -session id