From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/session.html | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 doc/html/session.html (limited to 'doc/html/session.html') diff --git a/doc/html/session.html b/doc/html/session.html new file mode 100644 index 000000000..3cd66010c --- /dev/null +++ b/doc/html/session.html @@ -0,0 +1,152 @@ + + + + + +Session Management + + + + + + + +

Session Management

+ + + +

Definitions +

A session is a group of running applications, each of which has a +particular state. The session is controlled by a service called the session manager. The applications participating in the session are +called session 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 session 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. +

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! +

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 TQApplication::commitData() method. +

X11 has supported complete session management since X11R6. +

Getting session management to work with TQt +

Start by reimplementing TQApplication::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: +

Example code to this dialog can be found in the documentation of TQSessionManager::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 TQApplication::saveState(). All state data you are saving in this +function, should be marked with the session identifier TQApplication::sessionId(). This application specific identifier is +globally unique, so no clashes will occur. (See TQSessionManager for +information on saving/restoring the state of a particular TQt +application.) +

Restoration is usually done in the application's main() +function. Check if TQApplication::isSessionRestored() is TRUE. If +that's the case, use the session identifier TQApplication::sessionId() again to access your state data and restore +the state of the application. +

Important: 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 TQObject::setName()). When +restoring the application, you must ensure that all restored +top level widgets are given the same unique names they had before. +

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 xsm and is part of a standard X11R6 +installation. As always with X11, a useful and informative manual page +is provided. Using xsm is straightforward (apart from the clumsy +Athena-based user interface). Here's a simple approach: +

Run X11R6. +
Create a dot file .xsmstartup in your home directory which +contains the single line +
```
+xterm
+
```
+ +This tells xsm that the default/failsafe session is just an xterm +and nothing else. Otherwise xsm would try to invoke lots of +clients including the windowmanager twm, which isn't very helpful. +
Now launch 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 SESSION_MANAGER +environment variable points to the session manager you just started. +
Launch your application from the new xterm window. It will connect +itself automatically to the session manager. You can check with the ClientList push button whether the connect was successful.
+Note: Never keep the ClientList open when you +start or end session managed clients! Otherwise xsm is likely to +crash. +
Use the session manager's Checkpoint and Shutdown buttons +with different settings and see how your application behaves. The save +type local means that the clients should save their state. It +corresponds to the TQApplication::saveState() function. The global save type asks applications to save their unsaved changes in +permanent, globally accessible storage. It invokes TQApplication::commitData(). +
Whenever something crashes, blame xsm and not TQt. 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. +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1