1QSessionManager(3qt)                                      QSessionManager(3qt)
2
3
4

NAME

6       QSessionManager - Access to the session manager
7

SYNOPSIS

9       #include <qsessionmanager.h>
10
11       Inherits QObject.
12
13   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

DESCRIPTION

36       The QSessionManager class provides access to the session manager.
37
38       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
47       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
55       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
62       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
66       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
72       See also Main Window and Related Classes and Environment Classes.
73
74   Member Type Documentation

QSessionManager::RestartHint

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
79       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
83       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
87       QSessionManager::RestartImmediately - the application wants to be
88       started immediately whenever it is not running.
89
90       QSessionManager::RestartNever - the application does not want to be
91       restarted automatically.
92
93       The default hint is RestartIfRunning.
94

MEMBER FUNCTION DOCUMENTATION

bool QSessionManager::allowsErrorInteraction ()

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
103       See also allowsInteraction(), release(), and cancel().
104

bool QSessionManager::allowsInteraction ()

106       Asks the session manager for permission to interact with the user.
107       Returns TRUE if interaction is permitted; otherwise returns FALSE.
108
109       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
114       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
120       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
124       Here's an example of how an application's QApplication::commitData()
125       might be implemented:
126
127       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
153       If an error occurred within the application while saving its data, you
154       may want to try allowsErrorInteraction() instead.
155
156       See also QApplication::commitData(), release(), and cancel().
157

void QSessionManager::cancel ()

159       Tells the session manager to cancel the shutdown process. Applications
160       should not call this function without first asking the user.
161
162       See also allowsInteraction() and allowsErrorInteraction().
163

QStringList QSessionManager::discardCommand () const

165       Returns the currently set discard command.
166
167       Note that if you want to iterate over the list, you should iterate over
168       a copy, e.g.
169
170           QStringList list = mySession.discardCommand();
171           QStringList::Iterator it = list.begin();
172           while( it != list.end() ) {
173               myProcessing( *it );
174               ++it;
175           }
176
177       See also setDiscardCommand(), restartCommand(), and
178       setRestartCommand().
179

void * QSessionManager::handle () const

181       X11 only: returns a handle to the current SmcConnection.
182

bool QSessionManager::isPhase2 () const

184       Returns TRUE if the session manager is currently performing a second
185       session management phase; otherwise returns FALSE.
186
187       See also requestPhase2().
188

void QSessionManager::release ()

190       Releases the session manager's interaction semaphore after an
191       interaction phase.
192
193       See also allowsInteraction() and allowsErrorInteraction().
194

void QSessionManager::requestPhase2 ()

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
202       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
207       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
211       See also isPhase2().
212

QStringList QSessionManager::restartCommand () const

214       Returns the currently set restart command.
215
216       Note that if you want to iterate over the list, you should iterate over
217       a copy, e.g.
218
219           QStringList list = mySession.restartCommand();
220           QStringList::Iterator it = list.begin();
221           while( it != list.end() ) {
222               myProcessing( *it );
223               ++it;
224           }
225
226       See also setRestartCommand() and restartHint().
227

RestartHint QSessionManager::restartHint () const

229       Returns the application's current restart hint. The default is
230       RestartIfRunning.
231
232       See also setRestartHint().
233

QString QSessionManager::sessionId () const

235       Returns the identifier of the current session.
236
237       If the application has been restored from an earlier session, this
238       identifier is the same as it was in that earlier session.
239
240       See also sessionKey() and QApplication::sessionId().
241

QString QSessionManager::sessionKey () const

243       Returns the session key in the current session.
244
245       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
248       The session key changes with every call of commitData() or saveState().
249
250       See also sessionId() and QApplication::sessionKey().
251

void QSessionManager::setDiscardCommand ( const QStringList & )

253       See also discardCommand() and setRestartCommand().
254

void QSessionManager::setManagerProperty ( const QString & name, const

256       QStringList & value )
257       Low-level write access to the application's identification and state
258       record are kept in the session manager.
259
260       The property called name has its value set to the string list value.
261

void QSessionManager::setManagerProperty ( const QString & name, const QString

263       & value )
264       This is an overloaded member function, provided for convenience. It
265       behaves essentially like the above function.
266
267       Low-level write access to the application's identification and state
268       records are kept in the session manager.
269
270       The property called name has its value set to the string value.
271

void QSessionManager::setRestartCommand ( const QStringList & command )

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
276               appname -session id
277
278       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
283       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
291       See also restartCommand(), setDiscardCommand(), and setRestartHint().
292

void QSessionManager::setRestartHint ( RestartHint hint )

294       Sets the application's restart hint to hint. On application startup the
295       hint is set to RestartIfRunning.
296
297       Note that these flags are only hints, a session manager may or may not
298       respect them.
299
300       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
304       See also restartHint().
305
306

SEE ALSO

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

AUTHOR

317       Generated automatically from the source code.
318

BUGS

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
324       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
330       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).
333
334
335
336Trolltech AS                    2 February 2007           QSessionManager(3qt)
Impressum