source: trunk/doc/src/howtos/session.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 8.0 KB
RevLine 
[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