labwc-config(5)

📦
version 0.20.2 · 12 versions
, in arch rolling

💖 labwc — configuration files 💖

okay bestie, welcome to labwc-config(5), straight out of the File Formats Manual section. this is the big one, so grab a snack 🍓

🌸 NAME 🌸

labwc — configuration files. that's it, that's the name, and honestly? iconic.

🦋 DESCRIPTION 🦋

so here's the tea: labwc uses the openbox-3.6 specification for configuration and theming, but does not support all options. like, it's openbox-flavored, not openbox-copy-pasted, iykyk 💅

these files form the basis of the labwc configuration: rc.xml, menu.xml, autostart, shutdown, environment and xinitrc.

and the best part? no configuration files are needed to start and run labwc. none. zero. it just works. main character energy fr fr ✨

In accordance with the XDG Base Directory Specification, configuration files are searched for in this order:

  • ${XDG_CONFIG_HOME:-$HOME/.config}/labwc
  • ${XDG_CONFIG_DIRS:-/etc/xdg}/labwc

when $XDG_CONFIG_HOME is defined, it replaces (rather than augments) $HOME/.config. same situation with $XDG_CONFIG_DIRS and /etc/xdg.

The XDG Base Directory Specification does not specify whether or not programs should (a) allow the first-identified configuration file to supersede any others, or (b) define rules for merging the information from more than one file. (the spec really said "you figure it out" 😭)

By default, labwc uses option (a), reading only the first file identified. with the --merge-config option, the search order is reversed, but every configuration file encountered is processed in turn. so user-specific files will augment system-wide configurations, with conflicts favoring the user-specific alternative. your vibes win, periodt 👑

The configuration directory location can be overridden with the -C command line option.

⚠️ All configuration and theme files except autostart and shutdown are re-loaded on receiving signal SIGHUP.

