qsessionmanager.3qt

来自「tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件」· 3QT 代码 · 共 218 行

.TH QSessionManager 3qt "6 July 1999" "Troll Tech AS" \" -*- nroff -*-
.\" Copyright 1992-1999 Troll Tech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QSessionManager \- Access to the session manager
.SH SYNOPSIS
.br
.PP
\fC#include <qsessionmanager.h>\fR
.PP
Inherits QObject.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "QString \fBsessionId\fR () const"
.br
.ti -1c
.BI "bool \fBallowsInteraction\fR ()"
.br
.ti -1c
.BI "bool \fBallowsErrorInteraction\fR ()"
.br
.ti -1c
.BI "void \fBrelease\fR ()"
.br
.ti -1c
.BI "void \fBcancel\fR ()"
.br
.ti -1c
.BI "enum \fBRestartHint\fR { RestartIfRunning, RestartAnyway, RestartImmediately, RestartNever }"
.br
.ti -1c
.BI "void \fBsetRestartHint\fR ( RestartHint )"
.br
.ti -1c
.BI "RestartHint \fBrestartHint\fR () const"
.br
.ti -1c
.BI "void \fBsetRestartCommand\fR ( const QStringList & )"
.br
.ti -1c
.BI "QStringList \fBrestartCommand\fR () const"
.br
.ti -1c
.BI "void \fBsetDiscardCommand\fR ( const QStringList & )"
.br
.ti -1c
.BI "QStringList \fBdiscardCommand\fR () const"
.br
.ti -1c
.BI "void \fBsetProperty\fR ( const QString & " "name" ", const QString & value )"
.br
.ti -1c
.BI "void \fBsetProperty\fR ( const QString & " "name" ", const QStringList & value )"
.br
.ti -1c
.BI "bool \fBisPhase2\fR () const"
.br
.ti -1c
.BI "void \fBrequestPhase2\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QSessionManager class provides access to the session manager.
.PP
The QSessionManager class provides access to the session manager during a session management action. In Qt, session management actions are handled in the two virtual functions QApplication::commitData() and QApplication::saveState(). Both functions provide a reference to a session manager object as argument, thus allowing the application to communicate with the session manager.
.PP
During a session management action, i.e. within one of the two mentioned functions, no user interaction is possible, \fIunless\fR the application got explicit permission from the session manager. An ordinary permission can be requested with allowsInteraction(). With allowsErrorInteraction(), applications can ask for a higher priority interaction permission in case an error occured.
.PP
Another important function is cancel(), which asks the session manager to cancel the shutdown process.
.PP
For sophisticated session managers as provided on Unix, QSessionManager offers further possibilites to finetune an application's session management behaviour: setRestartCommand(), setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2(). Please see the respective function descriptions for further details.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "bool QSessionManager::allowsErrorInteraction ()"
Like allowsInteraction() but tells the session manager in addition that an error occured. Session managers may treat error interaction requests with higher priority. That means it is more likely that an error interaction is granted. However, you are still not guaranteed that the session manager will follow your request.
.PP
See also: allowsInteraction(), release() and cancel().
.SH "bool QSessionManager::allowsInteraction ()"
Asks the session manager for permission to interact with the user. Returns TRUE if the interaction was granted, FALSE otherwise.
.PP
The rationale behind this is to make it possible to synchronize user interaction during a shutdown. Fancy session managers on multitasking operating systems may ask all applications simultaniously to commit their data, which results in a much faster shutdown.
.PP
After the interaction is is recommended (though not necessary) to release the session manager 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.
.PP
If the user decides to cancel the shutdown process during the interaction phase, inform the session manager with a call to cancel().
.PP
Here's an example usage of the mentioned functions that may occur in the QApplication::commitData() function of an application:
.PP
.nf
.br
void MyApplication::commitData( QSessionManager& sm ) {
.br
    if ( sm.allowsInteraction() ) {
.br
        switch ( QMessageBox::warning( yourMainWindow, "Application Name",
.br
                                        "Save changes to Document Foo?",
.br
                                        tr("&Yes"),
.br
                                        tr("&No"),
.br
                                        tr("Cancel"),
.br
                                        0, 2) ) {
.br
        case 0: // yes
.br
            sm.release();
.br
            // save document here. If saving fails, call sm.cancel()
.br
            break;
.br
        case 1: // no
.br
            break;
.br
        default: // cancel
.br
            sm.cancel();
.br
            break;
.br
        }
.br
    } else {
.br
        // we did not get permission to interact, do something reasonable instead.
.br
    }
.br
}
.fi
.PP
If an error occured within the application while saving its data, you may want to use allowsErrorInteraction() instead.
.PP
See also: QApplication::commitData(), release() and cancel().
.SH "void QSessionManager::cancel ()"
Tells the session manager to cancel the shutdown process. Applications should not call this function without asking the user first.
.PP
See also: allowsInteraction() and allowsErrorInteraction().
.SH "QStringList QSessionManager::discardCommand () const"
Returns the currently set discard command.
.PP
See also: setDiscardCommand(), restartCommand() and setRestartCommand().
.SH "bool QSessionManager::isPhase2 () const"
Returns whether the session manager is currently performing a second session management phase.
.PP
See also: requestPhase2().
.SH "void QSessionManager::release ()"
Releases the session manager after an interaction phase.
.PP
See also: allowsInteraction() and allowsErrorInteraction().
.SH "void QSessionManager::requestPhase2 ()"
Requests a second session management phase for the application. The application may then simply return from the QApplication::commitData() or QApplication::saveState() function. The respective function will be called again after the first session management phase has been finished, this time with isPhase2() returning TRUE.
.PP
The two phases are useful for applications like X11 window manager, that need to store informations about other application's windows and therefore have to wait until these applications finished their respective session management tasks.
.PP
See also: isPhase2().
.SH "QStringList QSessionManager::restartCommand () const"
Returns the currently set restart command.
.PP
See also: setRestartCommand() and restartHint().
.SH "QString QSessionManager::sessionId () const"
Returns the identifier of the current session.
.PP
If the application has been restored from an earlier session, this identifier is the same as it was in that previous session.
.PP
See also: QApplication::sessionId().
.SH "void QSessionManager::setDiscardCommand ( const QStringList & )"
See also: discardCommand() and setRestartCommand().
.SH "void QSessionManager::setProperty ( const QString & name, const QString & value )"
Low-level write access to the application's identification and state record kept in the session manager.
.SH "void QSessionManager::setProperty ( const QString & name, const QStringList & value )"
Low-level write access to the application's identification and state record kept in the session manager.
.SH "void QSessionManager::setRestartCommand ( const QStringList & command )"
If the session manager is capable of restoring sessions, it will execute \fIcommand\fR in order to restore the application. The command defaults to
.PP
.nf
.br
               appname -session  id
