/usr/share/qt5/doc/qtdoc/session.html is in qt5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- session.qdoc -->
<title>Session Management | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td ><a href="overviews-main.html#best-practices">Best Practice Guides</a></td><td >Session Management</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#shutting-a-session-down">Shutting a Session Down</a></li>
<li class="level1"><a href="#protocols-and-support-on-different-platforms">Protocols and Support on Different Platforms</a></li>
<li class="level1"><a href="#getting-session-management-to-work-with-qt">Getting Session Management to Work with Qt</a></li>
<li class="level1"><a href="#testing-and-debugging-session-management">Testing and Debugging Session Management</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Session Management</h1>
<span class="subtitle"></span>
<!-- $$$session.html-description -->
<div class="descr"> <a name="details"></a>
<p>A <i>session</i> is a group of running applications, each of which has a particular state. The session is controlled by a service called the <i>session</i> <i>manager</i>. The applications participating in the session are called <i>session clients</i>.</p>
<p>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 <i>session</i> <i>management</i>.</p>
<p>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.</p>
<a name="shutting-a-session-down"></a>
<h2 id="shutting-a-session-down">Shutting a Session Down</h2>
<p>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!</p>
<a name="protocols-and-support-on-different-platforms"></a>
<h2 id="protocols-and-support-on-different-platforms">Protocols and Support on Different Platforms</h2>
<p>On macOS, and Microsoft Windows versions prior to Windows 2000, there is nothing like complete session management for applications yet, i.e. no restoring of previous sessions. (Windows 2000 and XP provide "hibernation" where the entire memory is saved to disk and restored when the machine is restarted.) 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 <a href="../qtgui/qguiapplication.html#commitDataRequest">QGuiApplication::commitDataRequest</a>() signal.</p>
<p>X11 has supported complete session management since X11R6.</p>
<a name="getting-session-management-to-work-with-qt"></a>
<h2 id="getting-session-management-to-work-with-qt">Getting Session Management to Work with Qt</h2>
<p>Start by connecting a slot to the <a href="../qtgui/qguiapplication.html#commitDataRequest">QGuiApplication::commitDataRequest</a>() signal to enable your application to take part in the graceful logout process. If you are only targeting the Microsoft Windows platform, this is all you can and must provide. Ideally, your application should provide a shutdown dialog similar to the following:</p>
<p class="centerAlign"><img src="images/session.png" alt="A typical dialog on shutdown" /></p><p>Example code for this dialog can be found in the documentation of <a href="../qtgui/qsessionmanager.html#allowsInteraction">QSessionManager::allowsInteraction</a>().</p>
<p>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 implementing a slot connected to the <a href="../qtgui/qguiapplication.html#saveStateRequest">QGuiApplication::saveStateRequest</a>() signal. All state data you are saving in this function, should be marked with the session identifier <a href="../qtgui/qguiapplication.html#sessionId">QGuiApplication::sessionId</a>(). This application specific identifier is globally unique, so no clashes will occur. (See <a href="../qtgui/qsessionmanager.html">QSessionManager</a> for information on saving/restoring the state of a particular Qt application.)</p>
<p>Restoration is usually done in the application's main() function. Check if <a href="../qtgui/qguiapplication.html#isSessionRestored">QGuiApplication::isSessionRestored</a>() is <code>true</code>. If that's the case, use the session identifier <a href="../qtgui/qguiapplication.html#sessionId">QGuiApplication::sessionId</a>() again to access your state data and restore the state of the application.</p>
<p><b>Important:</b> 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 <a href="../qtcore/qobject.html#objectName-prop">QObject::setObjectName</a>()). When restoring the application, you must ensure that all restored top level widgets are given the same unique names they had before.</p>
<a name="testing-and-debugging-session-management"></a>
<h2 id="testing-and-debugging-session-management">Testing and Debugging Session Management</h2>
<p>Session management support on macOS 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.</p>
<p>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 <code>xsm</code> and is part of a standard X11R6 installation. As always with X11, a useful and informative manual page is provided. Using <code>xsm</code> is straightforward (apart from the clumsy Athena-based user interface). Here's a simple approach:</p>
<ul>
<li>Run X11R6.</li>
<li>Create a dot file <code>.xsmstartup</code> in your home directory which contains the single line<pre class="cpp">
xterm
</pre>
<p>This tells <code>xsm</code> that the default/failsafe session is just an xterm and nothing else. Otherwise <code>xsm</code> would try to invoke lots of clients including the windowmanager <code>twm</code>, which isn't very helpful.</p>
</li>
<li>Now launch <code>xsm</code> 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 <code>SESSION_MANAGER</code> environment variable points to the session manager you just started.</li>
<li>Launch your application from the new xterm window. It will connect itself automatically to the session manager. You can check with the <i>ClientList</i> push button whether the connect was successful.<p><b>Note: </b>Never keep the <i>ClientList</i> open when you start or end session managed clients! Otherwise <code>xsm</code> is likely to crash.</p></li>
<li>Use the session manager's <i>Checkpoint</i> and <i>Shutdown</i> buttons with different settings and see how your application behaves. The save type <i>local</i> means that the clients should save their state. It corresponds to the <a href="../qtgui/qguiapplication.html#saveStateRequest">QGuiApplication::saveStateRequest</a>() signal. The <i>global</i> save type asks applications to save their unsaved changes in permanent, globally accessible storage. It invokes <a href="../qtgui/qguiapplication.html#commitDataRequest">QGuiApplication::commitDataRequest</a>().</li>
<li>Whenever something crashes, blame <code>xsm</code> and not Qt. <code>xsm</code> 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.</li>
</ul>
</div>
<!-- @@@session.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|