Difference between revisions of "Development/Tutorials/Session Management"

 
(44 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Session Management}}
+
This tutorial was updated and moved to https://develop.kde.org/docs/configuration/introduction/
  
{{Under Construction}}
+
[[Category:MovedDevelop]]
 
 
==About KDE and X11 session management==
 
 
 
KDE supports the legacy X11R4 and ICCCM session
 
management protocols.  Legacy applications that define the <tt>WM_COMMAND</tt>
 
property or support the <tt>WM_SAVE_YOURSELF</tt> protocol will be restarted
 
with the specified command.  The window geometries will be restored on a best
 
effort basis.
 
 
 
Since version 2.0, KDE also supports and uses the standard X11R6
 
session management protocol XSMP. The official documentation of the
 
standard can be download from the X Consortium's FTP server
 
[http://stuff.mit.edu/afs/sipb/contrib/doc/X11/hardcopy/SM/xsmp.PS.gz ftp.x.org].
 
 
 
Unlike these legacy protocols, the new X11R6 session management gives a
 
chance to save application dependent settings when you log out.  A text
 
editor, for instance, would save the names of the loaded files and would
 
reload them when you log in again.  Another major advantage of the new
 
protocol is the support for a clean and safe logout procedure even if the
 
users decides not to restore the session next time. The protocol gives
 
applications the possibility to interact with the user in case they are in
 
danger to lose some data, and to cancel the shutdown process if necessary.
 
 
 
==Further Reading==
 
 
 
An introductive overview of session management functionality and
 
the Qt API for it is available from [http://doc.trolltech.com/4.4/session.html doc.trolltech.com].
 
 
 
In KDE, the classes [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKApplication.html KApplication]
 
and [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow]
 
hide all the ugly details from the programmer. Basically, a
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKApplication.html KApplication] manages a
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKConfig.html KConfig] configuration object
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKApplication.html#8f88369c240d6d90a04d29b2761989d9 sessionConfig()]
 
for you, that your application can utilize to store session specific data.
 
 
 
Please read the respective class documentation, especially the one of
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow], for a detailed interface description. With the advanced
 
functionality in [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow], it's really just a matter of a few lines to get even a multi-window application to retains its state between
 
different user sessions.
 
 
 
==Implementing session management in your application==
 
 
 
Here's just a brief overview how things are done. Again, see the
 
respective class documentation for details.
 
 
 
===Add session management support to your main() function===
 
 
 
====For one kind of toplevel widget====
 
 
 
If your client has only one kind of toplevel widgets (which should be pretty usual) then you should use the RESTORE-macro for backwards compatibility with 3.1 and 3.0 branches.
 
 
 
Imagine you have an
 
application with a main window MyWindow inherited from
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow] (or from
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKXmlGuiWindow.html KXmlGuiWindow], which inherits from
 
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow]). In your main() function, you would then create/restore the
 
application windows with something like:
 
 
 
<code cppqt>
 
KApplication app;
 
if ( kapp->isSessionRestored() ) {
 
  RESTORE( MyWindow )
 
} else {
 
  // create default application as usual
 
  // for example:
 
  MyWindow* window = new MyWindow();
 
  window->show();
 
}
 
return app.exec();
 
</code>
 
 
 
====For several kinds of toplevel widget====
 
 
 
It is also possible to
 
restore different types of toplevel windows within one application. In
 
that case, the RESTORE macro is too primitive. If you have more than one
 
kind of toplevel widget (each derived from KMainWindow, of course), you
 
can use the templated kRestoreMainWindows global functions:
 
 
 
<code cppqt>
 
KApplication app;
 
if ( kapp->isSessionRestored() ) {
 
  kRestoreMainWindows< childMW1, childMW2, childMW3 >();
 
} else {
 
  // create default application as usual
 
  // for example:
 
  childMW1* window1 = new childMW1();
 
  childMW2* window2 = new childMW2();
 
  childMW3* window3 = new childMW3();
 
  window1->show();
 
  window2->show();
 
  window3->show();
 
}
 
</code>
 
 
 
Currently, these functions are provided for up to three template arguments.
 
 
 
===Reimplement some virtual functions of KMainWindow===
 
 
 
You reimplement the store/restore handlers in MyWindow to save and
 
restore all additional settings. For a text editor, that would be the
 
loaded files, for example:
 
 
 
<code cppqt>
 
void MyWindow::saveProperties( KConfig* )
 
{
 
  // save properties here
 
}
 
 
 
void MyWindow::readProperties( KConfig* )
 
{
 
  // read properties here
 
}
 
</code>
 
 
 
Note that standard settings like window sizes, toolbar settings
 
etc. are automatically handled.
 
 
 
==Appendix: Architecture of the KDE session manager==
 
 
 
The session management server in KDE is called '''ksmserver''' and it is
 
part of the '''kdebase''' package.  The server interacts with the KDE window
 
manager '''kwin''' to save and restore the window geometries and to perform
 
legacy session management.  To make session management work, '''ksmserver'''
 
has to be started as last process of the X login procedure. This happens
 
automatically at the end of the '''startkde''' script.
 
 
 
 
 
''Initial Author:'' [mailto:[email protected] Matthias Ettrich]
 
 
 
[[Category:Programming]]
 
[[Category:Tutorial]]
 
[[Category:FAQs]]
 

Latest revision as of 09:36, 4 October 2020

This tutorial was updated and moved to https://develop.kde.org/docs/configuration/introduction/


This page was last edited on 4 October 2020, at 09:36. Content is available under Creative Commons License SA 4.0 unless otherwise noted.