Environment variables may be set within environment files, wherein each line defines shell variables in the format variable=value. it is recommended to specify keyboard layout settings and cursor size/theme here; see environment variable section below for details. Within an XDG Base Directory, a file named environment will be parsed first, followed by any file matching the glob environment.d/*.env. Files within the environment.d directory are parsed in alphabetical order. Unless the --merge-config option is specified, labwc will consider a particular XDG Base Directory to have provided an environment file if that directory contains either the environment file or at least one environment.d/*.env file.

📌 Note: environment files are treated differently by Openbox, which will simply source the file as a valid shell script before running the window manager. Files are instead parsed directly by labwc so that environment variables can be re-loaded on --reconfigure. (different approaches, both valid, we're not judging 🫶)

Any environment variables referenced as $VARIABLE or ${VARIABLE} will be substituted and the tilde (~) will be expanded as the user's home directory.

Any line beginning with the character # in an environment file will be treated as a comment. Trailing comments are not supported. nope, not a thing, don't try it 🙈

💀 Please note that as labwc reloads the environment file(s) on reconfigure, recursive/circular assignments (for example FOO=$FOO:bar) should not be made. seriously. don't. it's giving infinite loop.

The autostart file is executed as a shell script after labwc has read its configuration and set variables defined in the environment file. Additionally, the environment variables WAYLAND_DISPLAY and (when labwc is built with Xwayland support) DISPLAY will be defined. this is the place for executing clients for handling background images, panels and other tasks that should run automatically when labwc launches. your little startup squad 🎀

The shutdown file is executed as a shell script when labwc is preparing to terminate itself. All environment variables, including WAYLAND_DISPLAY and DISPLAY, will be available to the script. However, because the script runs asynchronously with other termination tasks, the shutdown file should not assume that the display will be usable. this file is useful to perform any custom operations necessary to finalize a labwc session. goodbye rituals only 💐

The menu.xml file defines the context/root-menus and is described in labwc-menu(5).

There is a small <theme> section in rc.xml, for example to set rounded corners, but the remainder of the theme specification and associated files are described in labwc-theme(5).

rc.xml is the main configuration file and all its options are described in detail below. buckle up bestie 🌈

The xinitrc file is executed as a shell script whenever labwc launches the Xwayland X11 server. This may happen multiple times throughout the session if Xwayland is not configured to persist when no X11 clients are connected.

✨ CONFIGURATION ✨

This section describes rc.xml configuration options.

🧚 SYNTAX 🧚

Configuration must be wrapped in a <labwc_config> root-element like this:

<?xml version="1.0"?>
<labwc_config>

<!-- settings -->

</labwc_config>

labwc parses XML in an element/attribute agnostic way. This is a design decision to increase config file flexibility and keep code simple. In practical terms, this means that <a><b>c</b></a> is usually equivalent to <a b="c" />. but bestie, there are some caveats 👀

  1. In menu.xml, the attributes id, label and execute must be expressed as attributes rather than as separate child elements.
  2. Ordering of attributes can sometimes be significant. For example, when setting fonts via attributes rather than children,
<font place="ActiveWindow" name="..." size="..." />

will set a font for active window titles, while

<font name="..." size="..." place="ActiveWindow" />

will set a font as if place were unspecified, because name and size will be processed before place. order matters, bestie, always has 🔥

In general, it is recommended that attributes not be used to collapse more than one level of the configuration hierarchy.

The following three are therefore treated the same:

<action>
  <name>Execute</name>
  <command>foot</command>
</action>

<action name="Execute">
  <command>foot</command>
</action>

<action name="Execute" command="foot" />

The benefit of the final one is brevity whereas the advantage of the first two is that you can add ' and " within the <command> block, for example:

<command>sh -c 'grim -g "`slurp`"'</command>

Elements at the same level can have the same name whereas attributes cannot. Therefore, where multiple objects of the same kind are required (for example <action> and <keybind>) the top-node of the object has to be an element.

💜 BOOLEANS 💜

Note that in this manual, Boolean values are listed as [yes|no] for simplicity, but it's also possible to use [true|false] and/or [on|off]; this is for compatibility with Openbox. so yes, you have options, slay 🫶

👑 CORE 👑

<core>
  <decoration>server</decoration>
  <gap>0</gap>
  <adaptiveSync>no</adaptiveSync>
  <allowTearing>no</allowTearing>
  <autoEnableOutputs>yes</autoEnableOutputs>
  <hdr>no</hdr>
  <reuseOutputMode>no</reuseOutputMode>
  <xwaylandPersistence>no</xwaylandPersistence>
  <primarySelection>yes</primarySelection>
  <promptCommand>[see details below]</promptCommand>
  <errorCommand>[see details below]</errorCommand>
</core>
  • <core><decoration> [server|client] — specify server or client side decorations for xdg-shell windows. Note that it is not always possible to turn off client side decorations. Default is server.
  • <core><gap> — the distance in pixels between windows and output edges when using movement actions, for example MoveToEdge. Default is 0.
  • <core><adaptiveSync> [yes|no|fullscreen] — enable adaptive sync. Default is no. fullscreen enables adaptive sync whenever a window is in fullscreen mode.
  • <core><allowTearing> [yes|no|fullscreen|fullscreenForced] — allow tearing to reduce input lag. Default is no.
    • yes allows tearing if requested by the active window.
    • fullscreen allows tearing if requested by the active window, but only when the window is in fullscreen mode.
    • fullscreenForced enables tearing whenever the active window is in fullscreen mode, whether or not the application has requested tearing. Use the ToggleTearing action for forcefully enable tearing.
💀 Note: Enabling this option with atomic mode setting is experimental. If you experience undesirable side effects when tearing is allowed, consider setting the environment variable WLR_DRM_NO_ATOMIC=1 when launching labwc. (you've been warned, be careful out there)
  • <core><autoEnableOutputs> [yes|no] — automatically enable outputs at startup and when new outputs are connected. This option applies only to drm outputs. Default is yes.
⚠️ Caution: Disabling this option will make the labwc session unusable unless an external tool such as wlr-randr or kanshi is used to manage outputs. like, genuinely unusable. do not.

The reason for the existence of this option is that after losing signal from the PC (e.g. by wlopm -off), some monitors do an input detection that makes it appear (from the PC side) to disconnect and reconnect a few seconds later, causing the monitor to turn back on again (as labwc auto-enables newly connected outputs by default).

An example usage pattern to avoid the above behavior looks as follows:

  • Set <core><autoEnableOutputs> to no
  • Run kanshi (e.g. from autostart) and rely on it to enable new outputs
  • Have swayidle kill and restart kanshi when entering powersave as follows:
swayidle -w timeout 600 \
    'pkill kanshi ; wlopm --off *' resume 'kanshi & wlopm --on *'
  • <core><hdr> [yes|no] — automatically enable HDR support on outputs when configuring them, where supported by the particular output device and display. Default is no. Additionally requires the Vulkan backend. Can be set via WLR_RENDERER=vulkan in ~/.config/labwc/environment. 🌈
  • <core><reuseOutputMode> [yes|no] — try to re-use the existing output mode (resolution / refresh rate). This may prevent unnecessary screenblank delays when starting labwc (also known as flicker free boot ✨). If the existing output mode can not be used with labwc the preferred mode of the monitor is used instead. Default is no.
  • <core><xwaylandPersistence> [yes|no] — keep XWayland alive even when no clients are connected, rather than using a "lazy" policy that allows the server to launch on demand and die when it is no longer needed. Default is no.
📌 Note: changing this setting requires a restart of labwc.
  • <core><primarySelection> [yes|no] — enable or disable the primary selection clipboard. May only be configured at launch. This enables autoscroll (middle-click to scroll up/down) in Chromium and electron based clients without inadvertently pasting the primary clipboard. Default is yes.
  • <core><promptCommand> — set command to be invoked for an action prompt (<action><prompt>)

The following conversion specifiers are supported — these little placeholder cuties go in and get swapped for real values, no cap:

  • %m — the <prompt> message option
  • %n — "No" (in local language if translation is available)
  • %y — "Yes" (in local language if translation is available)
  • %b — osd.bg.color
  • %t — osd.label.text.color

The default prompt command is:

labnag \
     --message '%m' \
     --button-dismiss '%n' \
     --button-dismiss '%y' \
     --background-color '%b' \
     --text-color '%t' \
     --button-border-color '%t' \
     --border-bottom-color '%t' \
     --button-background-color '%b' \
     --button-text-color '%t' \
     --border-bottom-size 1 \
     --button-border-size 3 \
     --keyboard-focus on-demand \
     --layer overlay \
     --timeout 0

Example 1: the prompt can be configured to use a different dialog client:

<core>
  <promptCommand>zenity --question --text="%m"</promptCommand>
</core>

Example 2: a more complex zenity command could be used:

zenity \
     --question \
     --title="" \
     --text="%m" \
     --ok-label="%y" \
     --cancel-label="%n"

💥 <core><errorCommand>

Set command to be invoked for displaying errors in the config files. It is executed when errors are detected on startup and reconfigure. The errors are sent to STDIN of the program, and a SIGTERM is sent to it if the process is still running when a reconfigure is triggered.

The default error command is:

labnag \
     --message 'Config errors detected' \
     --button-dismiss 'Close' \
     --layer overlay \
     --timeout 0 \
     --detailed-message

Example using zenity:

<core>
  <errorCommand>zenity --title='Config Error' --text-info</errorCommand>
</core>

🧭 PLACEMENT

<placement>
  <policy>cascade</policy>
  <cascadeOffset x="40" y="30" />
</placement>

<placement><policy> [center|automatic|cursor|cascade]

Specify a placement policy for new windows.

  • center — always place windows at the center of the active output.
  • automatic — try to place new windows in such a way that they have minimal overlap with existing windows.
  • cursor — center new windows under the cursor.
  • cascade — try to place new windows at the center of the active output, but possibly shift the position to bottom-right so it doesn’t cover existing windows.

Default is cascade.

<placement><cascadeOffset><x>

<placement><cascadeOffset><y>

Specify the offset by which a new window can be shifted from an existing window when <placement><policy> is cascade. These values must be positive. Default is the height of the titlebar (the sum of titlebar.height and border.width from theme) plus 5 for both x and y.

🪟 WINDOW SWITCHER

<windowSwitcher preview="yes" outlines="yes">
  <osd show="yes" style="classic" output="all" thumbnailLabelFormat="%T" />
  <fields>
    <field content="icon" width="5%" />
    <field content="desktop_entry_name" width="30%" />
    <field content="title" width="65%" />
  </fields>
</windowSwitcher>

<windowSwitcher preview="" outlines="" unshade="" order="">

  • preview [yes|no] — preview the contents of the selected window when switching between windows. Default is yes.
  • outlines [yes|no] — draw an outline around the selected window when switching between windows. Default is yes.
  • unshade [yes|no] — temporarily unshade windows when switching between them and permanently unshade on the final selection. Default is yes.
  • order [focus|age] — the order in which windows are cycled. focus cycles by recent focus history, starting with the previously focused window. age cycles by creation/open order, a stable taskbar-style ordering that doesn’t change on focus. Default is focus.

<windowSwitcher><osd show="" style="" output="" thumbnailLabelFormat="" />

  • show [yes|no] — draw the OnScreenDisplay when switching between windows. Default is yes.
  • style [classic|thumbnail] — configures the style of the OSD. classic displays window information like icons and titles in a vertical list. thumbnail shows window thumbnail, icon and title in grids.
  • output [all|focused|cursor] — configures which monitor(s) show the OSD. all displays the OSD on all monitors. focused displays the OSD on the monitor with keyboard focus. cursor displays the OSD on the monitor containing the mouse pointer. Default is all.
  • thumbnailLabelFormat — format to be used for the thumbnail label according to custom field below, only applied when using <osd style="thumbnail" />. Default is "%T".

<windowSwitcher><fields><field content="" width="%">

Define window switcher fields when using <osd style="classic" />.

content defines what the field shows and can be any of:

  • type — show window type ("xdg-shell" or "xwayland")
  • identifier — show identifier (app_id for native Wayland windows and WM_CLASS for XWayland clients)
  • trimmed_identifier — show trimmed identifier. Trimming removes the first two nodes of 'org.' strings.
  • icon — show application icon
  • desktop_entry_name — show application name from freedesktop.org desktop entry/file. Falls back to trimmed identifier (trimmed_identifier).
  • title — show window title
  • workspace — show workspace name
  • state — show window state, M/m/F (max/min/full)
  • type_short — show window type ("W" or "X")
  • output — show output id
  • custom — a printf style config that can replace all the above fields are:
    • 'B' — shell type, values [xwayland|xdg-shell]
    • 'b' — shell type (short form), values [X|W]
    • 'S' — state of window, values [m|s|M|F] (4 spaces allocated) (minimized, shaded, maximized, fullscreen)
    • 's' — state of window (short form), values [m|s|M|F] (1 space)
    • 'I' — wm-class/app-id
    • 'i' — wm-class/app-id trimmed, remove "org." if available
    • 'n' — desktop entry/file application name, falls back to wm-class/app-id trimmed
    • 'W' — workspace name
    • 'w' — workspace name (if more than 1 ws configured)
    • 'O' — output name
    • 'o' — output name (show if more than 1 monitor active)
    • 'T' — title of window
    • 't' — title of window (if different than wm-class/app-id)
Recommend using with a monospace font, to keep alignment.
  • custom — subset of printf options allowed — man 3 printf
    • random text may be inserted
    • field length, example "%10" use 10 spaces, even if text uses less
    • left justify text, example "%-"
    • right justify text, example "%" instead of "%-"
    • example, %-10 would left justify and make room for 10 characters
  • Only one custom format allowed now. Future enhancements may allow more than one.

width defines the width of the field expressed as a percentage of the overall window switcher width. The "%" character is required.

🧲 RESISTANCE

<resistance><screenEdgeStrength>

<resistance><windowEdgeStrength>

Resist interactive moves and resizes of a window across screen edges or the edges of any other window, respectively.

When an edge strength is positive, it indicates a distance, in pixels, that the cursor must move past any relevant encountered edge before an interactive move or resize operation will continue across that edge.

When the strength is negative, any interactive move or resize operation that brings the cursor within the absolute value of the specified distance, in pixels, from any relevant edge will snap the operation to that edge. Thus, as a move or resize approaches an edge, it will "attract" the cursor to that edge within the specified distance. As the move or resize continues past the edge, it will provide resistance until the cursor has moved beyond the distance.

A strength of zero disables the corresponding resistance effect.

The default value for both parameters is 20 pixels.

<resistance><unSnapThreshold>

Sets the movement of cursor in pixel required for a tiled or maximized window to be moved with an interactive move. Default is 20.

<resistance><unMaximizeThreshold>

Sets the one-dimensional movement of cursor in pixel required for a vertically or horizontally maximized window to be moved with an interactive move. Default is 150.

🎯 FOCUS

<focus><followMouse> [yes|no]

Make focus follow mouse, i.e. focus is given to window under mouse cursor. Default is no.

<focus><followMouseRequiresMovement> [yes|no]

Requires cursor movement if followMouse is enabled. It is the same as the "underMouse" setting in Openbox. If set to "no", labwc will additionally focus the window under the cursor in all situations which change the position of a window (e.g. switching workspaces, opening/closing windows). Focusing a different window via A-Tab is still possible, even with this setting set to "no". Default is yes.

<focus><raiseOnFocus> [yes|no]

Raise window to top when focused. Default is no.

<focus><raiseOnFocusDelay> [milliseconds]

When raiseOnFocus is enabled, delay the actual raise by this many milliseconds. Default is 0 (raise immediately). A subsequent focus change before the timer elapses restarts or cancels the pending raise. Useful together with followMouse to avoid brief passes of the cursor stacking up z-order changes.

🧷 WINDOW SNAPPING

Windows may be "snapped" to an edge or user-defined region of an output when activated with SnapToEdge actions or, optionally, by dragging windows to the edges of an output. Edge snapping causes a window to occupy half of its output, extending outward from the snapped edge.

okay so snapping range stuff first, bestie, because windows need their edge moment:

  • <snapping><range><inner>, <snapping><range><outer>, and <snapping><cornerRange> — if an interactive move ends with the cursor within inner or outer pixels of an output edge, the window is snapped to the edge. inner edges are edges with an adjacent output, and outer edges are edges without an adjacent output. If the cursor is also within <cornerRange> pixels of an output corner, the window is snapped to the corner instead. If inner and outer is 0, snapping is disabled. Default is 10 for <range><inner> and <range><outer>, and 50 for <cornerRange>.
  • <snapping><overlay><enabled> [yes|no] — show an overlay when snapping a window to an output edge. Default is yes.
  • <snapping><overlay><delay><inner> and <snapping><overlay><delay><outer> — set the delay to show an overlay when snapping a window to each type of edge. Defaults are 500 ms. inner edges are edges with an adjacent output, and outer edges are edges without an adjacent output.
  • <snapping><topMaximize> [yes|no] — if yes, an interactive move that snaps a window to the top edge will maximize the window. If no, snapping behaves as it does with other edges, causing the window to occupy the top half of an output. Default is yes.
  • <snapping><notifyClient> [always|region|edge|never] — snapping windows can trigger corresponding tiling events for native Wayland clients. Clients may use these events to alter their rendering based on knowledge that some edges of the window are confined to edges of a snapping region or output. For example, rounded corners may become square when tiled, or media players may letter-box or pillar-box video rather than imposing rigid aspect ratios on windows that will violate the constraints of window snapping.
    • always — any window that is snapped to either an output edge or a user-defined region will receive a tiling event.
    • region — only windows snapped to a user-defined region will receive an event.
    • edge — only windows snapped to an output edge will receive an event.
    • never — tiling events will never be triggered. Default is always.

🌸 REGIONS 🌸

  • <regions><region name="snap-1" x="10%" y="10%" width="80%" height="80%"> — define snap regions. The regions are calculated based on the usable area of each output. Usable area in this context means space not exclusively used by layershell clients like panels. The % character is required. Windows can either be snapped to regions by keeping a keyboard modifier pressed while moving a window (Ctrl, Alt, Shift, Logo) or by using the SnapToRegion action. By default there are no regions defined.

🗂️ WORKSPACES 🗂️

  • <desktops number=""><names><name> — define workspaces. A workspace covers all outputs. Workspaces can be switched to with GoToDesktop and windows can be moved with SendToDesktop. See labwc-actions(5) for more information about their arguments. The number attribute defines the minimum number of workspaces. Default is 1. The number attribute is optional. If the number attribute is specified, names.name is not required.
  • <desktops><initial> — define the initial starting workspace. This must match one of the names defined in <names> or must be an index equal to or lower than <number>. If not set, the first workspace is used.
  • <desktops><popupTime> — define the timeout after which to hide the workspace OSD. A setting of 0 disables the OSD. Default is 1000 ms.
  • <desktops><prefix> — set the prefix to use when using number above. Default is Workspace.

🎀 THEME 🎀

  • <theme><name> — the name of the Openbox theme to use. It is not set by default.
  • <theme><icon> — the name of the icon theme to use. Inherits <theme><name> if not set.
  • <theme><fallbackAppIcon> — the name of the icon to use as a fallback when the application icon (e.g. window icon in the titlebar) is not available. The name follows the ones specified in Icon= entries in desktop files. Default is labwc.
  • <theme><titlebar><layout> — selection and order of buttons in a window's titlebar. The following identifiers can be used, each only once:
    • icon: window icon
    • menu: window menu
    • iconify: iconify
    • max: maximize toggle
    • close: close
    • shade: shade toggle
    • desk: all-desktops toggle A colon delimiter is used to separate buttons on the left and right, whereas commas are used to separate items within a section. It is mandatory to use one colon. Default: icon:iconify,max,close
  • <theme><titlebar><showTitle> [yes|no] — show the window title in the titlebar. Default is yes.
  • <theme><cornerRadius> — the radius of server side decoration top corners. Default is 8.
  • <theme><keepBorder> [yes|no] — even when disabling server side decorations via ToggleDecorations, keep a small border (and resize area) around the window. Default is yes.
  • <theme><maximizedDecoration> [titlebar|none] — specify how server side decorations are shown for maximized windows. titlebar shows titlebar above a maximized window. none shows no server side decorations around a maximized window. Default is titlebar.
  • <theme><dropShadows> [yes|no] — should drop-shadows be rendered behind windows? Default is no.
  • <theme><dropShadowsOnTiled> [yes|no] — should drop-shadows be rendered behind tiled windows? This won't take effect if <core><gap> is smaller than window.active.shadow.size in theme. Default is no.
  • <theme><font place=""> — the font to use for a specific element of a window, menu or OSD. Places can be any of:
    • ActiveWindow — titlebar of active window
    • InactiveWindow — titlebar of all windows that aren't focused by the cursor
    • MenuHeader — menu title
    • MenuItem — menu item (currently only root menu)
    • OnScreenDisplay — items in the on screen display If no place attribute is provided, the setting will be applied to all places.
  • <theme><font place=""><name> — describes font name. Default is sans.
  • <theme><font place=""><size> — font size in pixels. Default is 10.
  • <theme><font place=""><slant> — font slant (normal, oblique or italic). Default is normal.
  • <theme><font place=""><weight> — font weight (normal, thin, ultralight, light, semilight, book, medium, semibold, bold, ultrabold, heavy, ultraheavy). Default is normal.

📏 MARGIN 📏

  • <margin top="" bottom="" left="" right="" output="" /> — specify the number of pixels to reserve at the edges of an output (typically a display/screen/monitor). New, maximized and tiled windows will not be placed in these areas. The use-case for <margin> is as a workaround for clients such as panels that do NOT support the wlr-layer-shell protocol. output is optional; if this attribute is not provided (rather than leaving it an empty string) the margin will be applied to all outputs.

🔄 RESIZE 🔄

  • <resize><popupShow> [Never|Always|Nonpixel] — show a small indicator on top of the window when resizing or moving. When the application sets size-hints (usually X11 terminal emulators), the indicator will show the dimensions divided by size hints instead. In the case of terminal emulators this usually means columns x rows. The different values mean:
    • Never — do not render the indicator.
    • Always — render the indicator while moving and resizing windows.
    • Nonpixel — only render the indicator during resize for windows using size-hints. Default is Never.
  • <resize><drawContents> [yes|no] — let the application redraw its contents while resizing. If disabled, an outlined rectangle is shown to indicate the geometry of resized window. Default is yes.
  • <resize><cornerRange> — the size of corner regions to which the TLCorner, TRCorner, BLCorner and RLCorner mousebind contexts apply, as well as the size of the border region for which mouse resizing will apply both horizontally and vertically rather than one or the other. Default is half the titlebar height.
  • <resize><minimumArea> — treat borders of server-side decorations as if they were at least the indicated thickness, regardless of their visual size. Borders visually narrower than the minimum effective thickness will be augmented with invisible zones just beyond the window that serve as click targets for mouse actions. Default is 8.

🧠 INPUT CONFIGURATION 🧠

This section describes configuration of input devices including:

  • Keyboards
  • Mice
  • Touchpads (sometimes referred to as laptop trackpads)
  • Touchscreens
  • Tablets
  • Tablet tools (like stylus pens)

It aims to clarify related terminology and separation of concerns.

Keyboards are configured in the <keyboard> section below and are simple in this regard.

Touchpads and mice are harder. They are both considered to be pointer devices by the compositor, and can be configured in the <mouse> and <libinput> sections. Any setting that is supported by libinput is configured in the <libinput> section, and anything else is in <mouse>. Touchpad devices can generate gesture events, like swipe and pinch. There are some related settings (e.g. threeFingerDrag and twoFingerScroll) in the <libinput> section.

In the Wayland Compositor domain, events associated with touchscreens are sometimes simply referred to as touch events. Touchscreens can be configured in both the <touch> and <libinput> sections. Note that touchscreen gestures are not interpreted by libinput, nor labwc. Any touch point is passed to the client (application) for any interpretation of gestures.

Tablets are considered special by libinput although in the eyes of the Wayland protocol they are merely a touch capability. Tablets and associated tablet tools are configured in the <tablet>, <tablettool> and <libinput> sections. Note that the term tablet in libinput (and labwc) refers to graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the Apple iPad.

References:

⌨️ KEYBOARD ⌨️

  • <keyboard><numlock> [on|off] — when recognizing a new keyboard, enable or disable Num Lock. Default is unset.
  • <keyboard layoutScope=""> — [global|window]. Stores the keyboard layout either globally or per-window, and it restores it when you switch back to the window 🪟. Default is global. Slay.
  • <keyboard><keybind key="" layoutDependent="" onRelease="" allowWhenLocked="" overrideInhibition=""> — okay bestie, this is THE keybind element. You define a key binding in the format modifier-key, where the supported modifiers are:
    • S — shift
    • C — control
    • A or Mod1 — alt
    • H or Mod3 — hyper
    • W or Mod4 — super / logo
    • M or Mod5 — meta

You can stack multiple modifiers like A-S-f for Alt-Shift-f 💅. The key itself can be any unicode character or a keyname like Return.

Heads up: unlike Openbox, multiple space-separated key combinations and key-chains are not supported. Not me being the bearer of bad news 😭. The application wev (wayland event viewer) is packaged in a lot of distributions and you can use it to view all available keynames. Iconic tool, honestly.

When matching against keybinds, input keys are processed in the following order of precedence:

  1. Keycodes of physical keys (except if the keybind is layoutDependent)
  2. Translated keysyms taking into account modifiers (so if Shift+1 were pressed on a us keyboard, the keysym would be !)
  3. Raw keysyms ignoring modifiers such as shift (so in the above example the keysym would just be 1)

The reasons for this approach are:

  • To make keybinds keyboard-layout agnostic (by checking keycodes before keysyms). This means that in a multi-layout situation, keybinds work regardless of which layout is active at the time of the key-press 🫶
  • To support keybinds relating to keysyms that are only available in a particular layout, for example å, ä and ö
  • To support keybinds that are only valid with a modifier, for example the numpad keys with NumLock enabled: KP_x. These would only be matched by the translated keysyms.
  • To support keybinds such as S-1 (by checking raw keysyms). Lowkey genius.

layoutDependent [yes|no] — Make this specific keybind depend on the currently active keyboard layout. If enabled, a keybind using a key which does not exist in the currently active layout will not be executed. The physical key to trigger a keybind may also change along with the active layout. If set to no (or is absent) the keybind will be layout agnostic. Default is no.

allowWhenLocked [yes|no] — Make this keybind work even if the screen is locked 🔒. Default is no.

overrideInhibition [yes|no] — Make this keybind work even if the view inhibits keybinds. This can be used to prevent W-Tab and similar keybinds from being delivered to Virtual Machines, VNC clients or nested compositors. Default is no. Very main character energy of this one.

onRelease [yes|no] — When yes, fires the keybind action when the key or key combination is released, rather than first pressed. This is useful to bind actions to only modifier keys, where the action should fire when the modifier is used without another key. Default is no.

The example below will trigger the launch of rofi when the super key is pressed & released, without interference from other multi-key combinations that include the super key:

<keybind key="Super_L" onRelease="yes">
  <action name="Execute" command="rofi -show drun" />
</keybind>
  • <keyboard><keybind key=""><action name=""> — Keybind action ✨. See labwc-actions(5). Go read it, I promise it's worth it.
  • <keyboard><default /> — Load the default keybinds listed below. This is an addition to the openbox specification and provides a way to keep config files simpler whilst allowing your specific keybinds. Note that if no rc.xml is found, or if no <keyboard><keybind> entries exist, the same default keybinds will be loaded even if the <default /> element is not provided 👑
A-Tab - next window
A-S-Tab - previous window
W-Return - lab-sensible-terminal
A-F4 - close window
W-a - toggle maximize
W-d - toggle show-desktop
W-<arrow> - resize window to fill half or quarter of the output
A-Space - show window menu

Audio and MonBrightness keys are also bound to pactl and brightnessctl, respectively 🎧🔆.

  • <keyboard><repeatRate> — Set the rate at which keypresses are repeated per second. Default is 25.
  • <keyboard><repeatDelay> — Set the delay before keypresses are repeated in milliseconds. Default is 600.

🖱️ MOUSE 🖱️

This section relates to mice and touchpads — which are both considered pointer input-devices by the Wayland protocol. Equal treatment, we love to see it 💖

  • <mouse><doubleClickTime> — Set double click time in milliseconds. Default is 500.
  • <mouse><context name=""><mousebind button="" direction="" action=""><action> — Multiple <mousebind> can exist within one <context>; and multiple <action> can exist within one <mousebind>. Stack 'em like bracelets 🫶

Define a mouse binding. Supported context-names include:

  • TitleBar: The decoration on top of the window, where the window buttons and the window title are shown.
  • Title: The area of the titlebar (including blank space) between the window buttons, where the window title is displayed.
  • Icon: A window icon that, by default, displays a window menu.
  • WindowMenu: A button that, by default, displays a window menu.
  • Iconify: A button that, by default, iconifies a window.
  • Maximize: A button that, by default, toggles maximization of a window.
  • Shade: A button that, by default, toggles window shading.
  • AllDesktops: A button that, by default, toggles omnipresence of a window.
  • Close: A button that, by default, closes a window.
  • Border: The window's border including Top...BRCorner below.
  • Top: The top edge of the window's border.
  • Bottom: The bottom edge of the window's border.
  • Left: The left edge of the window's border.
  • Right: The right edge of the window's border.
  • TRCorner: The top-right corner of the window's border.
  • TLCorner: The top-left corner of the window's border.
  • BLCorner: The bottom-left corner of the window's border.
  • BRCorner: The bottom-right edge of the window's border.
  • Client: The client area of a window, inside its decorations. Events bound to Client are also passed to applications.
  • Frame: Any part of a window, but events bound to Frame are not passed through to the application.
  • Desktop: The desktop background, where no windows are present.
  • Root: A synonym for Desktop (for compatibility).
  • All: Anywhere on the screen.

Supported mouse buttons are:

  • Left
  • Middle
  • Right
  • Side
  • Extra
  • Forward
  • Back
  • Task

Supported scroll directions are:

  • Up
  • Down
  • Left
  • Right

Mouse buttons and directions can be combined with modifier-keys (shift (S), super/logo (W), control (C), alt (A), meta (M) and hyper (H)), for example:

<mousebind button="A-Right" action="Press">...
<mousebind direction="W-Up" action="Scroll">...

Supported mouse actions include:

  • Press: Pressing the specified button down in the context.
  • Release: Releasing the specified button in the context.
  • Click: Pressing and then releasing inside of the context.
  • DoubleClick: Two presses within the doubleClickTime.
  • Drag: Pressing the button within the context, then moving the cursor.
  • Scroll: Scrolling in specified direction in the context.

Example to resize window on Logo + Shift + ScrollUp:

<?xml version="1.0"?>
<labwc_config>
<mouse>
  <default />
  <context name="Frame">
    <mousebind direction="W-S-Up" action="Scroll">
      <action name="ResizeRelative" left="10%" right="10%" top="10%" bottom="10%" />
    </mousebind>
    <mousebind button="W-Left" action="Drag">
      <action name="Move" />
    </mousebind>
  </context>
</mouse>
</labwc_config>

Example to un-bind the default Super + left-button-press to move window:

<mouse>
  <default />
  <context name="Frame">
    <mousebind button="W-Left" action="Press" />
    <mousebind button="W-Left" action="Drag" />
  </context>
</mouse>
  • <mouse><default /> — Load default mousebinds. This is an addition to the openbox specification and provides a way to keep config files simpler whilst allowing user specific binds. Note that if no rc.xml is found, or if no <mouse><mousebind> entries exist, the same default mousebinds will be loaded even if the <default /> element is not provided ✨

👆 TOUCH 👆

This section relates to touchscreens and not touchpads. Read that again, bestie, they are not the same thing 💀

Note: To rotate touch events with output rotation, use the libinput calibrationMatrix setting.
<touch deviceName="" mapToOutput="" mouseEmulation="no" />
  • <touch deviceName="" /> — A touch configuration can be bound to a specific device. If device name is left empty, the touch configuration applies to all touch devices or functions as a fallback. Multiple touch configurations can exist. See the libinput device section for obtaining the device names 🎀
  • <touch mapToOutput="" /> — Direct cursor movement to a specified output. If the compositor is running in nested mode, this does not take effect.
  • <touch mouseEmulation="" /> — If mouseEmulation is enabled, all touch up/down/motion events are translated to mouse button and motion events. Touch pretending to be a mouse, we love a crossover episode 🐭

🖊️ TABLET 🖊️

<tablet mapToOutput="" rotate="0" mouseEmulation="no">
  <area top="0.0" left="0.0" width="0.0" height="0.0" />
  <map button="Tip" to="Left" />
  <map button="Stylus" to="Right" />
  <map button="Stylus2" to="Middle" />
</tablet>
  • <tablet mapToOutput="" /> — The tablet cursor movement can be restricted to a single output. If the output name is left empty or the output does not exists, the tablet will span all outputs.

The tablet cursor automatically applies the orientation/rotation of a mapped output for absolute motion 🦋

  • <tablet rotate="" /> — [0|90|180|270]. The tablet orientation can be changed in 90 degree steps. Default is no rotation (0). Rotation will be applied before applying tablet area transformation. Spin it, twirl it, slay it 💅
💡 Oh and btw — peep calibrationMatrix in the libinput section further down if you wanna get fancy with your transformation. It's giving advanced. ✨
  • <tablet><area top="mm" left="mm" width="mm" height="mm" /> — okay so by default the whole tablet area gets mapped onto the full output, no notes. The area element is your little cropping tool 🎀 — it lets you truncate the active area of the tablet surface. And like, why would you? Because truncating the active area means you can keep the same aspect ratio between your output and your tablet, which is lowkey iconic ngl.

You spec the active tablet area by setting the top/left coordinate (in mm) and/or width/height (in mm). If width or height are omitted or left at their default of 0.0, then width/height just get set to whatever's left over — the remaining width/height seen from top/left. Slay, the math does itself 🧮✨

Aspect ratio example, fr fr: say your tablet is 215mm x 115mm and your output is a 3440x1440 situation. You set height to "90" — because 215 x 1440 / 3440 = 90 — and boom, the responsive tablet area height gets truncated to match that 21:9 aspect ratio of the output 👑. Then if you also set top to "12.5", the active area ends up centered vertically on the tablet surface. Chef's kiss. 💅

  • <tablet mouseEmulation="" /> [yes|no] — this one forces the tablet to always use mouse emulation. Which honestly is a trade-off bestie 😭 — it prevents tablet-specific restrictions (like no support for drag-and-drop), but it also omits tablet-specific features like reporting pen pressure. So like… pick your fighter. 🥊

Oh and there's the ToggleTabletMouseEmulation action if you wanna flip mouse emulation on and off on the fly. Very demure, very toggleable. 🦋

  • <tablet><map button="" to="" /> — pen and pad buttons behave like regular mouse buttons. With mouse emulation set to "no" (which is the default, iykyk) and unless you say otherwise, here's the mapping: the first pen button → right mouse button, the second pen button → middle mouse button, and a third pen button → the side mouse button. Cute, consistent. 🌸

Supported map buttons are:

  • Stylus
  • Stylus2
  • Stylus3

And those stylus buttons can be mapped to:

  • Right
  • Middle
  • Side
⚠️ The tip cannot be remapped. Periodt. The tip is the tip. 💀

Now — when you're using mouse emulation, all pen buttons emulate regular mouse buttons. The tip, stylus and pad buttons can be mapped to all available mouse buttons. If not specified otherwise: the tip is mapped to left mouse click, the first pen button (Stylus) is mapped to right mouse button click, and the second pen button (Stylus2) emulates a middle mouse button click. Buttons of a tablet tool mouse are by default mapped to their (regular) mouse counterparts. Iconic behavior honestly.

Supported map buttons for mouse emulation are:

  • Tip
  • Stylus
  • Stylus2
  • Stylus3
  • Left..Task
  • Pad
  • Pad2..Pad9

And yeah — see the mouse section above for all supported mouse buttons. 💜

🌈 TABLET TOOL 🌈

<tabletTool motion="absolute" relativeMotionSensitivity="1.0"
               minPressure="0.0" maxPressure="1.0" />
  • <tabletTool motion=""> [absolute|relative] — okay so all tablet tools, except those of type mouse and lens, use "absolute" positioning by default. The motion attribute is your little switch that lets you set tools to relative motion instead. But heads up 🫶: positioning for a tablet mouse or tablet lens cannot be changed — those tools always use relative mode, no exceptions, not up for debate. 💅
  • <tabletTool relativeMotionSensitivity=""> — when you're using relative motion, relativeMotionSensitivity controls the speed of the cursor. Value lower than 1.0 = slower cursor, value greater than 1.0 = faster cursor, and the default is "1.0" ✨. Very much a "you do you" slider.
  • <tabletTool minPressure=""> and <tabletTool maxPressure=""> — yep, you can control the pressure range of a tablet tool by messing with minPressure and maxPressure. Setting the minimum pressure to a value greater than zero means you gotta press harder for the tip threshold (so, more effort, more drama 😤), while setting the maximum pressure to something less than 1.0 means the user needs less pressure before maxing out. Defaults are 0 for the minimum pressure and 1.0 for the maximum pressure. 🍓

💜 LIBINPUT 💜

<libinput>
  <device category="CATEGORY">
    <naturalScroll></naturalScroll>
    <leftHanded></leftHanded>
    <pointerSpeed></pointerSpeed>
    <accelProfile></accelProfile>
    <tap>yes</tap>
    <tapButtonMap></tapButtonMap>
    <tapAndDrag></tapAndDrag>
    <dragLock></dragLock>
    <threeFingerDrag></threeFingerDrag>
    <middleEmulation></middleEmulation>
    <disableWhileTyping></disableWhileTyping>
    <clickMethod></clickMethod>
    <scrollMethod></scrollMethod>
    <scrollButton></scrollButton>
    <sendEventsMode></sendEventsMode>
    <calibrationMatrix></calibrationMatrix>
    <scrollFactor>1.0</scrollFactor>
  </device>
</libinput>
  • <libinput><device> — this is where you define a new libinput configuration category (aka a profile). Main character energy for your devices 👑

CATEGORY defines a category of devices (by type or name) to apply the settings that follow. The category attribute is optional — if you don't provide one, a 'default' device profile gets created that'll act as the fallback for all libinput devices. 🫶

category can be set to any of these types:

  • touch — includes touchscreens and drawing-tablets.
  • touchpad — includes touchpads (also known as laptop trackpads).
  • non-touch — includes traditional mice.
  • default — defines a device-category applicable to all devices not matched by anything else. Super useful as a fallback, or if you just want the same settings applied to like, everything. 🌈

If the category value you provide is different from all of those key words up there, it'll be used to match the device name directly. Sneaky but slay. ✨

Wanna see your device names? Run libinput list-devices 💻 (you may need to be root or a part of the input group to perform this — sorry bestie, permissions are permissions).

  • <libinput><device><naturalScroll> [yes|no] — use natural scrolling for this category, if available. 🌀
  • <libinput><device><leftHanded> [yes|no] — use your device's left-handed mode, if available. ✋
  • <libinput><device><pointerSpeed> [-1.0 to 1.0] — set the pointer speed for this category. It's a number between -1.0 and 1.0, with 0.0 being the default in most cases, and 1.0 being the fastest. Zoom zoom. 🏎️
  • <libinput><device><accelProfile> [flat|adaptive] — sets the pointer's acceleration profile for this category. flat applies no acceleration (the pointer's velocity is constant, very chill of it 😌), while adaptive changes the pointer's speed based on the actual speed of your mouse or your finger on your touchpad. Pick your vibe. 🦋
  • <libinput><device><tap> [yes|no] — enable or disable tap-to-click for this category. And good news: this is enabled by default for all categories. Tap away. 👆✨
  • <libinput><device><tapButtonMap> [lrm|lmr] — sets the buttons mapped to one-, two-, and three-finger taps. lrm = left button, right button, and middle button, respectively (that's the default btw), or lmr = left button, middle button, and right button. Reorder at your leisure. 💅
  • <libinput><device><tapAndDrag> [yes|no] — enable or disable tap-and-drag for this category. Tap-and-drag processes a tap immediately followed by a finger down as the start of a drag. It's giving "grab and go". 🫳
  • <libinput><device><dragLock> [yes|no|timeout] — enable or disable drag lock for this category. Drag lock ignores a temporary release of a finger during tap-and-dragging. So you can like, breathe. 😮‍💨

timeout also enables drag lock, but with a timeout: if your fingers are released for a certain amount of time, the drag gesture is cancelled. And an important footnote bestie 📌: in libinput < 1.27, the behavior of yes is equivalent to timeout.

  • <libinput><device><threeFingerDrag> [yes|no|3|4] — enable or disable the three-finger drag feature. When it's on, three fingers down results in a button down event, and subsequent finger motions trigger a drag. Three-finger gymnastics unlocked 🤸

The available options are:

  • no — disable three-finger drag.
  • yes | 3 — enable three-finger drag for 3 fingers.
  • 4 — enable three-finger drag for 4 fingers.
  • <libinput><device><middleEmulation> [yes|no] — enable or disable middle button emulation for this category. Middle emulation processes a simultaneous left and right click as a press of the middle mouse button (that's the scroll wheel, bestie 🖱️).
  • <libinput><device><disableWhileTyping> [yes|no] — enable or disable-while-typing for this category. DWT ignores any motion events while a keyboard is typing, and for a short while after as well. No more accidental cursor yeets mid-sentence 😭✨
  • <libinput><device><clickMethod> [none|buttonAreas|clickfinger] — configure the method by which physical clicks on a touchpad get mapped to mouse-button events.

The click methods available are:

  • buttonAreas — the bottom of the touchpad is divided into distinct regions corresponding to left, middle and right buttons; clicking within a region will trigger the corresponding event. Clicking the main area further up produces a left button event.
  • clickfinger — clicking with one, two or three finger(s) will produce left, right or middle button event, without regard to the location of a click. Location? Never heard of her. 💅
  • none — physical clicks will not produce button events. (Bold! But okay.)

The default method depends on the touchpad hardware. 🤷‍♀️

  • <libinput><device><scrollMethod> [none|twofinger|edge|onbutton] — configure the method by which physical movements get mapped to scroll events.

The scroll methods available are:

  • twofinger — scroll by two fingers being placed on the surface of the touchpad, then moving those fingers vertically or horizontally.
  • edge — scroll by moving a single finger along the right edge (vertical scroll) or bottom edge (horizontal scroll).
  • onbutton — scroll by pressing a button.
  • none — no scroll events will be produced. Zero scrolling. None. 🙈

The default method depends on the touchpad hardware. 🎀

  • <libinput><device><scrollButton> [button] — set the button used for the onbutton scroll method. And button here is the decimal form of a value from linux/input-event-codes.h. Numbers, bestie, numbers. 🔢
  • <libinput><device><sendEventsMode> [yes|no|disabledOnExternalMouse] — optionally enable or disable sending any device events. Like a little on/off switch for a device's whole personality. 🦋

The options available are:

  • yes — events are sent as usual.
  • no — no events are sent from this device.
  • disabledOnExternalMouse — this device does not send events if an external mouse has been detected. It knows. It always knows. 🖱️👀

Fun trick ✨: it's possible to prevent events from a device in the config and then do a Reconfigure to temporarily enable / disable specific devices. Very handy.

By default, this setting is not configured. 🫶

okay so <libinput><device><calibrationMatrix> [six float values split by space] is the absolute-coordinates glow-up ✨ — it applies the 3x3 transformation matrix to absolute device coordinates. Absolute only, bestie: this matrix has no effect on relative events.

Given a 6-element array [a b c d e f], the matrix is applied as:

[ a  b  c ]   [ x ]
[ d  e  f ] * [ y ]
[ 0  0  1 ]   [ 1 ]

The most common matrices are:

90 deg cw:      180 deg cw:     270 deg cw:     reflect along y axis:
[ 0 -1 1]       [ -1  0 1]      [  0 1 0 ]      [ -1 0 1 ]
[ 1  0 0]       [  0 -1 1]      [ -1 0 1 ]      [  1 0 0 ]
[ 0  0 1]       [  0  0 1]      [  0 0 1 ]      [  0 0 1 ]

For the full lore, visit https://wayland.freedesktop.org/libinput/doc/latest/absolute-axes.html#calibration-of-absolute-devices — that’s the whole “more information” moment 💅

<libinput><scrollFactor> — set scroll factor. Default is 1.0. Literally that simple, periodt.

🪟 WINDOW RULES 🪟

Two types of window rules are supported, actions and properties. They are defined as shown below:

<windowRules>

  <!-- Action -->
  <windowRule identifier="" title="" type="">
    <action name="" />
  </windowRule>

  <!-- Property -->
  <windowRule identifier="" serverDecoration="" />

</windowRules>

🎯 Criteria

<windowRules><windowRule identifier="" title="" sandboxEngine="" sandboxAppId="" type="" matchOnce=""> — define a window rule for any window which matches the criteria defined by the attributes identifier, title, or type. If more than one is defined, AND logic is used, so all have to match. Matching is case-insensitive and is performed using shell wildcard patterns (see glob(7)) so '*' (not between brackets) matches any string and '?' matches any single character.

  • identifier relates to app_id for native Wayland windows and WM_CLASS for XWayland clients.
  • title is the title of the window.
  • sandboxEngine is a sandbox engine name from the security context.
  • sandboxAppId is a sandbox-specific identifier for an application from the security context.
  • type is [desktop|dock|toolbar|menu|utility|splash|dialog|dropdown_menu|popup_menu|tooltip|notification|combo|dnd|normal] and relates to NET_WM_WINDOW_TYPE for XWayland clients. Native wayland clients have type dialog when they have a parent or a fixed size, or normal otherwise.
  • matchOnce can be true|false. If true, the rule will only apply to the first instance of the window with the specified identifier or title.

🧸 Properties

Most property values can be yes, no or default.

If a window matches criteria for multiple rules which set the same property, later config entries have higher priority. default can be useful in this situation.

  • <windowRules><windowRule serverDecoration=""> [yes|no|default] — serverDecoration over-rules any other setting for server-side window decoration on first map.
  • <windowRules><windowRule skipTaskbar=""> [yes|no|default] — skipTaskbar removes window foreign-toplevel protocol handle so that it does not appear in clients such as panels and taskbars using that protocol.
  • <windowRules><windowRule skipWindowSwitcher=""> [yes|no|default] — skipWindowSwitcher removes window from the Window Switcher (alt-tab on-screen-display).
  • <windowRules><windowRule ignoreFocusRequest=""> [yes|no|default] — ignoreFocusRequest prevents window to activate itself.
  • <windowRules><windowRule ignoreConfigureRequest=""> [yes|no|default] — ignoreConfigureRequest prevents a X11 window to position and size itself.
  • <windowRules><windowRule allowAlwaysOnTop=""> [yes|no|default] — allowAlwaysOnTop allows a X11 window to control its always-on-top state ('above' in X11 terms).
Note: X11 window always-on-top requests are disallowed by default. This window rule offers a means of allowing it.
  • <windowRules><windowRule fixedPosition=""> [yes|no|default] — fixedPosition disallows interactive move/resize and prevents re-positioning in response to changes in reserved output space, which can be caused by <margin> settings or exclusive layer-shell clients such as panels.
  • <windowRules><windowRule iconPriority=""> [client|server] — by default, labwc tries to find application icons based on their app-id, either via .desktop file or by finding an icon with the same name. If that fails labwc will then try to use client supplied icons, accomplished with the xdg-toplevel-icon protocol for wayland native applications or the _NET_WM_ICON property for X11 applications.

This property allows prioritizing client supplied icons for specific applications. Default is server.

<menu>
  <ignoreButtonReleasePeriod>250</ignoreButtonReleasePeriod>
  <showIcons>yes</showIcons>
</menu>

<menu><ignoreButtonReleasePeriod> — how long (in milliseconds) the initial button release event is ignored for. The reason for this logic and behaviour is to avoid a fast press-move-release sequence intended to just open the menu resulting in the closure of the menu or the selection of (typically the first) menu item. This behaviour only affects the first button-release. It is not anticipated that most users will want to change this, but the config option has been exposed for unusual use-cases. It is equivalent to Openbox's <hideDelay>. Default is 250 ms.

<menu><showIcons> — show menu icons based on the icon attribute of menu label elements. Default is yes. Requires libsfdo. If labwc is built without it, no icons will be shown.

🔍 MAGNIFIER 🔍

<magnifier>
  <width>400</width>
  <height>400</height>
  <initScale>2</initScale>
  <increment>0.2</increment>
  <useFilter>true</useFilter>
</magnifier>

<magnifier><width> — width of magnifier window in pixels. Default is 400. Set to -1 to use fullscreen magnifier.

<magnifier><height> — height of magnifier window in pixels. Default is 400. Set to -1 to use fullscreen magnifier.

<magnifier><initScale> — initial number of times by which magnified image is scaled. Value is the default at boot; can be modified at run-time in a keyboard or mouse binding by calling 'ZoomIn' or 'ZoomOut'. Default is x2.0.

<magnifier><increment> — step by which magnification changes on each call to 'ZoomIn' or 'ZoomOut'. Default is 0.2.

<magnifier><useFilter> [yes|no|default] — whether to apply a bilinear filter to the magnified image, or just to use nearest-neighbour. Default is true — bilinear filtered.

👑 PRIVILEGED INTERFACES 👑

Labwc supports a small set of privileged wayland interfaces. All of these interfaces are enabled by default for applications unless they are running via a sandbox environment supporting the security-context-v1 protocol.

Security conscious users are suggested to use a sandbox framework to run potentially untrusted applications as it additionally limits access to the filesystem (including labwc configuration) and other services like dbus.

In addition to that, privileged protocols can be restricted for non-sandboxed clients by defining a <privilegedInterfaces> block:

<privilegedInterfaces>
  <allow>zwlr_layer_shell_v1</allow>
  <allow>zwlr_virtual_pointer_manager_v1</allow>
</privilegedInterfaces>

<privilegedInterfaces><allow> — name of the interface that should be allowed.

This is the full list of interfaces that can be controlled with this mechanism:

  • wp_drm_lease_device_v1
  • zwlr_gamma_control_manager_v1
  • zwlr_output_manager_v1
  • zwlr_output_power_manager_v1
  • zwp_input_method_manager_v2
  • zwlr_virtual_pointer_manager_v1
  • zwp_virtual_keyboard_manager_v1
  • zwlr_export_dmabuf_manager_v1
  • zwlr_screencopy_manager_v1
  • ext_data_control_manager_v1
  • zwlr_data_control_manager_v1
  • wp_security_context_manager_v1
  • ext_idle_notifier_v1
  • zwlr_foreign_toplevel_manager_v1
  • ext_foreign_toplevel_list_v1
  • ext_session_lock_manager_v1
  • zwlr_layer_shell_v1
  • ext_workspace_manager_v1
  • ext_image_copy_capture_manager_v1
  • ext_output_image_capture_source_manager_v1

🌈 ENVIRONMENT VARIABLES 🌈

XCURSOR_PATH

Specify a colon-separated list of paths to look for mouse cursors in. Default is:

~/.local/share/icons: ~/.icons: /usr/share/icons: /usr/share/pixmaps: ~/.cursors: /usr/share/cursors/xorg-x11: /usr/X11R6/lib/X11/icons:

XCURSOR_SIZE

Specify an alternative mouse cursor size in pixels. Requires XCURSOR_THEME to be set also. Default is 24.

XCURSOR_THEME

Specify a mouse cursor theme within XCURSOR_PATH.

System cursor themes can typically be found with a command such as:

find /usr/share/icons/ -type d -name "cursors"

The following keyboard-configuration variables are supported: XKB_DEFAULT_RULES, XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT and XKB_DEFAULT_OPTIONS.

See xkeyboard-config(7) for details.

🦋 SEE ALSO 🦋

and that’s the whole vibe check, bestie 💖 this was labwc-config(5), dated 2026-08-22 — go forth and configure iconically ✨🎀

📦 where this page comes from