| [556] | 1 | /****************************************************************************
|
|---|
| 2 | **
|
|---|
| [846] | 3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
|---|
| [556] | 4 | ** All rights reserved.
|
|---|
| 5 | ** Contact: Nokia Corporation ([email protected])
|
|---|
| 6 | **
|
|---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
|---|
| 8 | **
|
|---|
| [846] | 9 | ** $QT_BEGIN_LICENSE:FDL$
|
|---|
| [556] | 10 | ** Commercial Usage
|
|---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
|---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
|---|
| [846] | 13 | ** Software or, alternatively, in accordance with the terms contained in a
|
|---|
| 14 | ** written agreement between you and Nokia.
|
|---|
| [556] | 15 | **
|
|---|
| [846] | 16 | ** GNU Free Documentation License
|
|---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
|---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
|---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
|---|
| 20 | ** file.
|
|---|
| [556] | 21 | **
|
|---|
| 22 | ** If you have questions regarding the use of this file, please contact
|
|---|
| 23 | ** Nokia at [email protected].
|
|---|
| 24 | ** $QT_END_LICENSE$
|
|---|
| 25 | **
|
|---|
| 26 | ****************************************************************************/
|
|---|
| 27 |
|
|---|
| 28 | /*!
|
|---|
| 29 | \page session.html
|
|---|
| 30 | \title Session Management
|
|---|
| [846] | 31 | \brief How to do session management with Qt.
|
|---|
| [556] | 32 | \ingroup best-practices
|
|---|
| 33 |
|
|---|
| 34 | A \e session is a group of running applications, each of which has a
|
|---|
| 35 | particular state. The session is controlled by a service called the \e
|
|---|
| 36 | session \e manager. The applications participating in the session are
|
|---|
| 37 | called \e{session clients}.
|
|---|
| 38 |
|
|---|
| 39 | The session manager issues commands to its clients on behalf of the
|
|---|
| 40 | user. These commands may cause clients to commit unsaved changes (for
|
|---|
| 41 | example by saving open files), to preserve their state for future
|
|---|
| 42 | sessions, or to terminate gracefully. The set of these operations is
|
|---|
| 43 | called \e session \e management.
|
|---|
| 44 |
|
|---|
| 45 | In the common case, a session consists of all applications that a
|
|---|
| 46 | user runs on their desktop at a time. Under Unix/X11, however, a
|
|---|
| 47 | session may include applications running on different computers and
|
|---|
| 48 | may span multiple displays.
|
|---|
| 49 |
|
|---|
| 50 | \section1 Shutting a Session Down
|
|---|
| 51 |
|
|---|
| 52 | A session is shut down by the session manager, usually on behalf of
|
|---|
| 53 | the user when they want to log out. A system might also perform an
|
|---|
| 54 | automatic shutdown in an emergency situation, for example, if power is
|
|---|
| 55 | about to be lost. Clearly there is a significant difference between
|
|---|
| 56 | these types of shutdown. During the first, the user may want to
|
|---|
| 57 | interact with the application, specifying exactly which files should
|
|---|
| 58 | be saved and which should be discarded. In the latter case, there's no
|
|---|
| 59 | time for interaction. There may not even be a user sitting in front of
|
|---|
| 60 | the machine!
|
|---|
| 61 |
|
|---|
| 62 |
|
|---|
| 63 | \section1 Protocols and Support on Different Platforms
|
|---|
| 64 |
|
|---|
| 65 | On Mac OS X, and Microsoft Windows versions prior to Windows 2000,
|
|---|
| 66 | there is nothing like complete session management for applications
|
|---|
| 67 | yet, i.e. no restoring of previous sessions. (Windows 2000 and XP
|
|---|
| 68 | provide "hibernation" where the entire memory is saved to disk and
|
|---|
| 69 | restored when the machine is restarted.) They do support graceful
|
|---|
| 70 | logouts where applications have the opportunity to cancel the process
|
|---|
| 71 | after getting confirmation from the user. This is the functionality
|
|---|
| 72 | that corresponds to the QApplication::commitData() method.
|
|---|
| 73 |
|
|---|
| 74 | X11 has supported complete session management since X11R6.
|
|---|
| 75 |
|
|---|
| 76 | \section1 Getting Session Management to Work with Qt
|
|---|
| 77 |
|
|---|
| 78 | Start by reimplementing QApplication::commitData() to
|
|---|
| 79 | enable your application to take part in the graceful logout process. If
|
|---|
| 80 | you are only targeting the Microsoft Windows platform, this is all you can
|
|---|
| 81 | and must provide. Ideally, your application should provide a shutdown
|
|---|
| 82 | dialog similar to the following:
|
|---|
| 83 |
|
|---|
| 84 | \img session.png A typical dialog on shutdown
|
|---|
| 85 |
|
|---|
| 86 | Example code for this dialog can be found in the documentation of
|
|---|
| 87 | QSessionManager::allowsInteraction().
|
|---|
| 88 |
|
|---|
| 89 | For complete session management (only supported on X11R6 at present),
|
|---|
| 90 | you must also take care of saving the application's state, and
|
|---|
| 91 | potentially of restoring the state in the next life cycle of the
|
|---|
| |
|---|
