1QSessionManager(3qt) QSessionManager(3qt)
2
6 QSessionManager - Access to the session manager
7
9 #include <qsessionmanager.h>
10 Inherits QObject.
12 Public Members
14 QString sessionId () const
15 QString sessionKey () const
16 void * handle () const
17 bool allowsInteraction ()
18 bool allowsErrorInteraction ()
19 void release ()
20 void cancel ()
21 enum RestartHint { RestartIfRunning, RestartAnyway, RestartImmediately,
22 RestartNever }
23 void setRestartHint ( RestartHint hint )
24 RestartHint restartHint () const
25 void setRestartCommand ( const QStringList & command )
26 QStringList restartCommand () const
27 void setDiscardCommand ( const QStringList & )
28 QStringList discardCommand () const
29 void setManagerProperty ( const QString & name, const QString & value )
30 void setManagerProperty ( const QString & name, const QStringList &
31 value )
32 bool isPhase2 () const
33 void requestPhase2 ()
34
36 The QSessionManager class provides access to the session manager.
37 The session manager is responsible for session management, most
39 importantly for interruption and resumption. A "session" is a kind of
40 record of the state of the system, e.g. which applications were run at
41 start up and which applications are currently running. The session
42 manager is used to save the session, e.g. when the machine is shut
43 down; and to restore a session, e.g. when the machine is started up.
44 Use QSettings to save and restore an individual application's settings,
45 e.g. window positions, recently used files, etc.
46 QSessionManager provides an interface between the application and the
48 session manager so that the program can work well with the session
49 manager. In Qt, session management requests for action are handled by
50 the two virtual functions QApplication::commitData() and
51 QApplication::saveState(). Both provide a reference to a session
52 manager object as argument, to allow the application to communicate
53 with the session manager.
54 During a session management action (i.e. within commitData() and
56 saveState()), no user interaction is possible unless the application
57 got explicit permission from the session manager. You ask for
58 permission by calling allowsInteraction() or, if it's really urgent,
59 allowsErrorInteraction(). Qt does not enforce this, but the session
60 manager may.
61 You can try to abort the shutdown process by calling cancel(). The
63 default commitData() function does this if some top-level window
64 rejected its closeEvent().
65 For sophisticated session managers provided on Unix/X11,
67 QSessionManager offers further possibilites to fine-tune an
68 application's session management behavior: setRestartCommand(),
69 setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2().
70 See the respective function descriptions for further details.
71 See also Main Window and Related Classes and Environment Classes.
73 Member Type Documentation
76 This enum type defines the circumstances under which this application
77 wants to be restarted by the session manager. The current values are
78 QSessionManager::RestartIfRunning - if the application is still running
80 when the session is shut down, it wants to be restarted at the start of
81 the next session.
82 QSessionManager::RestartAnyway - the application wants to be started at
84 the start of the next session, no matter what. (This is useful for
85 utilities that run just after startup and then quit.)
86 QSessionManager::RestartImmediately - the application wants to be
88 started immediately whenever it is not running.
89 QSessionManager::RestartNever - the application does not want to be
91 restarted automatically.
92 The default hint is RestartIfRunning.
94
97 This is similar to allowsInteraction(), but also tells the session
98 manager that an error occurred. Session managers may give error
99 interaction request higher priority, which means that it is more likely
100 that an error interaction is permitted. However, you are still not
101 guaranteed that the session manager will allow interaction.
102 See also allowsInteraction(), release(), and cancel().
104
106 Asks the session manager for permission to interact with the user.
107 Returns TRUE if interaction is permitted; otherwise returns FALSE.
108 The rationale behind this mechanism is to make it possible to
110 synchronize user interaction during a shutdown. Advanced session
111 managers may ask all applications simultaneously to commit their data,
112 resulting in a much faster shutdown.
113 When the interaction is completed we strongly recommend releasing the
115 user interaction semaphore with a call to release(). This way, other
116 applications may get the chance to interact with the user while your
117 application is still busy saving data. (The semaphore is implicitly
118 released when the application exits.)
119 If the user decides to cancel the shutdown process during the
121 interaction phase, you must tell the session manager that this has
122 happened by calling cancel().
123 Here's an example of how an application's QApplication::commitData()
125 might be implemented:
126 void MyApplication::commitData( QSessionManager& sm ) {
128 if ( sm.allowsInteraction() ) {
129 switch ( QMessageBox::warning(
130 yourMainWindow,
131 tr("Application Name"),
132 tr("Save changes to document Foo?"),
133 tr("&Yes"),
134 tr("&No"),
135 tr("Cancel"),
136 0, 2) ) {
137 case 0: // yes
138 sm.release();
139 // save document here; if saving fails, call sm.cancel()
140 break;
141 case 1: // continue without saving
142 break;
143 default: // cancel
144 sm.cancel();
145 break;
146 }
147 } else {
148 // we did not get permission to interact, then
149 // do something reasonable instead.
150 }
151 }
152 If an error occurred within the application while saving its data, you
154 may want to try allowsErrorInteraction() instead.
155 See also QApplication::commitData(), release(), and cancel().
157
159 Tells the session manager to cancel the shutdown process. Applications
160 should not call this function without first asking the user.
161 See also allowsInteraction() and allowsErrorInteraction().
163
165 Returns the currently set discard command.
166 Note that if you want to iterate over the list, you should iterate over
168 a copy, e.g.
169 QStringList list = mySession.discardCommand();
171 QStringList::Iterator it = list.begin();
172 while( it != list.end() ) {
173 myProcessing( *it );
174 ++it;
175 }
176 See also setDiscardCommand(), restartCommand(), and
178 setRestartCommand().
179
181 X11 only: returns a handle to the current SmcConnection.
182
184 Returns TRUE if the session manager is currently performing a second
185 session management phase; otherwise returns FALSE.
186 See also requestPhase2().
188
190 Releases the session manager's interaction semaphore after an
191 interaction phase.
192 See also allowsInteraction() and allowsErrorInteraction().
194
196 Requests a second session management phase for the application. The
197 application may then return immediately from the
198 QApplication::commitData() or QApplication::saveState() function, and
199 they will be called again once most or all other applications have
200 finished their session management.
201 The two phases are useful for applications such as the X11 window
203 manager that need to store information about another application's
204 windows and therefore have to wait until these applications have
205 completed their respective session management tasks.
206 Note that if another application has requested a second phase it may
208 get called before, simultaneously with, or after your application's
209 second phase.
210 See also isPhase2().
212
214 Returns the currently set restart command.
215 Note that if you want to iterate over the list, you should iterate over
217 a copy, e.g.
218 QStringList list = mySession.restartCommand();
220 QStringList::Iterator it = list.begin();
221 while( it != list.end() ) {
222 myProcessing( *it );
223 ++it;
224 }
225 See also setRestartCommand() and restartHint().
227
229 Returns the application's current restart hint. The default is
230 RestartIfRunning.
231 See also setRestartHint().
233
235 Returns the identifier of the current session.
236 If the application has been restored from an earlier session, this
238 identifier is the same as it was in that earlier session.
239 See also sessionKey() and QApplication::sessionId().
241
243 Returns the session key in the current session.
244 If the application has been restored from an earlier session, this key
246 is the same as it was when the previous session ended.
247 The session key changes with every call of commitData() or saveState().
249 See also sessionId() and QApplication::sessionKey().
251
253 See also discardCommand() and setRestartCommand().
254
256 QStringList & value )
257 Low-level write access to the application's identification and state
258 record are kept in the session manager.
259 The property called name has its value set to the string list value.
261
263 & value )
264 This is an overloaded member function, provided for convenience. It
265 behaves essentially like the above function.
266 Low-level write access to the application's identification and state
268 records are kept in the session manager.
269 The property called name has its value set to the string value.
271
273 If the session manager is capable of restoring sessions it will execute
274 command in order to restore the application. The command defaults to
275 appname -session id
277 The -session option is mandatory; otherwise QApplication cannot tell
279 whether it has been restored or what the current session identifier is.
280 See QApplication::isSessionRestored() and QApplication::sessionId() for
281 details.
282 If your application is very simple, it may be possible to store the
284 entire application state in additional command line options. This is
285 usually a very bad idea because command lines are often limited to a
286 few hundred bytes. Instead, use QSettings, or temporary files or a
287 database for this purpose. By marking the data with the unique
288 sessionId(), you will be able to restore the application in a future
289 session.
290 See also restartCommand(), setDiscardCommand(), and setRestartHint().
292
294 Sets the application's restart hint to hint. On application startup the
295 hint is set to RestartIfRunning.
296 Note that these flags are only hints, a session manager may or may not
298 respect them.
299 We recommend setting the restart hint in QApplication::saveState()
301 because most session managers perform a checkpoint shortly after an
302 application's startup.
303 See also restartHint().
305
308 http://doc.trolltech.com/qsessionmanager.html
309 http://www.trolltech.com/faq/tech.html
310
312 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
313 license file included in the distribution for a complete license
314 statement.
315
317 Generated automatically from the source code.
318
320 If you find a bug in Qt, please report it as described in
321 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
322 help you. Thank you.
323 The definitive Qt documentation is provided in HTML format; it is
325 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
326 web browser. This man page is provided as a convenience for those users
327 who prefer man pages, although this format is not officially supported
328 by Trolltech.
329 If you find errors in this manual page, please report them to qt-
331 bugs@trolltech.com. Please include the name of the manual page
332 (qsessionmanager.3qt) and the Qt version (3.3.8).
333Trolltech AS 2 February 2007 QSessionManager(3qt)