You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
347 lines
18 KiB
347 lines
18 KiB
14 years ago
|
<!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>
|