1labwc-config(5)               File Formats Manual              labwc-config(5)
2
3
4

NAME

6       labwc - configuration files
7

DESCRIPTION

9       Labwc uses openbox-3.6 specification for configuration and theming, but
10       does not support all options. The following files form the basis of the
11       labwc configuration: rc.xml, menu.xml, autostart and environment.
12
13       No configuration files are needed to start and run labwc.
14
15       In accordance with XDG Base Directory Specification, configuration
16       files are searched for in the following order:
17
18       •   ${XDG_CONFIG_HOME:-$HOME/.config}/labwc
19       •   ${XDG_CONFIG_DIRS:-/etc/xdg}/labwc
20
21
22       The configuration directory location can be override with the -C com‐
23       mand line option.
24
25       All configuration and theme files except autostart are re-loaded on re‐
26       ceiving signal SIGHUP.
27
28       The autostart file is executed as a shell script. This is the place for
29       executing clients for handling background images, panels and similar.
30
31       The environment file is parsed as variable=value and sets environment
32       variables accordingly. It is recommended to specify keyboard layout
33       settings and cursor size/theme here; see environment variable section
34       below for details. Note that the environment file is treated differ‐
35       ently by openbox where it is simply sourced prior to running openbox.
36       Note: Tilde (~) and environment variables in the value are expanded,
37       but subshell syntax and apostrophes are ignored.
38
39       The menu.xml file defines the context/root-menus and is described in
40       labwc-menu(5).
41
42       There is a small <theme> section in rc.xml, for example to set rounded
43       corners, but the remainder of the theme specification and associated
44       files are described in labwc-theme(5).
45
46       rc.xml is the main configuration file and all its options are described
47       in detail below.
48

CONFIGURATION

