qsessionmanager.cpp

Absolute File Name:/home/qt/qt5_coco/qt5/qtbase/src/gui/kernel/qsessionmanager.cpp
Source codeSwitch to Preprocessed file
LineSourceCount
1/****************************************************************************-
2**-
3** Copyright (C) 2015 The Qt Company Ltd.-
4** Contact: http://www.qt.io/licensing/-
5**-
6** This file is part of the QtGui module of the Qt Toolkit.-
7**-
8** $QT_BEGIN_LICENSE:LGPL21$-
9** Commercial License Usage-
10** Licensees holding valid commercial Qt licenses may use this file in-
11** accordance with the commercial license agreement provided with the-
12** Software or, alternatively, in accordance with the terms contained in-
13** a written agreement between you and The Qt Company. For licensing terms-
14** and conditions see http://www.qt.io/terms-conditions. For further-
15** information use the contact form at http://www.qt.io/contact-us.-
16**-
17** GNU Lesser General Public License Usage-
18** Alternatively, this file may be used under the terms of the GNU Lesser-
19** General Public License version 2.1 or version 3 as published by the Free-
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and-
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the-
22** following information to ensure the GNU Lesser General Public License-
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and-
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.-
25**-
26** As a special exception, The Qt Company gives you certain additional-
27** rights. These rights are described in The Qt Company LGPL Exception-
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.-
29**-
30** $QT_END_LICENSE$-
31**-
32****************************************************************************/-
33-
34#include <qsessionmanager.h>-
35#include <qguiapplication.h>-
36#include <qpa/qplatformsessionmanager.h>-
37#include <qpa/qplatformintegration.h>-
38-
39#include <private/qobject_p.h>-
40#include <private/qguiapplication_p.h>-
41#include <private/qsessionmanager_p.h>-
42-
43#ifndef QT_NO_SESSIONMANAGER-
44-
45QT_BEGIN_NAMESPACE-
46-
47/*!-
48 \class QSessionManager-
49 \brief The QSessionManager class provides access to the session manager.-
50-
51 \inmodule QtGui-
52-
53 A session manager in a desktop environment (in which Qt GUI applications-
54 live) keeps track of a session, which is a group of running applications,-
55 each of which has a particular state. The state of an application contains-
56 (most notably) the documents the application has open and the position and-
57 size of its windows.-
58-
59 The session manager is used to save the session, e.g., when the machine is-
60 shut down, and to restore a session, e.g., when the machine is started up.-
61 We recommend that you use QSettings to save an application's settings,-
62 for example, window positions, recently used files, etc. When the-
63 application is restarted by the session manager, you can restore the-
64 settings.-
65-
66 QSessionManager provides an interface between the application and the-
67 platform's session manager. In Qt, session management requests for action-
68 are handled by the two signals QGuiApplication::commitDataRequest() and-
69 QGuiApplication::saveStateRequest(). Both provide a reference to a-
70 QSessionManager object as argument. The session manager can only be-
71 accessed in slots invoked by these signals.-
72-
73 \warning If you use QSessionManager, you should disable fallback session-
74 management: QGuiApplication::setFallbackSessionManagementEnabled().-
75-
76 No user interaction is possible \e unless the application gets explicit-
77 permission from the session manager. You ask for permission by calling-
78 allowsInteraction() or, if it is really urgent, allowsErrorInteraction().-
79 Qt does not enforce this, but the session manager may.-
80-
81 You can try to abort the shutdown process by calling cancel().-
82-
83 For sophisticated session managers provided on Unix/X11, QSessionManager-
84 offers further possibilities to fine-tune an application's session-
85 management behavior: setRestartCommand(), setDiscardCommand(),-
86 setRestartHint(), setProperty(), requestPhase2(). See the respective-
87 function descriptions for further details.-
88-
89 \sa QGuiApplication, {Session Management}-
90*/-
91-
92-
93/*! \enum QSessionManager::RestartHint-
94-
95 This enum type defines the circumstances under which this application wants-
96 to be restarted by the session manager. The current values are:-
97-
98 \value RestartIfRunning If the application is still running when the-
99 session is shut down, it wants to be restarted-
100 at the start of the next session.-
101-
102 \value RestartAnyway The application wants to be started at the-
103 start of the next session, no matter what.-
104 (This is useful for utilities that run just-
105 after startup and then quit.)-
106-
107 \value RestartImmediately The application wants to be started immediately-
108 whenever it is not running.-
109-
110 \value RestartNever The application does not want to be restarted-
111 automatically.-
112-
113 The default hint is \c RestartIfRunning.-
114*/-
115-
116QSessionManagerPrivate::QSessionManagerPrivate(const QString &id,-
117 const QString &key)-
118 : QObjectPrivate()-
119{-
120 platformSessionManager = QGuiApplicationPrivate::platformIntegration()->createPlatformSessionManager(id, key);-
121 Q_ASSERT_X(platformSessionManager, "Platform session management",-
122 "No platform session management, should use the default implementation");-
123}
never executed: end of block
0
124-
125QSessionManagerPrivate::~QSessionManagerPrivate()-
126{-
127 delete platformSessionManager;-
128 platformSessionManager = 0;-
129}
never executed: end of block
0
130-
131QSessionManager::QSessionManager(QGuiApplication *app, QString &id, QString &key)-
132 : QObject(*(new QSessionManagerPrivate(id, key)), app)-
133{-
134}
never executed: end of block
0
135-
136QSessionManager::~QSessionManager()-
137{-
138}-
139-
140/*!-
141 Returns the identifier of the current session.-
142-
143 If the application has been restored from an earlier session, this-
144 identifier is the same as it was in the earlier session.-
145-
146 \sa sessionKey(), QGuiApplication::sessionId()-
147*/-
148QString QSessionManager::sessionId() const-
149{-
150 Q_D(const QSessionManager);-
151 return d->platformSessionManager->sessionId();
never executed: return d->platformSessionManager->sessionId();
0
152}-
153-
154/*!-
155 \fn QString QSessionManager::sessionKey() const-
156-
157 Returns the session key in the current session.-
158-
159 If the application has been restored from an earlier session, this key is-
160 the same as it was when the previous session ended.-
161-
162 The session key changes with every call of commitData() or saveState().-
163-
164 \sa sessionId(), QGuiApplication::sessionKey()-
165*/-
166QString QSessionManager::sessionKey() const-
167{-
168 Q_D(const QSessionManager);-
169 return d->platformSessionManager->sessionKey();
never executed: return d->platformSessionManager->sessionKey();
0
170}-
171-
172-
173/*!-
174 Asks the session manager for permission to interact with the user. Returns-
175 true if interaction is permitted; otherwise returns \c false.-
176-
177 The rationale behind this mechanism is to make it possible to synchronize-
178 user interaction during a shutdown. Advanced session managers may ask all-
179 applications simultaneously to commit their data, resulting in a much-
180 faster shutdown.-
181-
182 When the interaction is completed we strongly recommend releasing the user-
183 interaction semaphore with a call to release(). This way, other-
184 applications may get the chance to interact with the user while your-
185 application is still busy saving data. (The semaphore is implicitly-
186 released when the application exits.)-
187-
188 If the user decides to cancel the shutdown process during the interaction-
189 phase, you must tell the session manager that this has happened by calling-
190 cancel().-
191-
192 Here's an example of how an application's QGuiApplication::commitDataRequest()-
193 might be implemented:-
194-
195 \snippet code/src_gui_kernel_qguiapplication.cpp 1-
196-
197 If an error occurred within the application while saving its data, you may-
198 want to try allowsErrorInteraction() instead.-
199-
200 \sa QGuiApplication::commitDataRequest(), release(), cancel()-
201*/-
202bool QSessionManager::allowsInteraction()-
203{-
204 Q_D(QSessionManager);-
205 return d->platformSessionManager->allowsInteraction();
never executed: return d->platformSessionManager->allowsInteraction();
0
206}-
207-
208/*!-
209 Returns \c true if error interaction is permitted; otherwise returns \c false.-
210-
211 This is similar to allowsInteraction(), but also enables the application to-
212 tell the user about any errors that occur. Session managers may give error-
213 interaction requests higher priority, which means that it is more likely-
214 that an error interaction is permitted. However, you are still not-
215 guaranteed that the session manager will allow interaction.-
216-
217 \sa allowsInteraction(), release(), cancel()-
218*/-
219bool QSessionManager::allowsErrorInteraction()-
220{-
221 Q_D(QSessionManager);-
222 return d->platformSessionManager->allowsErrorInteraction();
never executed: return d->platformSessionManager->allowsErrorInteraction();
0
223}-
224-
225/*!-
226 Releases the session manager's interaction semaphore after an interaction-
227 phase.-
228-
229 \sa allowsInteraction(), allowsErrorInteraction()-
230*/-
231void QSessionManager::release()-
232{-
233 Q_D(QSessionManager);-
234 d->platformSessionManager->release();-
235}
never executed: end of block
0
236-
237/*!-
238 Tells the session manager to cancel the shutdown process. Applications-
239 should not call this function without asking the user first.-
240-
241 \sa allowsInteraction(), allowsErrorInteraction()-
242*/-
243void QSessionManager::cancel()-
244{-
245 Q_D(QSessionManager);-
246 d->platformSessionManager->cancel();-
247}
never executed: end of block
0
248-
249/*!-
250 Sets the application's restart hint to \a hint. On application startup, the-
251 hint is set to \c RestartIfRunning.-
252-
253 \note These flags are only hints, a session manager may or may not respect-
254 them.-
255-
256 We recommend setting the restart hint in QGuiApplication::saveStateRequest()-
257 because most session managers perform a checkpoint shortly after an-
258 application's-
259 startup.-
260-
261 \sa restartHint()-
262*/-
263void QSessionManager::setRestartHint(QSessionManager::RestartHint hint)-
264{-
265 Q_D(QSessionManager);-
266 d->platformSessionManager->setRestartHint(hint);-
267}
never executed: end of block
0
268-
269/*!-
270 \fn QSessionManager::RestartHint QSessionManager::restartHint() const-
271-
272 Returns the application's current restart hint. The default is-
273 \c RestartIfRunning.-
274-
275 \sa setRestartHint()-
276*/-
277QSessionManager::RestartHint QSessionManager::restartHint() const-
278{-
279 Q_D(const QSessionManager);-
280 return d->platformSessionManager->restartHint();
never executed: return d->platformSessionManager->restartHint();
0
281}-
282-
283/*!-
284 If the session manager is capable of restoring sessions it will execute-
285 \a command in order to restore the application. The command defaults to-
286-
287 \snippet code/src_gui_kernel_qguiapplication.cpp 2-
288-
289 The \c -session option is mandatory; otherwise QGuiApplication cannot-
290 tell whether it has been restored or what the current session identifier-
291 is.-
292 See QGuiApplication::isSessionRestored() and-
293 QGuiApplication::sessionId() for details.-
294-
295 If your application is very simple, it may be possible to store the entire-
296 application state in additional command line options. This is usually a-
297 very bad idea because command lines are often limited to a few hundred-
298 bytes. Instead, use QSettings, temporary files, or a database for this-
299 purpose. By marking the data with the unique sessionId(), you will be able-
300 to restore the application in a future session.-
301-
302 \sa restartCommand(), setDiscardCommand(), setRestartHint()-
303*/-
304void QSessionManager::setRestartCommand(const QStringList &command)-
305{-
306 Q_D(QSessionManager);-
307 d->platformSessionManager->setRestartCommand(command);-
308}
never executed: end of block
0
309-
310/*!-
311 Returns the currently set restart command.-
312-
313 To iterate over the list, you can use the \l foreach pseudo-keyword:-
314-
315 \snippet code/src_gui_kernel_qguiapplication.cpp 3-
316-
317 \sa setRestartCommand(), restartHint()-
318*/-
319QStringList QSessionManager::restartCommand() const-
320{-
321 Q_D(const QSessionManager);-
322 return d->platformSessionManager->restartCommand();
never executed: return d->platformSessionManager->restartCommand();
0
323}-
324-
325/*!-
326 Sets the discard command to the given \a command.-
327-
328 \sa discardCommand(), setRestartCommand()-
329*/-
330void QSessionManager::setDiscardCommand(const QStringList &command)-
331{-
332 Q_D(QSessionManager);-
333 d->platformSessionManager->setDiscardCommand(command);-
334}
never executed: end of block
0
335-
336/*!-
337 Returns the currently set discard command.-
338-
339 To iterate over the list, you can use the \l foreach pseudo-keyword:-
340-
341 \snippet code/src_gui_kernel_qguiapplication.cpp 4-
342-
343 \sa setDiscardCommand(), restartCommand(), setRestartCommand()-
344*/-
345QStringList QSessionManager::discardCommand() const-
346{-
347 Q_D(const QSessionManager);-
348 return d->platformSessionManager->discardCommand();
never executed: return d->platformSessionManager->discardCommand();
0
349}-
350-
351/*!-
352 \overload-
353-
354 Low-level write access to the application's identification and state-
355 records are kept in the session manager.-
356-
357 The property called \a name has its value set to the string \a value.-
358*/-
359void QSessionManager::setManagerProperty(const QString &name,-
360 const QString &value)-
361{-
362 Q_D(QSessionManager);-
363 d->platformSessionManager->setManagerProperty(name, value);-
364}
never executed: end of block
0
365-
366/*!-
367 Low-level write access to the application's identification and state record-
368 are kept in the session manager.-
369-
370 The property called \a name has its value set to the string list \a value.-
371*/-
372void QSessionManager::setManagerProperty(const QString &name,-
373 const QStringList &value)-
374{-
375 Q_D(QSessionManager);-
376 d->platformSessionManager->setManagerProperty(name, value);-
377}
never executed: end of block
0
378-
379/*!-
380 Returns \c true if the session manager is currently performing a second-
381 session management phase; otherwise returns \c false.-
382-
383 \sa requestPhase2()-
384*/-
385bool QSessionManager::isPhase2() const-
386{-
387 Q_D(const QSessionManager);-
388 return d->platformSessionManager->isPhase2();
never executed: return d->platformSessionManager->isPhase2();
0
389}-
390-
391/*!-
392 Requests a second session management phase for the application. The-
393 application may then return immediately from the-
394 QGuiApplication::commitDataRequest() or QApplication::saveStateRequest()-
395 function, and they will be called again once most or all other-
396 applications have finished their session management.-
397-
398 The two phases are useful for applications such as the X11 window manager-
399 that need to store information about another application's windows and-
400 therefore have to wait until these applications have completed their-
401 respective session management tasks.-
402-
403 \note If another application has requested a second phase it may get called-
404 before, simultaneously with, or after your application's second phase.-
405-
406 \sa isPhase2()-
407*/-
408void QSessionManager::requestPhase2()-
409{-
410 Q_D(QSessionManager);-
411 d->platformSessionManager->requestPhase2();-
412}
never executed: end of block
0
413-
414QT_END_NAMESPACE-
415-
416#endif // QT_NO_SESSIONMANAGER-
Source codeSwitch to Preprocessed file
Generated by Squish Coco Non-Commercial 4.3.0-BETA-master-30-08-2018-4cb69e9