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

Jump to: navigation, search
Line 37: Line 37:
  
 
Please read the respective class documentation, especially the one of
 
Please read the respective class documentation, especially the one of
KMainWindow, for a detailed interface description. With the advanced
+
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow], for a detailed interface description. With the advanced
functionality in KMainWindow, it's really just a matter of a few lines
+
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
 
to get even a multi-window application to retains its state between
 
different user sessions.
 
different user sessions.
Line 50: Line 50:
  
 
Imagine you have an
 
Imagine you have an
application with a main window MyWindow inherited from KMainWindow (or from KXmlGuiWindow, which inherits from KMainWindow). In
+
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
 
your main() function, you would then create/restore the application
 
windows with something like:
 
windows with something like:
Line 62: Line 62:
 
</code>
 
</code>
  
With KMainWindow::classNameOfToplevel(), it is also possible to
+
With [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#9b826dabc2fe32547acdfa20a7d1fc8a KMainWindow::classNameOfToplevel()], it is also possible to
 
restore different types of toplevel windows within one application. In
 
restore different types of toplevel windows within one application. In
 
that case, the RESTORE macro is too primitive, use something like this
 
that case, the RESTORE macro is too primitive, use something like this

Revision as of 15:11, 31 December 2008


Contents

Development/Tutorials/Session Management


noframe
 
Under Construction
This page is under construction. This page is actively being developed and updated with new information, and may be incomplete. You can help by editing this page


About KDE and X11 session management

KDE supports the legacy X11R4 and ICCCM session management protocols. Legacy applications that define the WM_COMMAND property or support the WM_SAVE_YOURSELF 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 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 doc.trolltech.com.

In KDE, the classes KApplication and KMainWindow hide all the ugly details from the programmer. Basically, a KApplication manages a KConfig configuration object sessionConfig() for you, that your application can utilize to store session specific data.

Please read the respective class documentation, especially the one of KMainWindow, for a detailed interface description. With the advanced functionality in 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

Imagine you have an application with a main window MyWindow inherited from KMainWindow (or from KXmlGuiWindow, which inherits from KMainWindow). In your main() function, you would then create/restore the application windows with something like:

if ( kapp->isRestored() ) {

 RESTORE( MyWindow )

} else {

 // create default application as usual

}

With KMainWindow::classNameOfToplevel(), it is also possible to restore different types of toplevel windows within one application. In that case, the RESTORE macro is too primitive, use something like this in your main() function instead:

if ( kapp->isRestored() ){

 int n = 1;
 while ( KMainWindow::canBeRestored( n ) ) {
   if ( KMainWindow::classNameOfToplevel( n ) == "MyWindow1" )
     ( new MyWindow1 )->restore( n );
   else if ( KMainWindow::classNameOfToplevel( n ) == "MyWindow2" )
     ( new MyWindow2 )->restore( n );
   // and so on....
   n++;
 }

} else {

 // create default application as usual

}

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:

void MyWindow::saveProperties( KConfig* ) {

 // save properties here

}

void MyWindow::readProperties( KConfig* ) {

 // read properties here

}

Note that standard settings like window sizes, toolbar settings etc. are automatically handled by the system.

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: Matthias Ettrich


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal