[556] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[651] | 3 | ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[556] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation ([email protected])
|
---|
| 6 | **
|
---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
| 8 | **
|
---|
| 9 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
| 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
| 13 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
| 14 | ** a written agreement between you and Nokia.
|
---|
| 15 | **
|
---|
| 16 | ** GNU Lesser General Public License Usage
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Lesser
|
---|
| 18 | ** General Public License version 2.1 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file LICENSE.LGPL included in the
|
---|
| 20 | ** packaging of this file. Please review the following information to
|
---|
| 21 | ** ensure the GNU Lesser General Public License version 2.1 requirements
|
---|
| 22 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
|
---|
| 23 | **
|
---|
| 24 | ** In addition, as a special exception, Nokia gives you certain additional
|
---|
| 25 | ** rights. These rights are described in the Nokia Qt LGPL Exception
|
---|
| 26 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
|
---|
| 27 | **
|
---|
| 28 | ** GNU General Public License Usage
|
---|
| 29 | ** Alternatively, this file may be used under the terms of the GNU
|
---|
| 30 | ** General Public License version 3.0 as published by the Free Software
|
---|
| 31 | ** Foundation and appearing in the file LICENSE.GPL included in the
|
---|
| 32 | ** packaging of this file. Please review the following information to
|
---|
| 33 | ** ensure the GNU General Public License version 3.0 requirements will be
|
---|
| 34 | ** met: http://www.gnu.org/copyleft/gpl.html.
|
---|
| 35 | **
|
---|
| 36 | ** If you have questions regarding the use of this file, please contact
|
---|
| 37 | ** Nokia at [email protected].
|
---|
| 38 | ** $QT_END_LICENSE$
|
---|
| 39 | **
|
---|
| 40 | ****************************************************************************/
|
---|
| 41 |
|
---|
| 42 | /*!
|
---|
| 43 | \page session.html
|
---|
| 44 | \title Session Management
|
---|
| 45 |
|
---|
| 46 | \ingroup best-practices
|
---|
| 47 |
|
---|
| 48 | A \e session is a group of running applications, each of which has a
|
---|
| 49 | particular state. The session is controlled by a service called the \e
|
---|
| 50 | session \e manager. The applications participating in the session are
|
---|
| 51 | called \e{session clients}.
|
---|
| 52 |
|
---|
| 53 | The session manager issues commands to its clients on behalf of the
|
---|
| 54 | user. These commands may cause clients to commit unsaved changes (for
|
---|
| 55 | example by saving open files), to preserve their state for future
|
---|
| 56 | sessions, or to terminate gracefully. The set of these operations is
|
---|
| 57 | called \e session \e management.
|
---|
| 58 |
|
---|
| 59 | In the common case, a session consists of all applications that a
|
---|
| 60 | user runs on their desktop at a time. Under Unix/X11, however, a
|
---|
| 61 | session may include applications running on different computers and
|
---|
| 62 | may span multiple displays.
|
---|
| 63 |
|
---|
| 64 | \section1 Shutting a Session Down
|
---|
| 65 |
|
---|
| 66 | A session is shut down by the session manager, usually on behalf of
|
---|
| 67 | the user when they want to log out. A system might also perform an
|
---|
| 68 | automatic shutdown in an emergency situation, for example, if power is
|
---|
| 69 | about to be lost. Clearly there is a significant difference between
|
---|
| 70 | these types of shutdown. During the first, the user may want to
|
---|
| 71 | interact with the application, specifying exactly which files should
|
---|
| 72 | be saved and which should be discarded. In the latter case, there's no
|
---|
| 73 | time for interaction. There may not even be a user sitting in front of
|
---|
| 74 | the machine!
|
---|
| 75 |
|
---|
| 76 |
|
---|
| 77 | \section1 Protocols and Support on Different Platforms
|
---|
| 78 |
|
---|
| 79 | On Mac OS X, and Microsoft Windows versions prior to Windows 2000,
|
---|
| 80 | there is nothing like complete session management for applications
|
---|
| 81 | yet, i.e. no restoring of previous sessions. (Windows 2000 and XP
|
---|
| 82 | provide "hibernation" where the entire memory is saved to disk and
|
---|
| 83 | restored when the machine is restarted.) They do support graceful
|
---|
| 84 | logouts where applications have the opportunity to cancel the process
|
---|
| 85 | after getting confirmation from the user. This is the functionality
|
---|
| 86 | that corresponds to the QApplication::commitData() method.
|
---|
| 87 |
|
---|
| 88 | X11 has supported complete session management since X11R6.
|
---|
| 89 |
|
---|
| 90 | \section1 Getting Session Management to Work with Qt
|
---|
| 91 |
|
---|
| 92 | Start by reimplementing QApplication::commitData() to
|
---|
| 93 | enable your application to take part in the graceful logout process. If
|
---|
| 94 | you are only targeting the Microsoft Windows platform, this is all you can
|
---|
| 95 | and must provide. Ideally, your application should provide a shutdown
|
---|
| 96 | dialog similar to the following:
|
---|
| 97 |
|
---|
| 98 | \img session.png A typical dialog on shutdown
|
---|
| 99 |
|
---|
| 100 | Example code for this dialog can be found in the documentation of
|
---|
| 101 | QSessionManager::allowsInteraction().
|
---|
| 102 |
|
---|
| 103 | For complete session management (only supported on X11R6 at present),
|
---|
| 104 | you must also take care of saving the application's state, and
|
---|
| 105 | potentially of restoring the state in the next life cycle of the
|
---|
| 106 | session. This saving is done by reimplementing
|
---|
| 107 | QApplication::saveState(). All state data you are saving in this
|
---|
| 108 | function, should be marked with the session identifier
|
---|
| 109 | QApplication::sessionId(). This application specific identifier is
|
---|
| 110 | globally unique, so no clashes will occur. (See QSessionManager for
|
---|
| 111 | information on saving/restoring the state of a particular Qt
|
---|
| 112 | application.)
|
---|
| 113 |
|
---|
| 114 | Restoration is usually done in the application's main()
|
---|
| 115 | function. Check if QApplication::isSessionRestored() is \c true. If
|
---|
| 116 | that's the case, use the session identifier
|
---|
| 117 | QApplication::sessionId() again to access your state data and restore
|
---|
| 118 | the state of the application.
|
---|
| 119 |
|
---|
| 120 | \bold{Important:} In order to allow the window manager to
|
---|
| 121 | restore window attributes such as stacking order or geometry
|
---|
| 122 | information, you must identify your top level widgets with
|
---|
| 123 | unique application-wide object names (see QObject::setObjectName()). When
|
---|
| 124 | restoring the application, you must ensure that all restored
|
---|
| 125 | top level widgets are given the same unique names they had before.
|
---|
| 126 |
|
---|
| 127 | \section1 Testing and Debugging Session Management
|
---|
| 128 |
|
---|
| 129 | Session management support on Mac OS X and Windows is fairly limited
|
---|
| 130 | due to the lack of this functionality in the operating system
|
---|
| 131 | itself. Simply shut the session down and verify that your application
|
---|
| 132 | behaves as expected. It may be useful to launch another application,
|
---|
| 133 | usually the integrated development environment, before starting your
|
---|
| 134 | application. This other application will get the shutdown message
|
---|
| 135 | afterwards, thus permitting you to cancel the shutdown. Otherwise you
|
---|
| 136 | would have to log in again after each test run, which is not a problem
|
---|
| 137 | per se, but is time consuming.
|
---|
| 138 |
|
---|
| 139 | On Unix you can either use a desktop environment that supports
|
---|
| 140 | standard X11R6 session management or, the recommended method, use the
|
---|
| 141 | session manager reference implementation provided by the X Consortium.
|
---|
| 142 | This sample manager is called \c xsm and is part of a standard X11R6
|
---|
| 143 | installation. As always with X11, a useful and informative manual page
|
---|
| 144 | is provided. Using \c xsm is straightforward (apart from the clumsy
|
---|
| 145 | Athena-based user interface). Here's a simple approach:
|
---|
| 146 |
|
---|
| 147 | \list
|
---|
| 148 | \i Run X11R6.
|
---|
| 149 | \i Create a dot file \c .xsmstartup in your home directory which
|
---|
| 150 | contains the single line
|
---|
| 151 | \snippet doc/src/snippets/code/doc_src_session.qdoc 0
|
---|
| 152 | This tells \c xsm that the default/failsafe session is just an xterm
|
---|
| 153 | and nothing else. Otherwise \c xsm would try to invoke lots of
|
---|
| 154 | clients including the windowmanager \c twm, which isn't very helpful.
|
---|
| 155 | \i Now launch \c xsm from another terminal window. Both a session
|
---|
| 156 | manager window and the xterm will appear. The xterm has a nice
|
---|
| 157 | property that sets it apart from all the other shells you are
|
---|
| 158 | currently running: within its shell, the \c SESSION_MANAGER
|
---|
| 159 | environment variable points to the session manager you just started.
|
---|
| 160 | \i Launch your application from the new xterm window. It will connect
|
---|
| 161 | itself automatically to the session manager. You can check with the \e
|
---|
| |
---|