AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update QSessionManager and related classes documentation

Browse Source 
Update the Qt 4 documentation of QSessionManager to reflect the changes
in Qt 5

Task-number: QTBUG-33528

Change-Id: I74286134155efc2781f9f6fc505fb6cf736d814e
Reviewed-by: Martin Smith <martin.smith@digia.com>
This commit is contained in:
Samuel Gaist 2013-09-27 21:53:12 +02:00 committed by The Qt Project
parent bc962256b4
commit 56cd9cc2b0
8 changed files with 149 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
src/gui/doc/snippets/code/src_gui_kernel_qapplication.cpp
View File

@ -107,79 +107,20 @@ void updateAllWidgets()
//! [6]
int main(int argc, char *argv[])
{
QApplication::setDesktopSettingsAware(false);
QApplication app(argc, argv);
...
return app.exec();
}
//! [6]
//! [7]
if ((startPos - currentPos).manhattanLength() >=
QApplication::startDragDistance())
startTheDrag();
//! [6]
//! [7]
QWidget *widget = qApp->widgetAt(x, y);
if (widget)
widget = widget->window();
//! [7]
//! [8]
void MyApplication::commitData(QSessionManager& manager)
{
if (manager.allowsInteraction()) {
int ret = QMessageBox::warning(
mainWindow,
tr("My Application"),
tr("Save changes to document?"),
QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
switch (ret) {
case QMessageBox::Save:
manager.release();
if (!saveDocument())
manager.cancel();
break;
case QMessageBox::Discard:
break;
case QMessageBox::Cancel:
default:
manager.cancel();
}
} else {
// we did not get permission to interact, then
// do something reasonable instead
}
}
//! [8]
//! [9]
appname -session id
//! [9]
//! [10]
foreach (const QString &command, mySession.restartCommand())
do_something(command);
//! [10]
//! [11]
foreach (const QString &command, mySession.discardCommand())
do_something(command);
//! [11]
//! [12]
QWidget *widget = qApp->widgetAt(x, y);
if (widget)
widget = widget->window();
//! [12]
//! [13]
QWidget *widget = qApp->widgetAt(point);
if (widget)
widget = widget->window();
//! [13]
//! [8]

102
src/gui/doc/snippets/code/src_gui_kernel_qguiapplication.cpp Normal file
View File

@ -0,0 +1,102 @@
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
** * Redistributions of source code must retain the above copyright
** notice, this list of conditions and the following disclaimer.
** * Redistributions in binary form must reproduce the above copyright
** notice, this list of conditions and the following disclaimer in
** the documentation and/or other materials provided with the
** distribution.
** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
** of its contributors may be used to endorse or promote products derived
** from this software without specific prior written permission.
**
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
int main(int argc, char *argv[])
{
QApplication::setDesktopSettingsAware(false);
QApplication app(argc, argv);
...
return app.exec();
}
//! [0]
//! [1]
MyMainWidget::MyMainWidget(QWidget *parent)
:QWidget(parent)
{
connect(qApp, SIGNAL(commitDataRequest(QSessionManager)), SLOT(commitData(QSessionManager)));
}
void MyMainWidget::commitData(QSessionManager& manager)
{
if (manager.allowsInteraction()) {
int ret = QMessageBox::warning(
mainWindow,
tr("My Application"),
tr("Save changes to document?"),
QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
switch (ret) {
case QMessageBox::Save:
manager.release();
if (!saveDocument())
manager.cancel();
break;
case QMessageBox::Discard:
break;
case QMessageBox::Cancel:
default:
manager.cancel();
}
} else {
// we did not get permission to interact, then
// do something reasonable instead
}
}
//! [1]
//! [2]
appname -session id
//! [2]
//! [3]
foreach (const QString &command, mySession.restartCommand())
do_something(command);
//! [3]
//! [4]
foreach (const QString &command, mySession.discardCommand())
do_something(command);
//! [4]

0
src/gui/doc/snippets/code/src_gui_kernel_qapplication_x11.cpp → src/gui/doc/snippets/code/src_gui_kernel_qguiapplication_x11.cpp
View File

4
src/gui/kernel/qguiapplication.cpp
View File

@ -2935,7 +2935,7 @@ static inline void applyWindowCursor(const QList<QWindow *> &l)
restoreOverrideCursor(), otherwise the stack will never be emptied.
Example:
\snippet code/src_gui_kernel_qapplication_x11.cpp 0
\snippet code/src_gui_kernel_qguiapplication_x11.cpp 0
\sa overrideCursor(), restoreOverrideCursor(), changeOverrideCursor(),
QWidget::setCursor()
@ -2995,7 +2995,7 @@ QStyleHints *QGuiApplication::styleHints()
This function must be called before creating the QGuiApplication object, like
this:
\snippet code/src_gui_kernel_qapplication.cpp 6
\snippet code/src_gui_kernel_qguiapplication.cpp 0
\sa desktopSettingsAware()
*/

50
src/gui/kernel/qsessionmanager.cpp
View File

@ -74,10 +74,11 @@ QT_BEGIN_NAMESPACE
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.
signals QGuiApplication::commitDataRequest() and
QGuiApplication::saveStateRequest(). 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
@ -94,7 +95,7 @@ QT_BEGIN_NAMESPACE
setRestartHint(), setProperty(), requestPhase2(). See the respective
function descriptions for further details.
\sa QApplication, {Session Management}
\sa QGuiApplication, {Session Management}
*/
@ -151,7 +152,7 @@ QSessionManager::~QSessionManager()
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()
\sa sessionKey(), QGuiApplication::sessionId()
*/
QString QSessionManager::sessionId() const
{
@ -169,7 +170,7 @@ QString QSessionManager::sessionId() const
The session key changes with every call of commitData() or saveState().
\sa sessionId(), QApplication::sessionKey()
\sa sessionId(), QGuiApplication::sessionKey()
*/
QString QSessionManager::sessionKey() const
{
@ -197,15 +198,15 @@ QString QSessionManager::sessionKey() const
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:
Here's an example of how an application's QGuiApplication::commitDataRequest()
might be implemented:
\snippet code/src_gui_kernel_qapplication.cpp 8
\snippet code/src_gui_kernel_qguiapplication.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()
\sa QGuiApplication::commitDataRequest(), release(), cancel()
*/
bool QSessionManager::allowsInteraction()
{
@ -261,8 +262,9 @@ void QSessionManager::cancel()
\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
We recommend setting the restart hint in QGuiApplication::saveStateRequest()
because most session managers perform a checkpoint shortly after an
application's
startup.
\sa restartHint()
@ -291,12 +293,13 @@ QSessionManager::RestartHint QSessionManager::restartHint() const
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
\snippet code/src_gui_kernel_qguiapplication.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.
The \c -session option is mandatory; otherwise QGuiApplication cannot
tell whether it has been restored or what the current session identifier
is.
See QGuiApplication::isSessionRestored() and
QGuiApplication::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
@ -318,7 +321,7 @@ void QSessionManager::setRestartCommand(const QStringList &command)
To iterate over the list, you can use the \l foreach pseudo-keyword:
\snippet code/src_gui_kernel_qapplication.cpp 10
\snippet code/src_gui_kernel_qguiapplication.cpp 10
\sa setRestartCommand(), restartHint()
*/
@ -344,7 +347,7 @@ void QSessionManager::setDiscardCommand(const QStringList &command)
To iterate over the list, you can use the \l foreach pseudo-keyword:
\snippet code/src_gui_kernel_qapplication.cpp 11
\snippet code/src_gui_kernel_qguiapplication.cpp 11
\sa setDiscardCommand(), restartCommand(), setRestartCommand()
*/
@ -396,9 +399,10 @@ bool QSessionManager::isPhase2() const
/*!
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.
application may then return immediately from the
QGuiApplication::commitDataRequest() or QApplication::saveStateRequest()
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

2
src/gui/kernel/qstylehints.cpp
View File

@ -106,7 +106,7 @@ int QStyleHints::mouseDoubleClickInterval() const
and the current position (e.g. in the mouse move event) is \c currentPos,
you can find out if a drag should be started with code like this:
\snippet code/src_gui_kernel_qapplication.cpp 7
\snippet code/src_gui_kernel_qguiapplication.cpp 6
\sa startDragTime(), QPoint::manhattanLength(), {Drag and Drop}
*/

9
src/plugins/platforms/xcb/qxcbsessionmanager.h
View File

@ -43,6 +43,15 @@
#ifndef QXCBSESSIONMANAGER_H
#define QXCBSESSIONMANAGER_H
//
// W A R N I N G
// -------------
//
// This file is part of the QPA API and is not meant to be used
// in applications. Usage of this API may make your code
// source and binary incompatible with future versions of Qt.
//
#include <qpa/qplatformsessionmanager.h>
QT_BEGIN_NAMESPACE

2
src/widgets/kernel/qapplication.cpp
View File

@ -2647,7 +2647,7 @@ void QApplication::setStartDragDistance(int l)
and the current position (e.g. in the mouse move event) is \c currentPos,
you can find out if a drag should be started with code like this:
\snippet code/src_gui_kernel_qapplication.cpp 7
\snippet code/src_gui_kernel_qapplication.cpp 6
Qt uses this value internally, e.g. in QFileDialog.