50       This section describes rc.xml configuration options.
51
52   SYNTAX
53       Configuration must be wrapped in a <labwc_config> root-element like
54       this:
55
56           <?xml version="1.0"?>
57           <labwc_config>
58
59           <!-- settings -->
60
61           </labwc_config>
62
63       labwc parses XML in an element/attribute agnostic way. This is a design
64       decision to increase config file flexibility and keep code simple. In
65       practical terms, this means that `<a><b>c</b></a>` is equivalent to `<a
66       b="c" />`.
67
68       The following three are therefore treated the same:
69
70           <action>
71             <name>Execute</name>
72             <command>foot</command>
73           </action>
74
75           <action name="Execute">
76             <command>foot</command>
77           </action>
78
79           <action name="Execute" command="foot" />
80
81       The benefit of the final one is brevity whereas the advantage of the
82       first two is that you can add ' and " within the `<command>` block, for
83       example:
84
85           <command>sh -c 'grim -g "`slurp`"'</command>
86
87       Elements at the same level can have the same name whereas attributes
88       cannot. Therefore, where multiple objects of the same kind are required
89       (for example <action> and <keybind>) the top-node of the object has to
90       be an element.
91
92   BOOLEANS
93       Note that in this manual, Boolean values are listed as [yes|no] for
94       simplicity, but it's also possible to use [true|false] and/or [on|off];
95       this is for compatibility with Openbox.
96
97   CORE
98           <core>
99             <decoration>server</decoration>
100             <gap>0</gap>
101             <adaptiveSync>no</adaptiveSync>
102             <reuseOutputMode>no</reuseOutputMode>
103           </core>
104
105       <core><decoration> [server|client]
106           Specify server or client side decorations for xdg-shell views. Note
107           that it is not always possible to turn off client side decorations.
108           Default is server.
109
110       <core><gap>
111           The distance in pixels between views and output edges when using
112           movement actions, for example MoveToEdge. Default is 0.
113
114       <core><adaptiveSync> [yes|no]
115           Enable adaptive sync. Default is no.
116
117       <core><reuseOutputMode> [yes|no]
118           Try to re-use the existing output mode (resolution / refresh rate).
119           This may prevent unnecessary screenblank delays when starting labwc
120           (also known as flicker free boot). If the existing output mode can
121           not be used with labwc the preferred mode of the monitor is used
122           instead. Default is no.
123
124   WINDOW SWITCHER
125       <windowSwitcher show="" preview="" outlines="">
126           show [yes|no] Draw the OnScreenDisplay when switching between win‐
127           dows. Default is yes.
128
129           preview [yes|no] Preview the contents of the selected window when
130           switching between windows. Default is yes.
131
132           outlines [yes|no] Draw an outline around the selected window when
133           switching between windows. Default is yes.
134
135       <windowSwitcher><fields><field content="" width="%">
136           Define window switcher fields.
137
138           content defines what the field shows and can be any of:
139
140type Show view type ("xdg-shell" or "xwayland")
141
142
143identifier Show identifier (app_id for native Wayland win‐
144                   dows and WM_CLASS for XWayland clients)
145
146
147title Show window title if different to app_id
148
149
150           width defines the width of the field expressed as a percentage of
151           the overall window switcher width. The "%" character is required.
152
153   RESISTANCE
154       <resistance><screenEdgeStrength>
155           Screen Edge Strength is how far past the screen's edge your cursor
156           must move before the window will move with it. Resistance is
157           counted in pixels. Default is 20 pixels.
158
159   FOCUS
160       <focus><followMouse> [yes|no]
161           Make focus follow mouse, i.e. focus is given to window under mouse
162           cursor. Default is no.
163
164       <focus><followMouseRequiresMovement> [yes|no]
165           Requires cursor movement if followMouse is enabled. It is the same
166           as the "underMouse" setting in Openbox. If set to "no", labwc will
167           additionally focus the window under the cursor in all situations
168           which change the position of a window (e.g. switching workspaces,
169           opening/closing windows). Focusing a different window via A-Tab is
170           still possible, even with this setting set to "no". Default is yes.
171
172       <focus><raiseOnFocus> [yes|no]
173           Raise window to top when focused. Default is no.
174
175   WINDOW SNAPPING
176       The following two options relate to triggering window actions when mov‐
177       ing windows using the mouse.
178
179       <snapping><range>
180           The distance in pixels from the edge of an output for window Move
181           operations to trigger SnapToEdge. A range of 0 disables window
182           snapping. Default is 1.
183
184       <snapping><topMaximize> [yes|no]
185           Maximize window if Move operation ends on the top edge. Default is
186           yes.
187
188   REGIONS
189       <regions><region name="snap-1" x="10%" y="10%" width="80%"
190       height="80%">
191           Define snap regions. The regions are calculated based on the usable
192           area of each output. Usable area in this context means space not
193           exclusively used by layershell clients like panels. The "%" charac‐
194           ter is required. Windows can either be snapped to regions by keep‐
195           ing a keyboard modifier pressed while moving a window (Ctrl, Alt,
196           Shift, Logo) or by using the SnapToRegion action. By default there
197           are no regions defined.
198
199   WORKSPACES
200       <desktops number=""><names><name>
201           Define workspaces. A workspace covers all outputs. The OSD only
202           shows windows on the current workspace. Workspaces can be switched
203           to with GoToDesktop and windows can be moved with SendToDesktop.
204           See labwc-actions(5) for more information about their arguments.
205
206           The number attribute defines the minimum number of workspaces. De‐
207           fault is 1. The number attribute is optional. If the number attri‐
208           bute is specified, names.name is not required.
209
210       <desktops><popupTime>
211           Define the timeout after which to hide the workspace OSD. A setting
212           of 0 disables the OSD. Default is 1000 ms.
213
214   THEME
215       <theme><name>
216           The name of the Openbox theme to use. It is not set by default.
217
218       <theme><cornerRadius>
219           The radius of server side decoration top corners. Default is 8.
220
221       <theme><keepBorder> [yes|no]
222           Even when disabling server side decorations via ToggleDecorations,
223           keep a small border (and resize area) around the window. Default is
224           yes.
225
226       <theme><font place="">
227           The font to use for a specific element of a window, menu or OSD.
228           Places can be any of:
229           •   ActiveWindow - titlebar of active window
230           •   MenuItem - menu item (currently only root menu)
231           •   OnScreenDisplay - items in the on screen display
232
233       If no place attribute is provided, the setting will be applied to all
234           places.
235
236       <theme><font place=""><name>
237           Describes font name. Default is sans.
238
239       <theme><font place=""><size>
240           Font size in pixels. Default is 10.
241
242       <theme><font place=""><slant>
243           Font slant (normal or italic). Default is normal.
244
245       <theme><font place=""><weight>
246           Font weight (normal or bold). Default is normal.
247
248   MARGIN
249       <margin top="" bottom="" left="" right="" output="" />
250           Specify the number of pixels to reserve at the edges of an output.
251           New, maximized and tiled windows will not be placed in these areas.
252
253   RESIZE
254       <resize><popupShow> [Never|Always|Nonpixel]
255           Show a small indicator on top of the window when resizing or mov‐
256           ing. When the application sets size-hints (usually X11 terminal em‐
257           ulators), the indicator will show the dimensions divided by size
258           hints instead. In the case of terminal emulators this usually means
259           columns x rows.
260
261           The different values mean:
262Never Do not render the indicator
263Always Render the indicator while moving and resizing windows
264Nonpixel Only render the indicator during resize for windows
265               using size-hints
266
267
268           Default is Never.
269
270   KEYBOARD
271       <keyboard><numlock> [on|off]
272           When recognizing a new keyboard enable or disable Num Lock. Default
273           is on.
274
275       <keyboard layoutScope=""> [global|window]
276           Stores the keyboard layout either globally or per window and re‐
277           stores it when switching back to the window. Default is global.
278
279       <keyboard><keybind key="" layoutDependent="">
280           Define a key binding in the format modifier-key, where supported
281           modifiers are:
282           •   S (shift)
283           •   C (control)
284           •   A or Mod1 (alt)
285           •   H or Mod3 (hyper)
286           •   W or Mod4 (super / logo)
287           •   M or Mod5 (meta)
288
289
290           Multiple modifiers can be combined like A-S-f for Alt-Shift-f. The
291           key itself can be any unicode character or a keyname like Return.
292
293           Unlike Openbox, multiple space-separated key combinations and key-
294           chains are not supported. The application "wev" (wayland event
295           viewer) is packaged in a lot of distributions and can be used to
296           view all available keynames.
297
298           layoutDependent [yes|no] Make this specific keybind depend on the
299           currently active keyboard layout. If enabled, a keybind using a key
300           which does not exist in the currently active layout will not be ex‐
301           ecuted. The physical key to trigger a keybind may also change along
302           with the active layout. If set to "no" (or is absent) the keybind
303           will be layout agnostic. Default is no.
304
305       <keyboard><keybind key=""><action name="">
306           Keybind action. See labwc-action(5)
307
308       <keyboard><default />
309           Load the default keybinds listed below. This is an addition to the
310           openbox specification and provides a way to keep config files sim‐
311           pler whilst allowing your specific keybinds. Note that if no rc.xml
312           is found, or if no <keyboard><keybind> entries exist, the same de‐
313           fault keybinds will be loaded even if the <default /> element is
314           not provided.
315
316             A-Tab - next window
317             W-Return - alacritty
318             A-F3 - run bemenu
319             A-F4 - close window
320             W-a - toggle maximize
321             A-<arrow> - move window to edge
322             W-<arrow> - resize window to fill half the output
323
324           Audio and MonBrightness keys are also bound to amixer and bright‐
325           nessctl respectively
326
327       <keyboard><repeatRate>
328           Set the rate at which keypresses are repeated per second. Default
329           is 25.
330
331       <keyboard><repeatDelay>
332           Set the delay before keypresses are repeated in milliseconds. De‐
333           fault is 600.
334
335   MOUSE
336       <mouse><doubleClickTime>
337           Set double click time in milliseconds. Default is 500.
338
339       <mouse><scrollFactor>
340           Set scroll factor. Default is 1.0.
341
342       <mouse><context name=""><mousebind button="" direction="" ac‐
343       tion=""><action>
344           Multiple <mousebind> can exist within one <context>; and multiple
345           <action> can exist within one <mousebind>
346
347           Define a mouse binding. Supported context-names include:
348           •   TitleBar: The decoration on top of the window, where the window
349               buttons and the window title are shown.
350           •   Title: The area of the titlebar (including blank space) between
351               the window buttons, where the window title is displayed.
352           •   WindowMenu: The button on the left.
353           •   Iconify: The button that looks like an underline.
354           •   Maximize: The button that looks like a box.
355           •   Close: The button that looks like an X.
356           •   Top: The top edge of the window's border.
357           •   Bottom: The bottom edge of the window's border.
358           •   Left: The left edge of the window's border.
359           •   Right: The right edge of the window's border.
360           •   TRCorner: The top-right corner of the window's border.
361           •   TLCorner: The top-left corner of the window's border.
362           •   BLCorner: The bottom-left corner of the window's border.
363           •   BRCorner: The bottom-right edge of the window's border.
364           •   Client: The client area of a window, inside its decorations.
365               Events bound to Client are also passed to applications.
366           •   Frame: Any part of a window, but events bound to Frame are not
367               passed through to the application.
368           •   Desktop: The desktop background, where no windows are present.
369           •   Root: A synonym for Desktop (for compatibility).
370
371
372           Supported mouse buttons are:
373           •   Left
374           •   Middle
375           •   Right
376
377
378           Supported scroll directions are:
379           •   Up
380           •   Down
381           •   Left
382           •   Right
383
384
385           Mouse buttons and directions can be combined with modifier-keys
386           (shift (S), super/logo (W), control (C), alt (A), meta (M) and hy‐
387           per (H)), for example: <mousebind button="A-Right" action="Press">
388
389           Supported mouse actions include:
390           •   Press: Pressing the specified button down in the context.
391           •   Release: Releasing the specified button in the context.
392           •   Click: Pressing and then releasing inside of the the context.
393           •   DoubleClick: Two presses within the doubleClickTime.
394           •   Drag: Pressing the button within the context, then moving the
395               cursor.
396           •   Scroll: Scrolling in specified direction in the context.
397
398
399       <mouse><default />
400           Load default mousebinds. This is an addition to the openbox speci‐
401           fication and provides a way to keep config files simpler whilst al‐
402           lowing user specific binds.  Note that if no rc.xml is found, or if
403           no <mouse><mousebind> entries exist, the same default mousebinds
404           will be loaded even if the <default /> element is not provided.
405
406   LIBINPUT
407       <libinput><device category="">
408           Define a category of devices to use the configuration values that
409           follow. The category can be set to touch (devices that define a
410           width and height), non-touch, default, or the name of a device. You
411           can obtain your devices name by running libinput list-devices (you
412           may need to be root or a part of the input group to perform this.)
413           Any members of this category that are not set use the default for
414           the device. With the exception of tap-to-click, which is enabled by
415           default.
416
417       <libinput><device category=""><naturalScroll> [yes|no]
418           Use natural scrolling for this category if available.
419
420       <libinput><device category=""><leftHanded> [yes|no]
421           Use your devices left-handed mode if available.
422
423       <libinput><device category=""><pointerSpeed> [-1.0 to 1.0]
424           Set the pointer speed for this category. The speed is a number be‐
425           tween -1.0 and 1.0, with 0.0 being the default in most cases, and
426           1.0 being the fastest.
427
428       <libinput><device category=""><accelProfile> [flat|adaptive]
429           Set the pointer's acceleration profile for this category. Flat ap‐
430           plies no acceleration (the pointers velocity is constant), while
431           adaptive changes the pointers speed based the actual speed of your
432           mouse or finger on your touchpad.
433
434       <libinput><device category=""><tap> [yes|no]
435           Enable or disable tap-to-click for this category. This is enabled
436           by default for all categories.
437
438       <libinput><device category=""><tapButtonMap> [lrm|lmr]
439           Set the buttons mapped to one-, two-, and three-finger taps to the
440           left button, right button, and middle button, respectively (lrm)
441           (the default), or to left button, middle button, and right button
442           (lmr).
443
444       <libinput><device category=""><tapAndDrag> [yes|no]
445           Enable or disable tap-and-drag for this category. Tap-and-drag pro‐
446           cesses a tap immediately followed by a finger down as the start of
447           a drag.
448
449       <libinput><device category=""><dragLock> [yes|no]
450           Enable or disable drag lock for this category. Drag lock ignores a
451           momentary release of a finger during tap-and-dragging.
452
453       <libinput><device category=""><middleEmulation> [yes|no]
454           Enable or disable middle button emulation for this category. Middle
455           emulation processes a simultaneous left and right click as a press
456           of the middle mouse button (scroll wheel).
457
458       <libinput><device category=""><disableWhileTyping> [yes|no]
459           Enable or disable disable while typing for this category. DWT ig‐
460           nores any motion events while a keyboard is typing, and for a short
461           while after as well.
462
463   WINDOW RULES
464       Two types of window rules are supported, actions and properties. They
465       are defined as shown below.
466
467           <windowRules>
468
469             <!-- Action -->
470             <windowRule identifier="" title="">
471               <action name=""/>
472             </windowRule>
473
474             <!-- Property -->
475             <windowRule identifier="" serverDecoration="" />
476
477           </windowRules>
478
479       Criteria
480
481       <windowRules><windowRule identifier="" title="" matchOnce="">
482           Define a window rule for any window which matches the criteria de‐
483           fined by the attributes identifier or title. If both are defined,
484           AND logic is used, so both have to match. Matching against patterns
485           with '*' (wildcard) and '?' (joker) is supported. Pattern matching
486           is case-insensitive.
487
488           identifier relates to app_id for native Wayland windows and
489           WM_CLASS for XWayland clients.
490
491           title is the title of the window.
492
493           matchOnce can be true|false. If true, the rule will only apply to
494           the first instance of the window with the specified identifier or
495           title.
496
497       Properties
498
499       Property values can be yes, no or default.
500
501       If a window matches criteria for multiple rules which set the same
502       property, later config entries have higher priority. default can be
503       useful in this situation.
504
505       <windowRules><windowRule serverDecoration=""> [yes|no|default]
506           serverDecoration over-rules any other setting for server-side win‐
507           dow decoration on first map.
508
509       <windowRules><windowRule skipTaskbar=""> [yes|no|default]
510           skipTaskbar removes window foreign-toplevel protocol handle so that
511           it does not appear in clients such as panels and taskbars using
512           that protocol.
513
514       <windowRules><windowRule skipWindowSwitcher=""> [yes|no|default]
515           skipWindowSwitcher removes window from the Window Switcher (alt-tab
516           on-screen-display)
517
518       <windowRules><windowRule ignoreFocusRequest=""> [yes|no|default]
519           ignoreFocusRequest prevent window to activate itself.
520
521       <windowRules><windowRule fixedPosition=""> [yes|no|default]
522           fixedPosition disallows interactive move/resize and prevents re-po‐
523           sitioning in response to changes in reserved output space, which
524           can be caused by <margin> settings or exclusive layer-shell clients
525           such as panels.
526
527   ENVIRONMENT VARIABLES
528       XCURSOR_THEME and XCURSOR_SIZE are supported to set cursor theme and
529       size respectively. The default size is 24. System cursor themes can
530       typically be found with a command such as:
531
532           find /usr/share/icons/ -type d -name "cursors"
533
534       The following keyboard-configuration variables are supported: XKB_DE‐
535       FAULT_RULES, XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT
536       and XKB_DEFAULT_OPTIONS.
537
538       See xkeyboard-config(7) for details.
539

SEE ALSO

541       labwc(1), labwc-actions(5), labwc-theme(5)
542
543
544
545                                  2023-11-26                   labwc-config(5)
Impressum