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