|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page session.html |
|
44 \title Session Management |
|
45 |
|
46 \ingroup best-practices |
|
47 |
|
48 A \e session is a group of running applications, each of which has a |
|
49 particular state. The session is controlled by a service called the \e |
|
50 session \e manager. The applications participating in the session are |
|
51 called \e{session clients}. |
|
52 |
|
53 The session manager issues commands to its clients on behalf of the |
|
54 user. These commands may cause clients to commit unsaved changes (for |
|
55 example by saving open files), to preserve their state for future |
|
56 sessions, or to terminate gracefully. The set of these operations is |
|
57 called \e session \e management. |
|
58 |
|
59 In the common case, a session consists of all applications that a |
|
60 user runs on their desktop at a time. Under Unix/X11, however, a |
|
61 session may include applications running on different computers and |
|
62 may span multiple displays. |
|
63 |
|
64 \section1 Shutting a Session Down |
|
65 |
|
66 A session is shut down by the session manager, usually on behalf of |
|
67 the user when they want to log out. A system might also perform an |
|
68 automatic shutdown in an emergency situation, for example, if power is |
|
69 about to be lost. Clearly there is a significant difference between |
|
70 these types of shutdown. During the first, the user may want to |
|
71 interact with the application, specifying exactly which files should |
|
72 be saved and which should be discarded. In the latter case, there's no |
|
73 time for interaction. There may not even be a user sitting in front of |
|
74 the machine! |
|
75 |
|
76 |
|
77 \section1 Protocols and Support on Different Platforms |
|
78 |
|
79 On Mac OS X, and Microsoft Windows versions prior to Windows 2000, |
|
80 there is nothing like complete session management for applications |
|
81 yet, i.e. no restoring of previous sessions. (Windows 2000 and XP |
|
82 provide "hibernation" where the entire memory is saved to disk and |
|
83 restored when the machine is restarted.) They do support graceful |
|
84 logouts where applications have the opportunity to cancel the process |
|
85 after getting confirmation from the user. This is the functionality |
|
86 that corresponds to the QApplication::commitData() method. |
|
87 |
|
88 X11 has supported complete session management since X11R6. |
|
89 |
|
90 \section1 Getting Session Management to Work with Qt |
|
91 |
|
92 Start by reimplementing QApplication::commitData() to |
|
93 enable your application to take part in the graceful logout process. If |
|
94 you are only targeting the Microsoft Windows platform, this is all you can |
|
95 and must provide. Ideally, your application should provide a shutdown |
|
96 dialog similar to the following: |
|
97 |
|
98 \img session.png A typical dialog on shutdown |
|
99 |
|
100 Example code for this dialog can be found in the documentation of |
|
101 QSessionManager::allowsInteraction(). |
|
102 |
|
103 For complete session management (only supported on X11R6 at present), |
|
104 you must also take care of saving the application's state, and |
|
105 potentially of restoring the state in the next life cycle of the |
|
106 session. This saving is done by reimplementing |
|
107 QApplication::saveState(). All state data you are saving in this |
|
108 function, should be marked with the session identifier |
|
109 QApplication::sessionId(). This application specific identifier is |
|
110 globally unique, so no clashes will occur. (See QSessionManager for |
|
111 information on saving/restoring the state of a particular Qt |
|
112 application.) |
|
113 |
|
114 Restoration is usually done in the application's main() |
|
115 function. Check if QApplication::isSessionRestored() is \c true. If |
|
116 that's the case, use the session identifier |
|
117 QApplication::sessionId() again to access your state data and restore |
|
118 the state of the application. |
|
119 |
|
120 \bold{Important:} In order to allow the window manager to |
|
121 restore window attributes such as stacking order or geometry |
|
122 information, you must identify your top level widgets with |
|
123 unique application-wide object names (see QObject::setObjectName()). When |
|
124 restoring the application, you must ensure that all restored |
|
125 top level widgets are given the same unique names they had before. |
|
126 |
|
127 \section1 Testing and Debugging Session Management |
|
128 |
|
129 Session management support on Mac OS X and Windows is fairly limited |
|
130 due to the lack of this functionality in the operating system |
|
131 itself. Simply shut the session down and verify that your application |
|
132 behaves as expected. It may be useful to launch another application, |
|
133 usually the integrated development environment, before starting your |
|
134 application. This other application will get the shutdown message |
|
135 afterwards, thus permitting you to cancel the shutdown. Otherwise you |
|
136 would have to log in again after each test run, which is not a problem |
|
137 per se, but is time consuming. |
|
138 |
|
139 On Unix you can either use a desktop environment that supports |
|
140 standard X11R6 session management or, the recommended method, use the |
|
141 session manager reference implementation provided by the X Consortium. |
|
142 This sample manager is called \c xsm and is part of a standard X11R6 |
|
143 installation. As always with X11, a useful and informative manual page |
|
144 is provided. Using \c xsm is straightforward (apart from the clumsy |
|
145 Athena-based user interface). Here's a simple approach: |
|
146 |
|
147 \list |
|
148 \i Run X11R6. |
|
149 \i Create a dot file \c .xsmstartup in your home directory which |
|
150 contains the single line |
|
151 \snippet doc/src/snippets/code/doc_src_session.qdoc 0 |
|
152 This tells \c xsm that the default/failsafe session is just an xterm |
|
153 and nothing else. Otherwise \c xsm would try to invoke lots of |
|
154 clients including the windowmanager \c twm, which isn't very helpful. |
|
155 \i Now launch \c xsm from another terminal window. Both a session |
|
156 manager window and the xterm will appear. The xterm has a nice |
|
157 property that sets it apart from all the other shells you are |
|
158 currently running: within its shell, the \c SESSION_MANAGER |
|
159 environment variable points to the session manager you just started. |
|
160 \i Launch your application from the new xterm window. It will connect |
|
161 itself automatically to the session manager. You can check with the \e |
|
162 ClientList push button whether the connect was successful. |
|
163 |
|
164 \bold{Note:} Never keep the \e ClientList open when you |
|
165 start or end session managed clients! Otherwise \c xsm is likely to |
|
166 crash. |
|
167 \i Use the session manager's \e Checkpoint and \e Shutdown buttons |
|
168 with different settings and see how your application behaves. The save |
|
169 type \e local means that the clients should save their state. It |
|
170 corresponds to the QApplication::saveState() function. The \e |
|
171 global save type asks applications to save their unsaved changes in |
|
172 permanent, globally accessible storage. It invokes |
|
173 QApplication::commitData(). |
|
174 \i Whenever something crashes, blame \c xsm and not Qt. \c xsm is far |
|
175 from being a usable session manager on a user's desktop. It is, |
|
176 however, stable and useful enough to serve as testing environment. |
|
177 \endlist |
|
178 */ |