diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/gui/kernel/qsessionmanager.cpp | 247 | ||||
| -rw-r--r-- | src/widgets/kernel/qapplication.cpp | 302 |
2 files changed, 256 insertions, 293 deletions
diff --git a/src/gui/kernel/qsessionmanager.cpp b/src/gui/kernel/qsessionmanager.cpp index 2db2e75de9..ec2787f1bf 100644 --- a/src/gui/kernel/qsessionmanager.cpp +++ b/src/gui/kernel/qsessionmanager.cpp @@ -48,6 +48,81 @@ QT_BEGIN_NAMESPACE +/*! + \class QSessionManager + \brief The QSessionManager class provides access to the session manager. + + \inmodule QtWidgets + + A session manager in a desktop environment (in which Qt GUI applications + live) keeps track of a session, which is a group of running applications, + each of which has a particular state. The state of an application contains + (most notably) the documents the application has open and the position and + size of its windows. + + The session manager is used to save the session, e.g., when the machine is + shut down, and to restore a session, e.g., when the machine is started up. + We recommend that you use QSettings to save an application's settings, + for example, window positions, recently used files, etc. When the + application is restarted by the session manager, you can restore the + settings. + + QSessionManager provides an interface between the application and the + session manager so that the program can work well with the session manager. + In Qt, session management requests for action are handled by the two + virtual functions QApplication::commitData() and QApplication::saveState(). + Both provide a reference to a session manager object as argument, to allow + the application to communicate with the session manager. The session + manager can only be accessed through these functions. + + No user interaction is possible \e unless the application gets explicit + permission from the session manager. You ask for permission by calling + allowsInteraction() or, if it is really urgent, allowsErrorInteraction(). + Qt does not enforce this, but the session manager may. + + You can try to abort the shutdown process by calling cancel(). The default + commitData() function does this if some top-level window rejected its + closeEvent(). + + For sophisticated session managers provided on Unix/X11, QSessionManager + offers further possibilities to fine-tune an application's session + management behavior: setRestartCommand(), setDiscardCommand(), + setRestartHint(), setProperty(), requestPhase2(). See the respective + function descriptions for further details. + + \sa QApplication, {Session Management} +*/ + + +/*! \enum QSessionManager::RestartHint + + This enum type defines the circumstances under which this application wants + to be restarted by the session manager. The current values are: + + \value RestartIfRunning If the application is still running when the + session is shut down, it wants to be restarted + at the start of the next session. + + \value RestartAnyway The application wants to be started at the + start of the next session, no matter what. + (This is useful for utilities that run just + after startup and then quit.) + + \value RestartImmediately The application wants to be started immediately + whenever it is not running. + + \value RestartNever The application does not want to be restarted + automatically. + + The default hint is \c RestartIfRunning. +*/ + +/*! + \fn void* QSessionManager::handle() const + + \internal +*/ + class QSessionManagerPrivate : public QObjectPrivate { public: @@ -79,12 +154,32 @@ QSessionManager::~QSessionManager() { } +/*! + Returns the identifier of the current session. + + If the application has been restored from an earlier session, this + identifier is the same as it was in the earlier session. + + \sa sessionKey(), QApplication::sessionId() +*/ QString QSessionManager::sessionId() const { Q_D(const QSessionManager); return d->sessionId; } +/*! + \fn QString QSessionManager::sessionKey() const + + Returns the session key in the current session. + + If the application has been restored from an earlier session, this key is + the same as it was when the previous session ended. + + The session key changes with every call of commitData() or saveState(). + + \sa sessionId(), QApplication::sessionKey() +*/ QString QSessionManager::sessionKey() const { Q_D(const QSessionManager); @@ -92,60 +187,184 @@ QString QSessionManager::sessionKey() const } +/*! + Asks the session manager for permission to interact with the user. Returns + true if interaction is permitted; otherwise returns false. + + The rationale behind this mechanism is to make it possible to synchronize + user interaction during a shutdown. Advanced session managers may ask all + applications simultaneously to commit their data, resulting in a much + faster shutdown. + + When the interaction is completed we strongly recommend releasing the user + interaction semaphore with a call to release(). This way, other + applications may get the chance to interact with the user while your + application is still busy saving data. (The semaphore is implicitly + released when the application exits.) + + If the user decides to cancel the shutdown process during the interaction + phase, you must tell the session manager that this has happened by calling + cancel(). + + Here's an example of how an application's QApplication::commitData() might + be implemented: + + \snippet code/src_gui_kernel_qapplication.cpp 8 + + If an error occurred within the application while saving its data, you may + want to try allowsErrorInteraction() instead. + + \sa QApplication::commitData(), release(), cancel() +*/ bool QSessionManager::allowsInteraction() { return false; } +/*! + Returns true if error interaction is permitted; otherwise returns false. + + This is similar to allowsInteraction(), but also enables the application to + tell the user about any errors that occur. Session managers may give error + interaction requests higher priority, which means that it is more likely + that an error interaction is permitted. However, you are still not + guaranteed that the session manager will allow interaction. + + \sa allowsInteraction(), release(), cancel() +*/ bool QSessionManager::allowsErrorInteraction() { return false; } +/*! + Releases the session manager's interaction semaphore after an interaction + phase. + + \sa allowsInteraction(), allowsErrorInteraction() +*/ void QSessionManager::release() { } +/*! + Tells the session manager to cancel the shutdown process. Applications + should not call this function without asking the user first. + + \sa allowsInteraction(), allowsErrorInteraction() +*/ void QSessionManager::cancel() { } +/*! + Sets the application's restart hint to \a hint. On application startup, the + hint is set to \c RestartIfRunning. + + \note These flags are only hints, a session manager may or may not respect + them. + + We recommend setting the restart hint in QApplication::saveState() because + most session managers perform a checkpoint shortly after an application's + startup. + + \sa restartHint() +*/ void QSessionManager::setRestartHint(QSessionManager::RestartHint hint) { Q_D(QSessionManager); d->restartHint = hint; } +/*! + \fn QSessionManager::RestartHint QSessionManager::restartHint() const + + Returns the application's current restart hint. The default is + \c RestartIfRunning. + + \sa setRestartHint() +*/ QSessionManager::RestartHint QSessionManager::restartHint() const { Q_D(const QSessionManager); return d->restartHint; } +/*! + If the session manager is capable of restoring sessions it will execute + \a command in order to restore the application. The command defaults to + + \snippet code/src_gui_kernel_qapplication.cpp 9 + + The \c -session option is mandatory; otherwise QApplication cannot tell + whether it has been restored or what the current session identifier is. + See QApplication::isSessionRestored() and QApplication::sessionId() for + details. + + If your application is very simple, it may be possible to store the entire + application state in additional command line options. This is usually a + very bad idea because command lines are often limited to a few hundred + bytes. Instead, use QSettings, temporary files, or a database for this + purpose. By marking the data with the unique sessionId(), you will be able + to restore the application in a future session. + + \sa restartCommand(), setDiscardCommand(), setRestartHint() +*/ void QSessionManager::setRestartCommand(const QStringList &command) { Q_D(QSessionManager); d->restartCommand = command; } +/*! + Returns the currently set restart command. + + To iterate over the list, you can use the \l foreach pseudo-keyword: + + \snippet code/src_gui_kernel_qapplication.cpp 10 + + \sa setRestartCommand(), restartHint() +*/ QStringList QSessionManager::restartCommand() const { Q_D(const QSessionManager); return d->restartCommand; } +/*! + Sets the discard command to the given \a list. + + \sa discardCommand(), setRestartCommand() +*/ void QSessionManager::setDiscardCommand(const QStringList &command) { Q_D(QSessionManager); d->discardCommand = command; } +/*! + Returns the currently set discard command. + + To iterate over the list, you can use the \l foreach pseudo-keyword: + + \snippet code/src_gui_kernel_qapplication.cpp 11 + + \sa setDiscardCommand(), restartCommand(), setRestartCommand() +*/ QStringList QSessionManager::discardCommand() const { Q_D(const QSessionManager); return d->discardCommand; } +/*! + \overload + + Low-level write access to the application's identification and state + records are kept in the session manager. + + The property called \a name has its value set to the string \a value. +*/ void QSessionManager::setManagerProperty(const QString &name, const QString &value) { @@ -153,6 +372,12 @@ void QSessionManager::setManagerProperty(const QString &name, Q_UNUSED(value); } +/*! + Low-level write access to the application's identification and state record + are kept in the session manager. + + The property called \a name has its value set to the string list \a value. +*/ void QSessionManager::setManagerProperty(const QString &name, const QStringList &value) { @@ -160,11 +385,33 @@ void QSessionManager::setManagerProperty(const QString &name, Q_UNUSED(value); } +/*! + Returns true if the session manager is currently performing a second + session management phase; otherwise returns false. + + \sa requestPhase2() +*/ bool QSessionManager::isPhase2() const { return false; } +/*! + Requests a second session management phase for the application. The + application may then return immediately from the QApplication::commitData() + or QApplication::saveState() function, and they will be called again once + most or all other applications have finished their session management. + + The two phases are useful for applications such as the X11 window manager + that need to store information about another application's windows and + therefore have to wait until these applications have completed their + respective session management tasks. + + \note If another application has requested a second phase it may get called + before, simultaneously with, or after your application's second phase. + + \sa isPhase2() +*/ void QSessionManager::requestPhase2() { } diff --git a/src/widgets/kernel/qapplication.cpp b/src/widgets/kernel/qapplication.cpp index 7f5b31d694..254e4c4383 100644 --- a/src/widgets/kernel/qapplication.cpp +++ b/src/widgets/kernel/qapplication.cpp @@ -3595,298 +3595,6 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e) } -/*! - \class QSessionManager - \brief The QSessionManager class provides access to the session manager. - - \inmodule QtWidgets - - A session manager in a desktop environment (in which Qt GUI applications - live) keeps track of a session, which is a group of running applications, - each of which has a particular state. The state of an application contains - (most notably) the documents the application has open and the position and - size of its windows. - - The session manager is used to save the session, e.g., when the machine is - shut down, and to restore a session, e.g., when the machine is started up. - We recommend that you use QSettings to save an application's settings, - for example, window positions, recently used files, etc. When the - application is restarted by the session manager, you can restore the - settings. - - QSessionManager provides an interface between the application and the - session manager so that the program can work well with the session manager. - In Qt, session management requests for action are handled by the two - virtual functions QApplication::commitData() and QApplication::saveState(). - Both provide a reference to a session manager object as argument, to allow - the application to communicate with the session manager. The session - manager can only be accessed through these functions. - - No user interaction is possible \e unless the application gets explicit - permission from the session manager. You ask for permission by calling - allowsInteraction() or, if it is really urgent, allowsErrorInteraction(). - Qt does not enforce this, but the session manager may. - - You can try to abort the shutdown process by calling cancel(). The default - commitData() function does this if some top-level window rejected its - closeEvent(). - - For sophisticated session managers provided on Unix/X11, QSessionManager - offers further possibilities to fine-tune an application's session - management behavior: setRestartCommand(), setDiscardCommand(), - setRestartHint(), setProperty(), requestPhase2(). See the respective - function descriptions for further details. - - \sa QApplication, {Session Management} -*/ - -/*! \enum QSessionManager::RestartHint - - This enum type defines the circumstances under which this application wants - to be restarted by the session manager. The current values are: - - \value RestartIfRunning If the application is still running when the - session is shut down, it wants to be restarted - at the start of the next session. - - \value RestartAnyway The application wants to be started at the - start of the next session, no matter what. - (This is useful for utilities that run just - after startup and then quit.) - - \value RestartImmediately The application wants to be started immediately - whenever it is not running. - - \value RestartNever The application does not want to be restarted - automatically. - - The default hint is \c RestartIfRunning. -*/ - - -/*! - \fn QString QSessionManager::sessionId() const - - Returns the identifier of the current session. - - If the application has been restored from an earlier session, this - identifier is the same as it was in the earlier session. - - \sa sessionKey(), QApplication::sessionId() -*/ - -/*! - \fn QString QSessionManager::sessionKey() const - - Returns the session key in the current session. - - If the application has been restored from an earlier session, this key is - the same as it was when the previous session ended. - - The session key changes with every call of commitData() or saveState(). - - \sa sessionId(), QApplication::sessionKey() -*/ - -/*! - \fn void* QSessionManager::handle() const - - \internal -*/ - -/*! - \fn bool QSessionManager::allowsInteraction() - - Asks the session manager for permission to interact with the user. Returns - true if interaction is permitted; otherwise returns false. - - The rationale behind this mechanism is to make it possible to synchronize - user interaction during a shutdown. Advanced session managers may ask all - applications simultaneously to commit their data, resulting in a much - faster shutdown. - - When the interaction is completed we strongly recommend releasing the user - interaction semaphore with a call to release(). This way, other - applications may get the chance to interact with the user while your - application is still busy saving data. (The semaphore is implicitly - released when the application exits.) - - If the user decides to cancel the shutdown process during the interaction - phase, you must tell the session manager that this has happened by calling - cancel(). - - Here's an example of how an application's QApplication::commitData() might - be implemented: - - \snippet code/src_gui_kernel_qapplication.cpp 8 - - If an error occurred within the application while saving its data, you may - want to try allowsErrorInteraction() instead. - - \sa QApplication::commitData(), release(), cancel() -*/ - - -/*! - \fn bool QSessionManager::allowsErrorInteraction() - - Returns true if error interaction is permitted; otherwise returns false. - - This is similar to allowsInteraction(), but also enables the application to - tell the user about any errors that occur. Session managers may give error - interaction requests higher priority, which means that it is more likely - that an error interaction is permitted. However, you are still not - guaranteed that the session manager will allow interaction. - - \sa allowsInteraction(), release(), cancel() -*/ - -/*! - \fn void QSessionManager::release() - - Releases the session manager's interaction semaphore after an interaction - phase. - - \sa allowsInteraction(), allowsErrorInteraction() -*/ - -/*! - \fn void QSessionManager::cancel() - - Tells the session manager to cancel the shutdown process. Applications - should not call this function without asking the user first. - - \sa allowsInteraction(), allowsErrorInteraction() -*/ - -/*! - \fn void QSessionManager::setRestartHint(RestartHint hint) - - Sets the application's restart hint to \a hint. On application startup, the - hint is set to \c RestartIfRunning. - - \note These flags are only hints, a session manager may or may not respect - them. - - We recommend setting the restart hint in QApplication::saveState() because - most session managers perform a checkpoint shortly after an application's - startup. - - \sa restartHint() -*/ - -/*! - \fn QSessionManager::RestartHint QSessionManager::restartHint() const - - Returns the application's current restart hint. The default is - \c RestartIfRunning. - - \sa setRestartHint() -*/ - -/*! - \fn void QSessionManager::setRestartCommand(const QStringList& command) - - If the session manager is capable of restoring sessions it will execute - \a command in order to restore the application. The command defaults to - - \snippet code/src_gui_kernel_qapplication.cpp 9 - - The \c -session option is mandatory; otherwise QApplication cannot tell - whether it has been restored or what the current session identifier is. - See QApplication::isSessionRestored() and QApplication::sessionId() for - details. - - If your application is very simple, it may be possible to store the entire - application state in additional command line options. This is usually a - very bad idea because command lines are often limited to a few hundred - bytes. Instead, use QSettings, temporary files, or a database for this - purpose. By marking the data with the unique sessionId(), you will be able - to restore the application in a future session. - - \sa restartCommand(), setDiscardCommand(), setRestartHint() -*/ - -/*! - \fn QStringList QSessionManager::restartCommand() const - - Returns the currently set restart command. - - To iterate over the list, you can use the \l foreach pseudo-keyword: - - \snippet code/src_gui_kernel_qapplication.cpp 10 - - \sa setRestartCommand(), restartHint() -*/ - -/*! - \fn void QSessionManager::setDiscardCommand(const QStringList& list) - - Sets the discard command to the given \a list. - - \sa discardCommand(), setRestartCommand() -*/ - - -/*! - \fn QStringList QSessionManager::discardCommand() const - - Returns the currently set discard command. - - To iterate over the list, you can use the \l foreach pseudo-keyword: - - \snippet code/src_gui_kernel_qapplication.cpp 11 - - \sa setDiscardCommand(), restartCommand(), setRestartCommand() -*/ - -/*! - \fn void QSessionManager::setManagerProperty(const QString &name, const QString &value) - \overload - - Low-level write access to the application's identification and state - records are kept in the session manager. - - The property called \a name has its value set to the string \a value. -*/ - -/*! - \fn void QSessionManager::setManagerProperty(const QString& name, - const QStringList& value) - - Low-level write access to the application's identification and state record - are kept in the session manager. - - The property called \a name has its value set to the string list \a value. -*/ - -/*! - \fn bool QSessionManager::isPhase2() const - - Returns true if the session manager is currently performing a second - session management phase; otherwise returns false. - - \sa requestPhase2() -*/ - -/*! - \fn void QSessionManager::requestPhase2() - - Requests a second session management phase for the application. The - application may then return immediately from the QApplication::commitData() - or QApplication::saveState() function, and they will be called again once - most or all other applications have finished their session management. - - The two phases are useful for applications such as the X11 window manager - that need to store information about another application's windows and - therefore have to wait until these applications have completed their - respective session management tasks. - - \note If another application has requested a second phase it may get called - before, simultaneously with, or after your application's second phase. - - \sa isPhase2() -*/ /*! \fn Qt::MacintoshVersion QApplication::macVersion() @@ -4110,7 +3818,6 @@ int QApplication::cursorFlashTime() return qApp->styleHints()->cursorFlashTime(); } - /*! \property QApplication::doubleClickInterval \brief the time limit in milliseconds that distinguishes a double click @@ -4132,6 +3839,15 @@ int QApplication::doubleClickInterval() } /*! + \fn QGuiApplication::keyboardInputDirection() + \since 4.2 + \deprecated + + Returns the current keyboard input direction. Replaced with QInputPanel::inputDirection() + \sa QInputPanel::inputDirection() +*/ + +/*! \property QApplication::keyboardInputInterval \brief the time limit in milliseconds that distinguishes a key press from two consecutive key presses |