diff options
Diffstat (limited to 'doc/html/qsessionmanager.html')
| -rw-r--r-- | doc/html/qsessionmanager.html | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/doc/html/qsessionmanager.html b/doc/html/qsessionmanager.html new file mode 100644 index 0000000..167a236 --- /dev/null +++ b/doc/html/qsessionmanager.html @@ -0,0 +1,346 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/kernel/qapplication.cpp:4067 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>QSessionManager Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSessionManager Class Reference</h1> + +<p>The QSessionManager class provides access to the session manager. +<a href="#details">More...</a> +<p><tt>#include <<a href="qsessionmanager-h.html">qsessionmanager.h</a>></tt> +<p>Inherits <a href="qobject.html">QObject</a>. +<p><a href="qsessionmanager-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn>QString <a href="#sessionId"><b>sessionId</b></a> () const</li> +<li class=fn>QString <a href="#sessionKey"><b>sessionKey</b></a> () const</li> +<li class=fn>void * <a href="#handle"><b>handle</b></a> () const</li> +<li class=fn>bool <a href="#allowsInteraction"><b>allowsInteraction</b></a> ()</li> +<li class=fn>bool <a href="#allowsErrorInteraction"><b>allowsErrorInteraction</b></a> ()</li> +<li class=fn>void <a href="#release"><b>release</b></a> ()</li> +<li class=fn>void <a href="#cancel"><b>cancel</b></a> ()</li> +<li class=fn>enum <a href="#RestartHint-enum"><b>RestartHint</b></a> { RestartIfRunning, RestartAnyway, RestartImmediately, RestartNever }</li> +<li class=fn>void <a href="#setRestartHint"><b>setRestartHint</b></a> ( RestartHint hint )</li> +<li class=fn>RestartHint <a href="#restartHint"><b>restartHint</b></a> () const</li> +<li class=fn>void <a href="#setRestartCommand"><b>setRestartCommand</b></a> ( const QStringList & command )</li> +<li class=fn>QStringList <a href="#restartCommand"><b>restartCommand</b></a> () const</li> +<li class=fn>void <a href="#setDiscardCommand"><b>setDiscardCommand</b></a> ( const QStringList & )</li> +<li class=fn>QStringList <a href="#discardCommand"><b>discardCommand</b></a> () const</li> +<li class=fn>void <a href="#setManagerProperty-2"><b>setManagerProperty</b></a> ( const QString & name, const QString & value )</li> +<li class=fn>void <a href="#setManagerProperty"><b>setManagerProperty</b></a> ( const QString & name, const QStringList & value )</li> +<li class=fn>bool <a href="#isPhase2"><b>isPhase2</b></a> () const</li> +<li class=fn>void <a href="#requestPhase2"><b>requestPhase2</b></a> ()</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + +The QSessionManager class provides access to the session manager. +<p> + +<p> 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 <a href="qsettings.html">QSettings</a> to save and restore an individual +application's settings, e.g. window positions, recently used files, +etc. +<p> 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 <a href="qapplication.html#commitData">QApplication::commitData</a>() +and <a href="qapplication.html#saveState">QApplication::saveState</a>(). Both provide a reference to +a session manager object as argument, to allow the application +to communicate with the session manager. +<p> During a session management action (i.e. within commitData() and +saveState()), no user interaction is possible <em>unless</em> the +application got explicit permission from the session manager. You +ask for permission by calling <a href="#allowsInteraction">allowsInteraction</a>() or, if it's really +urgent, <a href="#allowsErrorInteraction">allowsErrorInteraction</a>(). Qt does not enforce this, but the +session manager may. +<p> You can try to abort the shutdown process by calling <a href="#cancel">cancel</a>(). The +default commitData() function does this if some top-level window +rejected its closeEvent(). +<p> For sophisticated session managers provided on Unix/X11, QSessionManager +offers further possibilites to fine-tune an application's session +management behavior: <a href="#setRestartCommand">setRestartCommand</a>(), <a href="#setDiscardCommand">setDiscardCommand</a>(), +<a href="#setRestartHint">setRestartHint</a>(), <a href="qobject.html#setProperty">setProperty</a>(), <a href="#requestPhase2">requestPhase2</a>(). See the respective +function descriptions for further details. +<p>See also <a href="application.html">Main Window and Related Classes</a> and <a href="environment.html">Environment Classes</a>. + +<hr><h2>Member Type Documentation</h2> +<h3 class=fn><a name="RestartHint-enum"></a>QSessionManager::RestartHint</h3> +<p> This enum type defines the circumstances under which this +application wants to be restarted by the session manager. The +current values are +<ul> +<li><tt>QSessionManager::RestartIfRunning</tt> - if the application is still running when +the session is shut down, it wants to be restarted at the start of +the next session. +<li><tt>QSessionManager::RestartAnyway</tt> - the application wants to be started at the +start of the next session, no matter what. (This is useful for +utilities that run just after startup and then quit.) +<li><tt>QSessionManager::RestartImmediately</tt> - the application wants to be started +immediately whenever it is not running. +<li><tt>QSessionManager::RestartNever</tt> - the application does not want to be restarted +automatically. +</ul><p> The default hint is <a href="#RestartHint-enum">RestartIfRunning</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn>bool <a name="allowsErrorInteraction"></a>QSessionManager::allowsErrorInteraction () +</h3> + +<p> This is similar to <a href="#allowsInteraction">allowsInteraction</a>(), 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. +<p> <p>See also <a href="#allowsInteraction">allowsInteraction</a>(), <a href="#release">release</a>(), and <a href="#cancel">cancel</a>(). + +<h3 class=fn>bool <a name="allowsInteraction"></a>QSessionManager::allowsInteraction () +</h3> + +<p> Asks the session manager for permission to interact with the +user. Returns TRUE if interaction is permitted; otherwise +returns FALSE. +<p> 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. +<p> When the interaction is completed we strongly recommend releasing the +user interaction semaphore with a call to <a href="#release">release</a>(). 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.) +<p> 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 <a href="#cancel">cancel</a>(). +<p> Here's an example of how an application's <a href="qapplication.html#commitData">QApplication::commitData</a>() +might be implemented: +<p> <pre> +void MyApplication::commitData( QSessionManager& sm ) { + if ( sm.<a href="#allowsInteraction">allowsInteraction</a>() ) { + switch ( QMessageBox::<a href="qmessagebox.html#warning">warning</a>( + yourMainWindow, + <a href="qobject.html#tr">tr</a>("Application Name"), + <a href="qobject.html#tr">tr</a>("Save changes to document Foo?"), + <a href="qobject.html#tr">tr</a>("&Yes"), + <a href="qobject.html#tr">tr</a>("&No"), + <a href="qobject.html#tr">tr</a>("Cancel"), + 0, 2) ) { + case 0: // yes + sm.<a href="#release">release</a>(); + // save document here; if saving fails, call sm.<a href="#cancel">cancel</a>() + break; + case 1: // continue without saving + break; + default: // cancel + sm.<a href="#cancel">cancel</a>(); + break; + } + } else { + // we did not get permission to interact, then + // do something reasonable instead. + } +} +</pre> + +<p> If an error occurred within the application while saving its data, +you may want to try <a href="#allowsErrorInteraction">allowsErrorInteraction</a>() instead. +<p> <p>See also <a href="qapplication.html#commitData">QApplication::commitData</a>(), <a href="#release">release</a>(), and <a href="#cancel">cancel</a>(). + +<h3 class=fn>void <a name="cancel"></a>QSessionManager::cancel () +</h3> + +<p> Tells the session manager to cancel the shutdown process. Applications +should not call this function without first asking the user. +<p> <p>See also <a href="#allowsInteraction">allowsInteraction</a>() and <a href="#allowsErrorInteraction">allowsErrorInteraction</a>(). + +<p> +<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="discardCommand"></a>QSessionManager::discardCommand () const +</h3> + +<p> Returns the currently set discard command. +<p> Note that if you want to iterate over the list, you should +iterate over a copy, e.g. +<pre> + <a href="qstringlist.html">QStringList</a> list = mySession.discardCommand(); + QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>(); + while( it != list.<a href="qvaluelist.html#end">end</a>() ) { + myProcessing( *it ); + ++it; + } + </pre> + +<p> <p>See also <a href="#setDiscardCommand">setDiscardCommand</a>(), <a href="#restartCommand">restartCommand</a>(), and <a href="#setRestartCommand">setRestartCommand</a>(). + +<h3 class=fn>void * <a name="handle"></a>QSessionManager::handle () const +</h3> + +<p> X11 only: returns a handle to the current <tt>SmcConnection</tt>. + +<h3 class=fn>bool <a name="isPhase2"></a>QSessionManager::isPhase2 () const +</h3> + +<p> Returns TRUE if the session manager is currently performing a second +session management phase; otherwise returns FALSE. +<p> <p>See also <a href="#requestPhase2">requestPhase2</a>(). + +<h3 class=fn>void <a name="release"></a>QSessionManager::release () +</h3> + +<p> Releases the session manager's interaction semaphore after an +interaction phase. +<p> <p>See also <a href="#allowsInteraction">allowsInteraction</a>() and <a href="#allowsErrorInteraction">allowsErrorInteraction</a>(). + +<h3 class=fn>void <a name="requestPhase2"></a>QSessionManager::requestPhase2 () +</h3> + +<p> Requests a second session management phase for the application. The +application may then return immediately from the +<a href="qapplication.html#commitData">QApplication::commitData</a>() or <a href="qapplication.html#saveState">QApplication::saveState</a>() function, +and they will be called again once most or all other applications have +finished their session management. +<p> 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. +<p> Note that if another application has requested a second phase it +may get called before, simultaneously with, or after your +application's second phase. +<p> <p>See also <a href="#isPhase2">isPhase2</a>(). + +<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="restartCommand"></a>QSessionManager::restartCommand () const +</h3> + +<p> Returns the currently set restart command. +<p> Note that if you want to iterate over the list, you should +iterate over a copy, e.g. +<pre> + <a href="qstringlist.html">QStringList</a> list = mySession.restartCommand(); + QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>(); + while( it != list.<a href="qvaluelist.html#end">end</a>() ) { + myProcessing( *it ); + ++it; + } + </pre> + +<p> <p>See also <a href="#setRestartCommand">setRestartCommand</a>() and <a href="#restartHint">restartHint</a>(). + +<h3 class=fn><a href="qsessionmanager.html#RestartHint-enum">RestartHint</a> <a name="restartHint"></a>QSessionManager::restartHint () const +</h3> + +<p> Returns the application's current restart hint. The default is +<a href="#RestartHint-enum">RestartIfRunning</a>. +<p> <p>See also <a href="#setRestartHint">setRestartHint</a>(). + +<h3 class=fn><a href="qstring.html">QString</a> <a name="sessionId"></a>QSessionManager::sessionId () const +</h3> + +<p> Returns the identifier of the current session. +<p> If the application has been restored from an earlier session, this +identifier is the same as it was in that earlier session. +<p> <p>See also <a href="#sessionKey">sessionKey</a>() and <a href="qapplication.html#sessionId">QApplication::sessionId</a>(). + +<h3 class=fn><a href="qstring.html">QString</a> <a name="sessionKey"></a>QSessionManager::sessionKey () const +</h3> + +<p> Returns the session key in the current session. +<p> If the application has been restored from an earlier session, this +key is the same as it was when the previous session ended. +<p> The session key changes with every call of commitData() or +saveState(). +<p> <p>See also <a href="#sessionId">sessionId</a>() and <a href="qapplication.html#sessionKey">QApplication::sessionKey</a>(). + +<h3 class=fn>void <a name="setDiscardCommand"></a>QSessionManager::setDiscardCommand ( const <a href="qstringlist.html">QStringList</a> & ) +</h3> + +<p> <p>See also <a href="#discardCommand">discardCommand</a>() and <a href="#setRestartCommand">setRestartCommand</a>(). + +<h3 class=fn>void <a name="setManagerProperty"></a>QSessionManager::setManagerProperty ( const <a href="qstring.html">QString</a> & name, const <a href="qstringlist.html">QStringList</a> & value ) +</h3> + +<p> Low-level write access to the application's identification and state +record are kept in the session manager. +<p> The property called <em>name</em> has its value set to the string list <em>value</em>. + +<h3 class=fn>void <a name="setManagerProperty-2"></a>QSessionManager::setManagerProperty ( const <a href="qstring.html">QString</a> & name, const <a href="qstring.html">QString</a> & value ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Low-level write access to the application's identification and state +records are kept in the session manager. +<p> The property called <em>name</em> has its value set to the string <em>value</em>. + +<h3 class=fn>void <a name="setRestartCommand"></a>QSessionManager::setRestartCommand ( const <a href="qstringlist.html">QStringList</a> & command ) +</h3> + +<p> If the session manager is capable of restoring sessions it will +execute <em>command</em> in order to restore the application. The command +defaults to +<p> <pre> + appname -session id + </pre> + +<p> The <tt>-session</tt> option is mandatory; otherwise <a href="qapplication.html">QApplication</a> cannot +tell whether it has been restored or what the current session +identifier is. See <a href="qapplication.html#isSessionRestored">QApplication::isSessionRestored</a>() and +<a href="qapplication.html#sessionId">QApplication::sessionId</a>() for details. +<p> 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 <a href="qsettings.html">QSettings</a>, or temporary files +or a database for this purpose. By marking the data with the unique +<a href="#sessionId">sessionId</a>(), you will be able to restore the application in a future +session. +<p> <p>See also <a href="#restartCommand">restartCommand</a>(), <a href="#setDiscardCommand">setDiscardCommand</a>(), and <a href="#setRestartHint">setRestartHint</a>(). + +<h3 class=fn>void <a name="setRestartHint"></a>QSessionManager::setRestartHint ( <a href="qsessionmanager.html#RestartHint-enum">RestartHint</a> hint ) +</h3> + +<p> Sets the application's restart hint to <em>hint</em>. On application +startup the hint is set to <a href="#RestartHint-enum">RestartIfRunning</a>. +<p> Note that these flags are only hints, a session manager may or may +not respect them. +<p> We recommend setting the restart hint in <a href="qapplication.html#saveState">QApplication::saveState</a>() +because most session managers perform a checkpoint shortly after an +application's startup. +<p> <p>See also <a href="#restartHint">restartHint</a>(). + +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">Qt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |