1 files changed, 177 insertions, 0 deletions
diff --git a/doc/session.doc b/doc/session.doc
new file mode 100644
index 0000000..6f3185f
--- /dev/null
+++ b/doc/session.doc
@@ -0,0 +1,177 @@
+/****************************************************************************
+**
+** Qt session management overview documentation
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+\page session.html
+
+\title Session Management
+
+\section1  Definitions 
+
+A \e session is a group of running applications, each of which has a
+particular state. The session is controlled by a service called the \e
+session \e manager. The applications participating in the session are
+called \e session \e clients.
+
+The session manager issues commands to its clients on behalf of the
+user. These commands may cause clients to commit unsaved changes (for
+example by saving open files), to preserve their state for future
+sessions, or to terminate gracefully. The set of these operations is
+called \e session \e management.
+
+In the common case, a session consists of all applications that a
+user runs on their desktop at a time. Under Unix/X11, however, a
+session may include applications running on different computers and
+may span multiple displays.
+
+\section1  Shutting a session down 
+
+A session is shut down by the session manager, usually on behalf of
+the user when they want to log out. A system might also perform an
+automatic shutdown in an emergency situation, for example, if power is
+about to be lost. Clearly there is a significant difference between
+these types of shutdown. During the first, the user may want to
+interact with the application, specifying exactly which files should
+be saved and which should be discarded. In the latter case, there's no
+time for interaction. There may not even be a user sitting in front of
+the machine!
+
+
+\section1  Protocols and support on different platforms
+
+On Mac OS X and MS-Windows, there is nothing like complete session
+management for applications yet, i.e. no restoring of previous
+sessions. They do support graceful logouts where applications
+have the opportunity to cancel the process after getting confirmation
+from the user. This is the functionality that corresponds to the \l
+QApplication::commitData() method.
+
+X11 has supported complete session management since X11R6.
+
+\section1  Getting session management to work with Qt 
+
+Start by reimplementing \l QApplication::commitData() to
+enable your application to take part in the graceful logout process. If
+you are only targeting the MS-Windows platform, this is all you can
+and must provide. Ideally, your application should provide a shutdown
+dialog similar to the following:
+
+\img session.png A typical dialog on shutdown
+
+Example code to this dialog can be found in the documentation of \l
+QSessionManager::allowsInteraction().
+
+For complete session management (only supported on X11R6 at present),
+you must also take care of saving the application's state, and
+potentially of restoring the state in the next life cycle of the
+session. This saving is done by reimplementing \l
+QApplication::saveState(). All state data you are saving in this
+function, should be marked with the session identifier \l
+QApplication::sessionId(). This application specific identifier is
+globally unique, so no clashes will occur. (See \l QSessionManager for
+information on saving/restoring the state of a particular Qt
+application.)
+
+Restoration is usually done in the application's main()
+function. Check if \l QApplication::isSessionRestored() is \c TRUE. If
+that's the case, use the session identifier \l
+QApplication::sessionId() again to access your state data and restore
+the state of the application.
+
+<strong>Important:</strong> In order to allow the window manager to
+restore window attributes such as stacking order or geometry
+information, you must identify your top level widgets with 
+unique application-wide object names (see \l{QObject::setName()}). When
+restoring the application, you must ensure that all restored
+top level widgets are given the same unique names they had before.
+
+\section1  Testing and debugging session management 
+
+Session management support on Mac OS X and Windows is fairly limited
+due to the lack of this functionality in the operating system
+itself. Simply shut the session down and verify that your application
+behaves as expected. It may be useful to launch another application,
+usually the integrated development environment, before starting your
+application. This other application will get the shutdown message
+afterwards, thus permitting you to cancel the shutdown. Otherwise you
+would have to log in again after each test run, which is not a problem
+per se, but is time consuming.
+
+On Unix you can either use a desktop environment that supports
+standard X11R6 session management or, the recommended method, use the
+session manager reference implementation provided by the X Consortium.
+This sample manager is called \c xsm and is part of a standard X11R6
+installation. As always with X11, a useful and informative manual page
+is provided. Using \c xsm is straightforward (apart from the clumsy
+Athena-based user interface). Here's a simple approach:
+
+\list
+\i Run X11R6.
+\i Create a dot file \c .xsmstartup in your home directory which
+contains the single line
+\code
+xterm
+\endcode
+This tells \c xsm that the default/failsafe session is just an xterm
+and nothing else. Otherwise \c xsm would try to invoke lots of
+clients including the windowmanager \c twm, which isn't very helpful.
+\i Now launch \c xsm from another terminal window. Both a session
+manager window and the xterm will appear. The xterm has a nice
+property that sets it apart from all the other shells you are
+currently running: within its shell, the \c SESSION_MANAGER
+environment variable points to the session manager you just started.
+\i Launch your application from the new xterm window. It will connect
+itself automatically to the session manager. You can check with the \e
+ClientList push button whether the connect was successful.<br>
+<strong>Note:</strong> Never keep the \e ClientList open when you
+start or end session managed clients! Otherwise \c xsm is likely to
+crash.
+\i Use the session manager's \e Checkpoint and \e Shutdown buttons
+with different settings and see how your application behaves. The save
+type \e local means that the clients should save their state. It
+corresponds to the \l QApplication::saveState() function. The \e
+global save type asks applications to save their unsaved changes in
+permanent, globally accessible storage. It invokes \l
+QApplication::commitData().
+\i Whenever something crashes, blame \c xsm and not Qt. \c xsm is far
+from being a usable session manager on a user's desktop. It is,
+however, stable and useful enough to serve as testing environment.
+\endlist
+
+
+*/