|
|
| (22 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/ |
|
| |
|
| ==About KDE and X11 session management==
| | [[Category:MovedDevelop]] |
| | |
| 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.
| |
| | |
| Implementing session management in KDE is easy. If your main window inherits from [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow], you have just 2 things to do:
| |
| * Reimplement some virtual functions of [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow].
| |
| * Add session management support to your main() function.
| |
| That's all.
| |
| | |
| ===Reimplement some virtual functions of KMainWindow===
| |
| | |
| [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow] will save its position, geometry and positions of toolbars and menubar on logout. To save additional data, reimplement [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#4c7a6c395eec0bb245cd9ad6c884f897 saveProperties()] and (to read them again on next login) [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#c8d0d64ed5b309ba1da410423120d0a6 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 (and to give him the possibility to save them), reimplement [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#f8c5708414be62f259114b0453ef8432 queryClose()]. These functions are called automatically by [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow] respectively by the session manager. Note that it is not determined if [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#4c7a6c395eec0bb245cd9ad6c884f897 saveProperties()] is called before or after [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#f8c5708414be62f259114b0453ef8432 queryClose()]! Please read documentation of the respective functions before reimplementing them.
| |
| | |
| To save your application-wide properties (data that is only needed once per application, and not for each main window) reimplement [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#cf811d77a3acdcf2b61f8826429615a7 saveGlobalProperties()] and it's counterpart [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#2d4da4f305f00e8a5c94f5b978334231 readGlobalProperties]. Normally, you don't need these functions.
| |
| | |
| ===Add session management support to your main() function===
| |
| | |
| While [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#4c7a6c395eec0bb245cd9ad6c884f897 KMainWindow::saveProperties()] and [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#f8c5708414be62f259114b0453ef8432 KMainWindow::queryClose()] will work out of the box, [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#c8d0d64ed5b309ba1da410423120d0a6 KMainWindow::readProperties()] will not. You have to add some code to your main() function to implement session restoring.
| |
| | |
| The function [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html#46e01bd1aa6d488f1be2a5010030efb2 KMainWindow::restore()] is responsible for restoring the session. This function is a little bit tricky, but you don't need to call it manually in your main function. There are more convenience possibilities:
| |
| | |
| ====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 ( app.isSessionRestored() ) {
| |
| RESTORE( MyWindow )
| |
| } else {
| |
| // create default application as usual
| |
| // for example:
| |
| MyWindow* window = new MyWindow();
| |
| // # will be replaced with numbers that are guaranteed
| |
| // to be unique in the application:
| |
| window->setObjectName("MainWindow#");
| |
| window->show();
| |
| }
| |
| return app.exec();
| |
| </code>
| |
| | |
| RESTORE will create as many instances of MyWindow as have existed in the last session. Note that QWidget::show() is called.
| |
| | |
| 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 [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/kmainwindow_8h.html#88ce427e39f425eefa5a94d746eb2bed kRestoreMainWindows()] global functions:
| |
| | |
| <code cppqt>
| |
| KApplication app;
| |
| if ( app.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();
| |
| // # will be replaced with numbers that are guaranteed
| |
| // to be unique in the application:
| |
| window1->setObjectName("type1mainWindow#");
| |
| window2->setObjectName("type2mainWindow#");
| |
| window3->setObjectName("type3mainWindow#");
| |
| window1->show();
| |
| window2->show();
| |
| window3->show();
| |
| }
| |
| return app.exec();
| |
| </code>
| |
| | |
| Currently, these functions are provided for up to three template arguments.
| |
| | |
| ==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]] | |
