OpenCoverage

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