|
|
| (38 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/features/session-managment/ |
|
| |
|
| {{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.
| |
| | |
| 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>
| |
| | |
| Note that QWidget::show() is called implicitly in RESTORE.
| |
| | |
| With this you can easily restore all toplevel windows of your application.
| |
| | |
| ====For several kinds of toplevel widgets====
| |
| | |
| 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 [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html 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();
| |
| }
| |
| return app.exec();
| |
| </code>
| |
| | |
| Currently, these functions are provided for up to three template arguments.
| |
| | |
| ===Reimplement some virtual functions of KMainWindow===
| |
| | |
| KMainWindow will save its position, geometry and positions of toolbars and menubar on logout. To save additional data, reimplement saveProperties() and (to read them again on next login) readProperties(). (For a text editor, that would be the loaded files, for example.) To warn the user that the application or some windows have unsaved data on close or logout, reimplement queryClose().
| |
| | |
| To save special data about your data, reimplement saveGlobalProperties().
| |
| | |
| ==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.
| |
| | |
| | |
| | |
| | |
| [[Category:Programming]]
| |
| [[Category:Tutorial]]
| |
| [[Category:FAQs]] | |
