1labwc-config(5) File Formats Manual labwc-config(5)
2
6 labwc - configuration files
7
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 No configuration files are needed to start and run labwc.
14 In accordance with XDG Base Directory Specification, configuration
16 files are searched for in the following order:
17 • ${XDG_CONFIG_HOME:-$HOME/.config}/labwc
19 • ${XDG_CONFIG_DIRS:-/etc/xdg}/labwc
20 The configuration directory location can be override with the -C com‐
23 mand line option.
24 All configuration and theme files except autostart are re-loaded on re‐
26 ceiving signal SIGHUP.
27 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 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 The menu.xml file defines the context/root-menus and is described in
40 labwc-menu(5).
41 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 rc.xml is the main configuration file and all its options are described
47 in detail below.
48
50 This section describes rc.xml configuration options.
51 SYNTAX
53 Configuration must be wrapped in a <labwc_config> root-element like
54 this:
55 <?xml version="1.0"?>
57 <labwc_config>
58 <!-- settings -->
60 </labwc_config>
62 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 The following three are therefore treated the same:
69 <action>
71 <name>Execute</name>
72 <command>foot</command>
73 </action>
74 <action name="Execute">
76 <command>foot</command>
77 </action>
78 <action name="Execute" command="foot" />
80 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 <command>sh -c 'grim -g "`slurp`"'</command>
86 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 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 CORE
98 <core>
99 <decoration>server</decoration>
100 <gap>0</gap>
101 <adaptiveSync>no</adaptiveSync>
102 <reuseOutputMode>no</reuseOutputMode>
103 </core>
104 <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 <core><gap>
111 The distance in pixels between views and output edges when using
112 movement actions, for example MoveToEdge. Default is 0.
113 <core><adaptiveSync> [yes|no]
115 Enable adaptive sync. Default is no.
116 <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 WINDOW SWITCHER
125 <windowSwitcher show="" preview="" outlines="">
126 show [yes|no] Draw the OnScreenDisplay when switching between win‐
127 dows. Default is yes.
128 preview [yes|no] Preview the contents of the selected window when
130 switching between windows. Default is yes.
131 outlines [yes|no] Draw an outline around the selected window when
133 switching between windows. Default is yes.
134 <windowSwitcher><fields><field content="" width="%">
136 Define window switcher fields.
137 content defines what the field shows and can be any of:
139 • type Show view type ("xdg-shell" or "xwayland")
141 • identifier Show identifier (app_id for native Wayland win‐
144 dows and WM_CLASS for XWayland clients)
145 • title Show window title if different to app_id
148 width defines the width of the field expressed as a percentage of
151 the overall window switcher width. The "%" character is required.
152 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 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 <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 <focus><raiseOnFocus> [yes|no]
173 Raise window to top when focused. Default is no.
174 WINDOW SNAPPING
176 The following two options relate to triggering window actions when mov‐
177 ing windows using the mouse.
178 <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 <snapping><topMaximize> [yes|no]
185 Maximize window if Move operation ends on the top edge. Default is
186 yes.
187 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 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 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 <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 THEME
215 <theme><name>
216 The name of the Openbox theme to use. It is not set by default.
217 <theme><cornerRadius>
219 The radius of server side decoration top corners. Default is 8.
220 <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 <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 If no place attribute is provided, the setting will be applied to all
234 places.
235 <theme><font place=""><name>
237 Describes font name. Default is sans.
238 <theme><font place=""><size>
240 Font size in pixels. Default is 10.
241 <theme><font place=""><slant>
243 Font slant (normal or italic). Default is normal.
244 <theme><font place=""><weight>
246 Font weight (normal or bold). Default is normal.
247 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 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 The different values mean:
262 • Never Do not render the indicator
263 • Always Render the indicator while moving and resizing windows
264 • Nonpixel Only render the indicator during resize for windows
265 using size-hints
266 Default is Never.
269 KEYBOARD
271 <keyboard><numlock> [on|off]
272 When recognizing a new keyboard enable or disable Num Lock. Default
273 is on.
274 <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 <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 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 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 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 <keyboard><keybind key=""><action name="">
306 Keybind action. See labwc-action(5)
307 <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 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 Audio and MonBrightness keys are also bound to amixer and bright‐
325 nessctl respectively
326 <keyboard><repeatRate>
328 Set the rate at which keypresses are repeated per second. Default
329 is 25.
330 <keyboard><repeatDelay>
332 Set the delay before keypresses are repeated in milliseconds. De‐
333 fault is 600.
334 MOUSE
336 <mouse><doubleClickTime>
337 Set double click time in milliseconds. Default is 500.
338 <mouse><scrollFactor>
340 Set scroll factor. Default is 1.0.
341 <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 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 Supported mouse buttons are:
373 • Left
374 • Middle
375 • Right
376 Supported scroll directions are:
379 • Up
380 • Down
381 • Left
382 • Right
383 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 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 <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 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 <libinput><device category=""><naturalScroll> [yes|no]
418 Use natural scrolling for this category if available.
419 <libinput><device category=""><leftHanded> [yes|no]
421 Use your devices left-handed mode if available.
422 <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 <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 <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 <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 <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 <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 <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 <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 WINDOW RULES
464 Two types of window rules are supported, actions and properties. They
465 are defined as shown below.
466 <windowRules>
468 <!-- Action -->
470 <windowRule identifier="" title="">
471 <action name=""/>
472 </windowRule>
473 <!-- Property -->
475 <windowRule identifier="" serverDecoration="" />
476 </windowRules>
478 Criteria
480 <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 identifier relates to app_id for native Wayland windows and
489 WM_CLASS for XWayland clients.
490 title is the title of the window.
492 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 Properties
498 Property values can be yes, no or default.
500 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 <windowRules><windowRule serverDecoration=""> [yes|no|default]
506 serverDecoration over-rules any other setting for server-side win‐
507 dow decoration on first map.
508 <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 <windowRules><windowRule skipWindowSwitcher=""> [yes|no|default]
515 skipWindowSwitcher removes window from the Window Switcher (alt-tab
516 on-screen-display)
517 <windowRules><windowRule ignoreFocusRequest=""> [yes|no|default]
519 ignoreFocusRequest prevent window to activate itself.
520 <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 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 find /usr/share/icons/ -type d -name "cursors"
533 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 See xkeyboard-config(7) for details.
539
541 labwc(1), labwc-actions(5), labwc-theme(5)
542 2023-11-26 labwc-config(5)