.fi
.PP
The \fC-session\fR option is mandatory, otherwise QApplication can not tell whether it has been restored or what the current session identifier is. See QApplication::isSessionRestored() and QApplication::sessionId() for details. If your application is very simply, it may be possible to store the entire application state in additional command line options. In general, this is a very bad idea, since command lines are often limited to a few hundred bytes. Instead, use 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.
.PP
See also: restartCommand(), setDiscardCommand() and setRestartHint().
.SH "void QSessionManager::setRestartHint ( RestartHint hint )"
Sets the application's restart hint to \fIhint.\fR The restart hint defines, under what circumstances an application should be restarted by the session manager in the next session.
.PP
The following values are possible:
.TP
\fCRestartIfRunning\fR - This is the default hint. If the application still runs by the time the session is shut down, it shall be restarted.
.TP
\fCRestartAnyway\fR - Restart the application in the next session, regardless whether it runs at the end of this session or not. This is in particulary useful for configuration utilities that just run during startup and quit themselves after finishing their task.
.TP
\fCRestartImmediately\fR - Ensure that the application runs all the time. If it exits during the session for whatever reason, restart it immediately. This might be useful for desktop utilities that are supposed to run permanentely, for example a file manager.
.TP
\fCRestartNever\fR - Do not restart this application under any circumstances.
.PP
The default hint is \fCRestartIfRunning.\fR Note that these flags are only hints, a session manager may or may not obey them.
.PP
Preferrably, the restart hint shall be defined in QApplication::saveState() since most session managers perform a checkpoint immediately after an application's startup.
.PP
See also:  restartHint().
.SH "SEE ALSO"
.BR http://www.troll.no/qt/qsessionmanager.html
.SH COPYRIGHT
Copyright 1992-1999 Troll Tech AS.  See the license file included in
the distribution for a complete license statement.
.SH AUTHOR
Generated automatically from the source code.