Automatic translation update from Pootle
[lxde/lxsession.git] / README
CommitLineData
9550c0e5
JL
1LXSession
2=========
3
4The default LXDE session manager.
5
b03fc74e 6Full documentation on http://wiki.lxde.org/en/index.php?title=LXSession
9550c0e5 7
b03fc74e 8== What's LXSession and who needs this? ==
dd69beb8 9
dd69beb8 10A session manager is used to automatically start a set of applications and
644fd872 11set up a working desktop environment.
f8d2bceb
HJYP
12Besides, LXSession has a built-in lightweight Xsettings daemon, which can
13configure gtk+ themes, keyboard, and mouse for you on session startup.
14In gnome the Xsettings part is provided by gnome-settings-daemon.
dd69beb8 15
644fd872 16Gnome is bundled with its own gnome-session, KDE brings its own session
dd69beb8
FC
17manager, too. XFCE and ROX desktop also have their own session managers,
18xfce4-session and rox-session.
19
644fd872
HJYP
20LXSession can start a set of programs specified by the distribution
21makers or users. Furthermore, LXSession is more advanced than
9550c0e5 22some of the other ones because it can "guard" the specified
644fd872
HJYP
23programs, and get them restarted if crashes happened.
24
25Besides, the major difference between LXSession and the preceding programs
df011ff6 26is that LXSession is lightweight, and it's not tighted to "any" desktop environment.
dd69beb8
FC
27It's desktop-independent and can be used with any window manager.
28With proper configuration, you can make your own desktop environment with
29LXSession. This is very useful to the users and developers of non-mainstream
df011ff6 30window managers and desktop environments.
dd69beb8 31
644fd872 32Here we use our own desktop environment LXDE as a working example
dd69beb8
FC
33to tell you, step by step, how to create your own new desktop environment.
34
35Create a startup script for your desktop, and put it to /usr/bin.
9550c0e5 36For example, we create a script ``/usr/bin/startlxde``.
dd69beb8 37
644fd872 38Then, add the commands you want to execute *before* LXSession,
dd69beb8
FC
39such as setting up locales or others, and put "exec lxsession" in the last line.
40
41For example, our startlxde script looks like this:
42
9550c0e5 43```sh
dd69beb8 44#!/bin/sh
b03fc74e 45exec /usr/bin/lxsession -s LXDE -e LXDE
9550c0e5 46```
dd69beb8
FC
47
48Apparently, LXDE is the name of our desktop.
49Replace it with the name of your desktop.
50
51Then, make a desktop entry file for it under '/usr/share/xsessions'.
52With this, you can select this desktop session from menu in GDM.
53For example, this is the content of our LXDE.desktop:
54
9550c0e5 55```ini
dd69beb8
FC
56[Desktop Entry]
57Encoding=UTF-8
58Name=LXDE
59Comment=LXDE - Lightweight X11 desktop environment
60Exec=/usr/bin/startlxde
61Type=Application
9550c0e5 62```
dd69beb8 63
df011ff6 64Apparently, you can replace the name and description with your own.
dd69beb8
FC
65Exec should points to the startup script created in previous step.
66
67Now you get an item 'LXDE' in the list of available sessions in gdm.
68NOTE: Restart of gdm might be needed. ( On Debian: sudo /etc/init.d/gdm restart )
69
b03fc74e
JL
70
71== Compilation flags ==
72* "--enable-man" : Generate man pages
73* "--enable-more-warnings" : Enable more compilation warning at build time
74* "--enable-gtk3" : Compile with GTK3 when the component is compatible (incomplete)
75* "--enable-buildin-clipboard" : Add a build-in support for clipboard functionalities, using GTK2
76* "--enable-buildin-polkit" : Add a build-in support for a polkit agent (based on GTK)
77* "--enable-debug" : Enable more debug
78* "--enable-gtk" : Enable GTK+ programs and compilation. Pass --disable-gtk to build without any GTK+ component (useful if you want lxsession on a Qt environnement).
79
80== Runtime arguments ==
81* --session or -s : Specify the session name (use for configuration, settings, log files ...). Default to LXDE
82* --de or -e : Specify the desktop environment name to use for desktop files (such as LXDE, GNOME, or XFCE).
83* --reload or -r : Reload configurations (for Xsettings daemon).
84* --noxsettings or -n : Disable Xsettings daemon support.
85* --noautostart or -a : Disable the autostart of applications (window-manager mode only)
86* --compatibility or -c : Specify a compatibility mode for settings (only razor-qt supported)
87
88== Configuration files ==
89The config files of LXSession are stored in
90'''~/.config/lxsession/''<Profile Name>'''''
91
92If the config files are missing, LXSession loads system-wide config in '''/etc/xdg/lxsession/''<Profile name>''''' instead.
93
94Note: If no <code>-session</code> has been passed on the command line to lxsession, the default profile name is LXDE.
95
96== Dbus interface ==
97All settings are available via Dbus, using the Dbus interface org.lxde.SessionManager /org/lxde/SessionManager org.lxde.SessionManager
98There are several group of methods, which reflect the groups of the keyfile. All settings have 2 keys (key1/key2), the first one (level1) is the main one, the second one (level2) is linked to the first one and can be empty, depending of the settings.
99Example : composite_manager/command is the settings which contains the name of the executable to launch the composite manager. composite_manager/autostart is the one to manager the autostart of composite_manager
100
101To retrieve all the settings, use the ***Support method, which retrieve the list of available options. To have the details of level2 settings available for a level1 setting, use ***SupportDetail method.
102
103Type available for methods :
104* Session
105* Dbus
106* Environment
107* Keymap
108* Proxy
109* Security
110* State
111* Updates
112* XRandr
113* Xsettings
114* a11y
115
116Methods available for all type (replace *** by the type you want (such as Session, Dbus ...) :
117* ***Get (key1, key2) : Retrieve the setting for key1/key2
118* ***Set (key1, key2, value_to_set): Save the setting for key1/key2
119* ***Support () : List all the options available
120* ***SupportDetail (lvl1) : List all the level2 options for level1 setting lvl1.
121* ***Activate () : Launch the option (available for all type of method except Session)
122
123Special methods:
124* SessionLaunch (command) : Launch the application (command is the key1 setting of the application to launch)
125
126Session Manager methods:
127* CanShutdown
128* Logout
129* RequestReboot
130* RequestShutdown
131* Shutdown
132* ReloadSettingsDaemon
133
134== Options and settings ==
135All options are available on the desktop.conf.example : http://lxde.git.sourceforge.net/git/gitweb.cgi?p=lxde/lxsession;a=blob;f=data/desktop.conf.example;hb=HEAD
136
137== Custom configuration files ==
138You can use custom configuration files for some applications. LXsession will automatically copy them on the right place to be used by the applications. The configuration of those files are done in conffiles.conf, in /etc/xdg/lxsession/<profile>/ or ~/.config/lxsession/<profile>/.
139
140== Applications and binaries ==
141* lxclipboard : Application to enable a clipboard support, using GTK.
142* lxlock : Application to lock the screen, using external applications
143* lxpolkit : Polkit agent
144* lxsession-default : Wrapper around Dbus method to launch applications defined in lxsession configuration file.
145* lxsession-default-apps : Configuration application for lxsession (mostly for debugging purposes).
146* lxsession-edit : Old configuration application for lxsession
147* lxsession-utils : Misc utilities for lxsession
148* lxsettings-daemon : Xsettings daemon
149
150== Autostarted applications using lxsession ==
151Lxsession manages the application which are started on login. It's handle by several elements
152
153=== Settings ===
154You can enable, disable partly, or disable completely autostared application using the settings "disable_autostart", with different value :
155* all : disable all applications (home, system, specify in this config file)
156* config-only : disable applications from home and system (start only the ones in the desktop.conf config file)
157* no : autostart all applications
158
159Using "all" and "config-only" will disable autostared applications from the 2 above methods.
160
161=== autostart configuration file ===
162This file stores the commands that will be executed at the beginning of the session.
163It is not a shell script, but each line represents a different command to be executed.
164If a line begins with @, the command following the @ will be automatically re-executed if
165it crashes. Lines beginning with # are comments.
166
167Commands globally executed are stored in the /etc/xdg/lxsession/<profile>/autostart file, and
168in addition, other commands can be locally specified in the ~/.config/lxsession/<profile>/autostart
169file. If both files are present, only the entries in the local file will be executed.
170
171Exactly how autostart files are parsed, as of LXSession 0.4.9.2, is given by the following code in <code>autostart.vala</code>:
172
173<pre>while ((line = dis.read_line (null)) != null)
174{
175 string first = line[0:1];
176
177 switch (first)
178 {
179 case ("@"):
180 var builder = new StringBuilder ();
181 builder.append(line);
182 builder.erase(0,1);
183 string[] command = builder.str.split_set(" ",0);
184 AppType app = { command[0], command, true, "" };
185 app_list.add (app);
186 break;
187 case ("#"):
188 /* Commented, skip */
189 break;
190 default:
191 string[] command = line.split_set(" ",0);
192 AppType app = { command[0], command, false, "" };
193 app_list.add (app);
194 break;
195 }
196 }</pre>
197
198Notice that lines are split on space characters, but no form of escaping or quoting is supported, nor are multi-line commands. So if you need, e.g., a command with a space in one of its arguments, put it in a shell script and invoke the shell script from the autostart file.
199
200=== autostart directories ===
201LXSession supports [http://www.freedesktop.org/ freedesktop.org] [http://www.freedesktop.org/wiki/Specifications/autostart-spec Autostart spec]. Put *.desktop files of those applications in ~/.config/autostart, and they will get executed when the session starts.
202
203'''Important note:'''
204
205Some gnome applications have the "OnlyShowIn=GNOME" key in their *.desktop files. That key means 'only load this application in GNOME' and it prevents the application from being loaded in other desktop environments. Actually, most of those applications can work well under other desktops, but sometimes they claim they are GNOME-only.
206
207If you cannot get an application automatically started and you already have a .desktop file for it in the autostart directory, then check the setting of the 'OnlyShowIn' key. Try commenting it out or removing the key.
208If the application still works ok then it's not really GNOME-specific - file a bug report for that application to its author and packager. As an example, the NetworkManager Applet (nm-applet) has the setting "OnlyShowIn=Gnome", but it works fine in LXDE. To make it autostart, just comment out or delete "OnlyShowIn=Gnome" in your ~/.config/autostart/nm-applet.desktop. If you are using different desktop environments on different sessions, and wish to use NetworkManager in LXDE, XFCE and Gnome, but not in KDE, you might want to add "OnlyShowIn=Gnome;XFCE;LXDE;" and/or "NotShowIn=KDE;"
209
210== Log out ==
dd69beb8
FC
211
212Simply executing this command:
9550c0e5 213``lxsession-logout``
dd69beb8 214
df011ff6 215This will give you a good-looking logout dialog.
dd69beb8
FC
216If gdm is installed, lxsession can do shutdown/reboot/suspend via gdm.
217(These options are not available if gdm is not running.)
218
219If you want to customize this logout box further, try this:
9550c0e5
JL
220``lxsession-logout --prompt "Your custom message" --banner "Your logo" \
221--side "left | top | right | bottom (The position of the logo)"``
222
223We create a script ``/usr/bin/lxde-logout`` to do this:
dd69beb8 224
9550c0e5 225```sh
dd69beb8
FC
226#!/bin/sh
227/usr/bin/lxsession-logout --banner "/usr/share/lxde/images/logout-banner.png" --side top
9550c0e5 228```
dd69beb8
FC
229
230You can put this logout script in the menu of your window manager or desktop panel.
231Then, you can logout via clicking from the menu.
232
233Have fun!