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/qsessionmanager.html | 346 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 doc/html/qsessionmanager.html (limited to 'doc/html/qsessionmanager.html') diff --git a/doc/html/qsessionmanager.html b/doc/html/qsessionmanager.html new file mode 100644 index 000000000..9ad3ae9fb --- /dev/null +++ b/doc/html/qsessionmanager.html @@ -0,0 +1,346 @@ + + + + + +TQSessionManager Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQSessionManager Class Reference

+ +

The TQSessionManager class provides access to the session manager. +More... +

#include <qsessionmanager.h> +

Inherits TQObject. +

List of all member functions. +

Public Members

+ +

Detailed Description

+ + +The TQSessionManager class provides access to the session manager. +

+ +

The session manager is responsible for session management, most +importantly for interruption and resumption. A "session" is a kind +of record of the state of the system, e.g. which applications were +run at start up and which applications are currently running. 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. Use TQSettings to save and restore an individual +application's settings, e.g. window positions, recently used files, +etc. +

TQSessionManager provides an interface between the application and +the session manager so that the program can work well with the +session manager. In TQt, session management requests for action +are handled by the two virtual functions TQApplication::commitData() +and TQApplication::saveState(). Both provide a reference to +a session manager object as argument, to allow the application +to communicate with the session manager. +

During a session management action (i.e. within commitData() and +saveState()), no user interaction is possible unless the +application got explicit permission from the session manager. You +ask for permission by calling allowsInteraction() or, if it's really +urgent, allowsErrorInteraction(). TQt 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, TQSessionManager +offers further possibilites to fine-tune an application's session +management behavior: setRestartCommand(), setDiscardCommand(), +setRestartHint(), setProperty(), requestPhase2(). See the respective +function descriptions for further details. +

See also Main Window and Related Classes and Environment Classes. + +

Member Type Documentation

+

TQSessionManager::RestartHint

+

This enum type defines the circumstances under which this +application wants to be restarted by the session manager. The +current values are +

The default hint is RestartIfRunning. + +

Member Function Documentation

+

bool TQSessionManager::allowsErrorInteraction () +

+ +

This is similar to allowsInteraction(), but also tells the session +manager that an error occurred. Session managers may give error +interaction request 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. +

See also allowsInteraction(), release(), and cancel(). + +

bool TQSessionManager::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 TQApplication::commitData() +might be implemented: +

+void MyApplication::commitData( TQSessionManager& sm ) {
+    if ( sm.allowsInteraction() ) {
+        switch ( TQMessageBox::warning(
+                    yourMainWindow,
+                    tr("Application Name"),
+                    tr("Save changes to document Foo?"),
+                    tr("&Yes"),
+                    tr("&No"),
+                    tr("Cancel"),
+                    0, 2) ) {
+        case 0: // yes
+            sm.release();
+            // save document here; if saving fails, call sm.cancel()
+            break;
+        case 1: // continue without saving
+            break;
+        default: // cancel
+            sm.cancel();
+            break;
+        }
+    } else {
+        // we did not get permission to interact, then
+        // do something reasonable instead.
+    }
+}
+
+ +

If an error occurred within the application while saving its data, +you may want to try allowsErrorInteraction() instead. +

See also TQApplication::commitData(), release(), and cancel(). + +

void TQSessionManager::cancel () +

+ +

Tells the session manager to cancel the shutdown process. Applications +should not call this function without first asking the user. +

See also allowsInteraction() and allowsErrorInteraction(). + +

+

TQStringList TQSessionManager::discardCommand () const +

+ +

Returns the currently set discard command. +

Note that if you want to iterate over the list, you should +iterate over a copy, e.g. +

+    TQStringList list = mySession.discardCommand();
+    TQStringList::Iterator it = list.begin();
+    while( it != list.end() ) {
+        myProcessing( *it );
+        ++it;
+    }
+
+ +

See also setDiscardCommand(), restartCommand(), and setRestartCommand(). + +

void * TQSessionManager::handle () const +

+ +

X11 only: returns a handle to the current SmcConnection. + +

bool TQSessionManager::isPhase2 () const +

+ +

Returns TRUE if the session manager is currently performing a second +session management phase; otherwise returns FALSE. +

See also requestPhase2(). + +

void TQSessionManager::release () +

+ +

Releases the session manager's interaction semaphore after an +interaction phase. +

See also allowsInteraction() and allowsErrorInteraction(). + +

void TQSessionManager::requestPhase2 () +

+ +

Requests a second session management phase for the application. The +application may then return immediately from the +TQApplication::commitData() or TQApplication::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 that if another application has requested a second phase it +may get called before, simultaneously with, or after your +application's second phase. +

See also isPhase2(). + +

TQStringList TQSessionManager::restartCommand () const +

+ +

Returns the currently set restart command. +

Note that if you want to iterate over the list, you should +iterate over a copy, e.g. +

+    TQStringList list = mySession.restartCommand();
+    TQStringList::Iterator it = list.begin();
+    while( it != list.end() ) {
+        myProcessing( *it );
+        ++it;
+    }
+
+ +

See also setRestartCommand() and restartHint(). + +

RestartHint TQSessionManager::restartHint () const +

+ +

Returns the application's current restart hint. The default is +RestartIfRunning. +

See also setRestartHint(). + +

TQString TQSessionManager::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 that earlier session. +

See also sessionKey() and TQApplication::sessionId(). + +

TQString TQSessionManager::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(). +

See also sessionId() and TQApplication::sessionKey(). + +

void TQSessionManager::setDiscardCommand ( const TQStringList & ) +

+ +

See also discardCommand() and setRestartCommand(). + +

void TQSessionManager::setManagerProperty ( const TQString & name, const TQStringList & value ) +

+ +

Low-level write access to the application's identification and state +record are kept in the session manager. +

The property called name has its value set to the string list value. + +

void TQSessionManager::setManagerProperty ( const TQString & name, const TQString & value ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Low-level write access to the application's identification and state +records are kept in the session manager. +

The property called name has its value set to the string value. + +

void TQSessionManager::setRestartCommand ( const TQStringList & command ) +

+ +

If the session manager is capable of restoring sessions it will +execute command in order to restore the application. The command +defaults to +

+        appname -session id
+
+ +

The -session option is mandatory; otherwise TQApplication cannot +tell whether it has been restored or what the current session +identifier is. See TQApplication::isSessionRestored() and +TQApplication::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 TQSettings, or 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. +

See also restartCommand(), setDiscardCommand(), and setRestartHint(). + +

void TQSessionManager::setRestartHint ( RestartHint hint ) +

+ +

Sets the application's restart hint to hint. On application +startup the hint is set to RestartIfRunning. +

Note that these flags are only hints, a session manager may or may +not respect them. +

We recommend setting the restart hint in TQApplication::saveState() +because most session managers perform a checkpoint shortly after an +application's startup. +

See also restartHint(). + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1