labwc-config

title: labwc-config(5)

text:
# labwc-config(5)

## NAME
labwc - configuration files

## DESCRIPTION
Labwc uses openbox-3.6 specification for configuration and theming, but does not support all options. The following files form the basis of the labwc configuration: rc.xml, menu.xml, autostart, shutdown, environment and xinitrc.

No configuration files are needed to start and run labwc.

In accordance with XDG Base Directory Specification, configuration files are searched for in the following 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. The same is the case for $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.

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. Thus, user-specific files will augment system-wide configurations, with conflicts favoring the user-specific alternative.

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.

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.

Please note that as labwc reloads the environment file(s) on reconfigure, recursive/circular assignments (for example FOO=$FOO:bar) should not be made.

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.

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.

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.

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" />`. However, 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,

will set a font for active window titles, while

will set a font as if place were unspecified, because name and size will be processed before place.

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.

### CORE

```
<core>

  <decoration>server</decoration>

  <gap>0</gap>

  <adaptiveSync>no</adaptiveSync>

  <allowTearing>no</allowTearing>

  <autoEnableOutputs>yes</autoEnableOutputs>

  <reuseOutputMode>no</reuseOutputMode>

  <xwaylandPersistence>no</xwaylandPersistence>

  <primarySelection>yes</primarySelection>

  <promptCommand>[see details below]</promptCommand>
</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.

<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.

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><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:

•%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"
```

### PLACEMENT

```
<placement>

  <policy>cascade</policy>

  <cascadeOffset x="40" y="30" />
</placement>
```

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

Specify a placement policy for new windows. The "center" policy will always place windows at the center of the active output. The "automatic" policy will try to place new windows in such a way that they will have minimal overlap with existing windows. The "cursor" policy will center new windows under the cursor. The "cascade" policy will try to place new windows at the center of the active output, but possibly shifts its position to bottom-right not to 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 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.

### 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.

<snapping><range><inner>

<snapping><range><outer>

<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 it's 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>

<snapping><overlay><delay><outer>

Sets 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 will behave 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.

•When always is specified, any window that is snapped to either an output edge or a user-defined region will receive a tiling event.

•When region is specified, only windows snapped to a user-defined region will receive an event.

•When edge is specified, only windows snapped to an output edge will receive an event.

•When never is specified, tiling events will never be triggered.

The 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 deliminator 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>

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><name>

Describes font name. Default is sans.

<theme><size>

Font size in pixels. Default is 10.

<theme><slant>

Font slant (normal, oblique or italic). Default is normal.

<theme><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:

•https://wayland.freedesktop.org/libinput/doc/latest/tablet-support.html

•https://wayland.freedesktop.org/libinput/doc/latest/gestures.html

### 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 restores it when switching back to the window. Default is global.

<keyboard><keybind key="" layoutDependent="" onRelease="" allowWhenLocked="">

Define a key binding in the format modifier-key, where supported modifiers are: •S (shift)

•C (control)

•A or Mod1 (alt)

•H or Mod3 (hyper)

•W or Mod4 (super / logo)

•M or Mod5 (meta)

Multiple modifiers can be combined like A-S-f for Alt-Shift-f. The key itself can be any unicode character or a keyname like Return.

Unlike Openbox, multiple space-separated key combinations and key-chains are not supported. The application "wev" (wayland event viewer) is packaged in a lot of distributions and can be used to view all available keynames.

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

•Keycodes of physical keys (except if keybind is layoutDependent)

•Translated keysyms taking into account modifiers (so if Shift+1 were pressed on a us keyboard, the keysym would be '!')

•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).

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.

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).

<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-<arrow> - resize window to fill half or quarter of the output

  A-Space - show window menu
```

Audio and MonBrightness keys are also bound to amixer 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.

<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>. 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, closses 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.

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.

### 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. See also calibrationMatrix in libinput section below for advanced transformation.

<tablet><area top="mm" left="mm" width="mm" height="mm" />

By default the complete tablet area is mapped to the full output. The area element can be used to truncate the active area of the tablet surface. By truncating the active area, it is e.g. possible to maintain the same aspect ratio between output and tablet. The active tablet area can be specified by setting the top/left coordinate (in mm) and/or width/height (in mm). If width or height are omitted or default (0.0), width/height will be set to the remaining width/height seen from top/left.

Aspect ratio example: The dimensions of the tablet are 215mm x 115mm and the output has a resolution of 3440x1440. When setting height to "90", because 215 x 1440 / 3440 = 90, the responsive tablet area height will be truncated to match the 21:9 aspect ratio of the output. By additionally setting top to "12.5", the active area is centered vertically on the tablet surface.

<tablet mouseEmulation="" /> [yes|no]

The tablet can be forced to always use mouse emulation. This prevents tablet specific restrictions, e.g. no support for drag-and-drop, but also omits tablet specific features like reporting pen pressure. Use the ToggleTabletMouseEmulation action for toggling between mouse emulation on and off.

<tablet><map button="" to="" />

Pen and pad buttons behave like regular mouse buttons.With mouse emulation set to "no", which is the default, and if not specified otherwise, the first pen button is mapped to the right mouse button, the second pen button to the middle mouse button and a third pen button is mapped to the side mouse button. Supported map buttons are:

•Stylus

•Stylus2

•Stylus3

The stylus buttons can be mapped to:

•Right

•Middle

•Side

The tip cannot be remapped.

When 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.

Supported map buttons for mouse emulation are:

•Tip

•Stylus

•Stylus2

•Stylus3

•Left..Task

•Pad

•Pad2..Pad9

See mouse section above for all supported mouse buttons.

### TABLET TOOL

```
<tabletTool motion="absolute" relativeMotionSensitivity="1" />
```

<tabletTool motion=""> [absolute|relative]

All tablet tools, except of type mouse and lens, use "absolute" positioning by default. The motion attribute allows to set tools to relative motion instead. Positioning for a tablet mouse or tablet lens cannot be changed, those tools always use relative mode.

<tabletTool relativeMotionSensitivity="">

When using relative motion, relativeMotionSensitivity controls the speed of the cursor. Using a value lower than 1.0 decreases the speed, using a value greater than 1.0 increases the speed of the cursor. The default is "1.0".

### 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>

    <sendEventsMode></sendEventsMode>

    <calibrationMatrix></calibrationMatrix>

    <scrollFactor>1.0</scrollFactor>

  </device>
</libinput>
```

<libinput><device>

Define a new libinput configuration category (profile). CATEGORY Defines a category of devices (by type or name) to apply the settings that follow. The category attribute as optional. If no category attribute is provided, a 'default' device profile will created that will act as the fallback for all libinput devices. Category can be set to any of the following 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. This can be useful for a fallback, or if you want the same settings to be applied to all devices.

If the provided category value is different from all of the above key words, it will be used to match the device name directly.

A list of device names can be obtained by running libinput list-devices (you may need to be root or a part of the input group to perform this).

<libinput><device><naturalScroll> [yes|no]

Use natural scrolling for this category if available.

<libinput><device><leftHanded> [yes|no]

Use your devices left-handed mode if available.

<libinput><device><pointerSpeed> [-1.0 to 1.0]

Set the pointer speed for this category. The speed is a number between -1.0 and 1.0, with 0.0 being the default in most cases, and 1.0 being the fastest.

<libinput><device><accelProfile> [flat|adaptive]

Set the pointer's acceleration profile for this category. Flat applies no acceleration (the pointers velocity is constant), while adaptive changes the pointers speed based the actual speed of your mouse or finger on your touchpad.

<libinput><device><tap> [yes|no]

Enable or disable tap-to-click for this category. This is enabled by default for all categories.

<libinput><device><tapButtonMap> [lrm|lmr]

Set the buttons mapped to one-, two-, and three-finger taps to the left button, right button, and middle button, respectively (lrm) (the default), or to left button, middle button, and right button (lmr).

<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.

<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. 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. 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 enabled, three fingers down will result in a button down event and subsequent finger motions triggers a drag. 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 (scroll wheel).

<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.

<libinput><device><clickMethod> [none|buttonAreas|clickfinger]

Configure the method by which physical clicks on a touchpad are 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 the 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.

•none - Physical clicks will not produce button events.

The default method depends on the touchpad hardware.

<libinput><device><scrollMethod> [none|twofinger|edge]

Configure the method by which physical movements on a touchpad are 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).

•none - No scroll events will be produced.

The default method depends on the touchpad hardware.

<libinput><device><sendEventsMode> [yes|no|disabledOnExternalMouse]

Optionally enable or disable sending any device events. 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 is possible to prevent events from a device in the config and then do a Reconfigure to temporarily enable / disable specific devices.

By default, this setting is not configured.

<libinput><device><calibrationMatrix> [six float values split by space]

Apply the 3x3 transformation matrix to absolute device coordinates. 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 ]
```

visit https://wayland.freedesktop.org/libinput/doc/latest/absolute-axes.html#calibration-of-absolute-devices for more information.

<libinput><scrollFactor>

Set scroll factor. Default is 1.0.

### 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 [desktop|dock|toolbar|menu|utility|splash|dialog|dropdown_menu| popup_menu|tooltip|notification|combo|dnd|normal] 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 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

```
<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.

### ENVIRONMENT VARIABLES
XCURSOR_THEME and XCURSOR_SIZE are supported to set cursor theme and size respectively. The default size is 24. 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
labwc(1), labwc-actions(5), labwc-theme(5)


labwc-menu

package: labwc-base

title: labwc-menu(5)

text:
# labwc-menu(5)

## NAME
labwc - menu file

## DESCRIPTION
Static menus are built based on the menu.xml file located at "~/.config/labwc" and equivalent XDG Base Directories.

## SYNTAX
The menu file must be entirely enclosed within <openbox_menu> and </openbox_menu> tags. Inside these tags, menus are specified as follows:

```
<!-- A toplevel menu -->
<menu id="external_menu_settings" label="External Settings" icon="preferences-other">

  <item label="Display setting">

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

  </item>
</menu>
<!-- Another toplevel menu -->
<menu id="">

  <!-- A menu entry with an action, for example to execute an application -->

  <item label="" icon="">

    <action></action>

  </item>

  <!-- A submenu defined elsewhere, uses external label and icon attributes -->

  <menu id="external_menu_settings" />

  <!-- Horizontal line -->

  <separator />

  <!-- An inline submenu -->

  <menu id="" label="" icon="">

    ...some content...

  </menu>

  <!-- Title -->

  <separator label="" />

  <!-- Pipemenu -->

  <menu id="" label="" icon="" execute="COMMAND" />
</menu>
```

menu.id (when at toplevel)

Define a menu tree. Each menu must be given an id, which is a unique identifier of the menu. This id is used to refer to the menu in a ShowMenu action. Default identifiers are •"root-menu" for the root window context menu

•"client-menu" for a window's titlebar context menu

•"client-list-combined-menu" for a list of all windows across all workspaces. Will change focus to the app that gets selected or go to workspace without activating any app if "Go there" is selected.

•"client-send-to-menu" shows all workspaces and sends current window to that workspace when selected.

menu.id (when nested under other <menu> element)

Link to a submenu defined elsewhere (by a <menu id=""> at toplevel).

menu.label

The title of the menu, shown in its parent. A label must be given when defining a menu unless it is the topmost menu element. Note that Openbox requires a label="" defined for topmost elements too, but for simplicity labwc handles these with or without the label attribute.

menu.icon

An icon to be rendered, shown in its parent. This argument is optional. See menu.item.icon for further details.

menu.item.label

The visible name of the menu item.

menu.item.icon

The name of an icon to be rendered in front of the menu entry. This attribute is optional. The name follows naming conventions of "Icon=" entries in .desktop files. If used, it is recommended to use the name of the icon only rather than a full path. This ensures that the icon will be looked up in the scale of the output where the menu is rendered. E.g. use of icon="vlc" is suggested over using icon="/usr/share/icons/hicolor/16x16/apps/vlc.png".

menu.item.action

See labwc-actions(5). Note: XML CDATA is supported for this node in order to maintain compatibility with obmenu-generator.

menu.separator

Horizontal line.

menu.separator.label

In a "separator" element, the label attribute transforms the separator from a horizontal line to a menu title (heading) with the text specified by label in it.

menu.execute

Command to execute for pipe menu. See details below.

## PIPE MENUS
Pipe menus are menus generated dynamically based on output of scripts or binaries. They are so-called because the output of the executable is piped to the labwc menu.

For any <menu id="" label="" execute="COMMAND"/> entry in menu.xml, the COMMAND will be executed the first time the item is selected (for example by cursor or keyboard input). The XML output of the command will be parsed and shown as a submenu. The content of pipemenus is cached until the whole menu (not just the pipemenu) is closed.

The content of the output must be entirely enclosed within <openbox_pipe_menu> tags. Inside these, menus are specified in the same way as static (normal) menus, for example:

```
<openbox_pipe_menu>

  <item label="Terminal">

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

  </item>
</openbox_pipe_menu>
```

Inline submenus and nested pipemenus are supported.

Note that it is the responsibility of the pipemenu executable to ensure that ID attributes are unique. Duplicates are ignored.

When writing pipe menu scripts, make sure to escape XML special characters such as "&" ("&"), "<" ("<"), and ">" (">").

A pipemenu can also be used to define the toplevel <menu> element. In this case the entire menu.xml file would be reduced to something like this (replacing obmenu-generator with the menu generator of your choice):

```
<?xml version="1.0"?>
<openbox_menu>

  <menu id="root-menu" label="" execute="obmenu-generator"/>
</openbox_menu>
```

## LOCALISATION
Available localisation for the default "client-menu" is only shown if no "client-menu" is present in menu.xml. Any menu definition in menu.xml is interpreted as a user-override.

## SEE ALSO
labwc(1), labwc-actions(5), labwc-config(5), labwc-theme(5)


labwc-theme

title: labwc-theme(5)

text:
# labwc-theme(5)

## NAME
labwc - theme files

## THEME
The theme engine aims to be compatible with openbox and themes will be searched for in the following order:

•${XDG_DATA_HOME:-$HOME/.local/share}/themes/<theme-name>/labwc/

•$HOME/.themes/<theme-name>/labwc/

•/usr/share/themes/<theme-name>/labwc/

•/usr/local/share/themes/<theme-name>/labwc/

•/opt/share/themes/<theme-name>/labwc/

•${XDG_DATA_HOME:-$HOME/.local/share}/themes/<theme-name>/openbox-3/

•$HOME/.themes/<theme-name>/openbox-3/

•/usr/share/themes/<theme-name>/openbox-3/

•/usr/local/share/themes/<theme-name>/openbox-3/

•/opt/share/themes/<theme-name>/openbox-3/

When $XDG_DATA_HOME is defined, it replaces (rather than augments) $HOME/.local/share. The same is the case for $XDG_DATA_DIRS and /usr/share/.

Choosing a theme is done by editing the <name> key in the <theme> section of the rc.xml configuration file (labwc-config(5)).

A theme consists of a themerc file and optionally some titlebar icons (referred to as buttons).

Theme settings specified in themerc can be overridden by creating a 'themerc-override' file in the configuration directory, which is normally $HOME/.config/labwc/ but can be a few other locations as described in labwc-config(5).

## DATA TYPES
color

Colors can be specified by name or hexadecimal Red-Green-Blue (RGB) value: color name refers to "X11 color name", for example: 'white', 'grey40', 'pink' and 'peach puff'. More information can be found here:

•http://en.wikipedia.org/wiki/Web_colors#X11_color_names

•http://en.wikipedia.org/wiki/X11_color_names

•https://github.com/labwc/labwc/blob/master/src/common/rgb.txt

RGB value

•#rrggbb (hexadecimal RGB values)

•#rrggbb aaa (same but with decimal alpha value percentage)

•#rrggbbaa (same but with inline alpha value in hex encoding)

•#rgb (hexadecimal RGB values where #fff is shorthand for #f0f0f0) (since 0.9.0)

Note: the #rrggbb aaa notation is deprecated starting from labwc 0.7.2 and may be removed in future releases.

justification

Justification determines the horizontal alignment of text. Valid options are Left, Center and Right.

textures

Textures determine the visual look of an element. They are specified through a text string with a number of fields. Capitalization is not significant. The format is as follows:

```
(Solid | Gradient <type>)
```

.. where | stands for "or".

•Solid means that the background of the texture is filled with a single color. The texture must be accompanied by a single color field. For example:

```
window.*.title.bg: Solid
window.*.title.bg.color: #f8f5f2
```

•Gradient means that the background of the texture is filled with a gradient from one color to another. When Gradient is specified, it must be followed by the gradient's type. It must also be accompanied by the fields color and colorTo. Valid gradient types are: (1) Vertical where the gradient goes from the top edge to the bottom (2) SplitVertical where the gradient is split in the middle and goes out toward the top and bottom edges. SplitVertical gradients have two extra, optional color fields: color.splitTo and colorTo.splitTo. These colors are the light colors used on the far top and bottom of the SplitVertical gradient. When these are omitted, the default values for these are color x 5/4 and colorTo x 17/16. Examples:

```
# Vertical gradient
window.*.title.bg: Gradient Vertical
window.*.title.bg.color: #658fb5
window.*.title.bg.colorTo: #4d6982
# SplitVertical gradient
window.*.title.bg: Gradient SplitVertical
window.*.title.bg.color: #658fb5
window.*.title.bg.color.splitTo: #7595b9
window.*.title.bg.colorTo: #4d6982
window.*.title.bg.colorTo.splitTo: #557485
```

## THEME ELEMENTS
border.width

Line width (integer) of border drawn around window frames. Default is 1.

window.titlebar.padding.width

Horizontal titlebar padding size, in pixels, between border and first button on the left/right. Default is 0.

window.titlebar.padding.height

Vertical titlebar padding size, in pixels. Default is 0.

window.active.border.color

Border color of active window. Default is #aaaaaa.

window.inactive.border.color

Border color of inactive window. Default is #aaaaaa.

window.active.indicator.toggled-keybind.color

Status indicator for the ToggleKeybinds action. Can be set to the same value as set for window.active.border.color to disable the status indicator. Default is #ff0000.

window.active.title.bg

Texture for the focused window's titlebar. See texture section above. Default is Solid

window.active.title.bg.color

Background color for the focused window's titlebar. See texture section for additional color fields associated with gradients. Default is #e1dedb.

window.inactive.title.bg

Texture for non-focused windows' titlebars. See texture section above. Default is Solid

window.inactive.title.bg.color

Background color for non-focused windows' titlebars. See texture section for additional color fields associated with gradients. Default is #f6f5f4.

window.active.label.text.color

Text color for the focused window's titlebar. Default is #000000.

window.inactive.label.text.color

Text color non-focused windows' titlebars. Default is #000000.

window.label.text.justify

Specifies how window titles are aligned in the titlebar for both focused and unfocused windows. Type justification. Default is Center.

window.button.width

Width of a titlebar button, in pixels. Default is 26.

window.button.height

Height of a titlebar button, in pixels. Default is 26.

window.button.spacing

Space between titlebar buttons, in pixels. Default is 0.

Note: The window.button.hover namespace (below) relates to button hover overlay effects which work with all buttons including svg, png and xbm.

The window.button.hover effects are only shown if there is no corresponding hover icon, like close_hover-active.svg.

Openbox only supports hover effects rendered behind buttons which makes sense for the xbm format, but not for others. For reference, these are defined by window.active|inactive.button.STATE.bg where STATE can be any of pressed, hover and disabled. These are not (yet) supported by labwc and are mentioned here for comparison only.

window.button.hover.bg.color

Color of the hover effect of a titlebar button. Default is #80808020.

window.button.hover.bg.corner-radius

Radius of the hover effect of a titlebar button, in pixels. Default is 0. Note: for a circular hover effect, set window.button.width and window.button.height equal and window.button.hover.bg.corner-radius half of them.

window.active.button.unpressed.image.color

Color of the images in titlebar buttons in their default, unpressed, state. This element is for the focused window. Default is #000000.

window.inactive.button.unpressed.image.color

Color of the images in titlebar buttons in their default, unpressed, state. This element is for non-focused windows. Default is #000000.

Note: Button elements (i.e. window.[in]active.button.*) may be defined uniquely for each type of button ("menu", "iconify", "max", "shade", "desk" or "close") by appending the type after the "button" node. For example:

•window.active.button.iconify.unpressed.image.color indicates the color of the

iconify button for active windows; while

•window.inactive.button.close.unpressed.image.color indicates the color of the

close button for inactive windows. This syntax is not documented by Openbox, but is supported and is used by many popular themes. For the sake of brevity, these elements are not listed here, but all are supported.

window.active.shadow.size

Size of the drop-shadow for the focused window, in pixels. Default is 60.

window.inactive.shadow.size

Size of drop-shadows for non-focused windows, in pixels. Default is 40.

window.active.shadow.color

Color of the drop-shadow for the focused window, including opacity. Default is #00000060 (black with 38% opacity).

window.inactive.shadow.color

Color of drop-shadows for non-focused windows, including opacity. Default is #00000040 (black with 25% opacity).

menu.overlap.x

Horizontal overlap in pixels between submenus and their parents. A positive value move submenus over the top of their parents, whereas a negative value creates a gap between submenus and their parents. Default is 0.

menu.overlap.y

Vertical offset in pixels between submenus and their parents. Positive values for downwards and negative for upwards. Default is 0.

menu.width.min

Minimal width for menus. Default is 20. A fixed width can be achieved by setting .min and .max to the same value.

menu.width.max

Maximal width for menus. Default is 200. A fixed width can be achieved by setting .min and .max to the same value.

menu.border.width

Border width of menus in pixels. Inherits border.width if not set.

menu.border.color

Border color of menus. Inherits window.active.border.color if not set.

menu.items.padding.x

Horizontal padding of menu text entries in pixels. Default is 7.

menu.items.padding.y

Vertical padding of menu text entries in pixels. Default is 4.

menu.items.bg.color

Background color of inactive menu items. Default is #fcfbfa.

menu.items.text.color

Text color of inactive menu item. Default is #000000.

menu.items.active.bg.color

Background color of active menu items. Default is #e1dedb.

menu.items.active.text.color

Text color of active menu item. Default is #000000.

menu.separator.width

Line thickness of menu separators. Default is 1.

menu.separator.padding.width

Space on the left and right side of each separator line. Default is 6.

menu.separator.padding.height

Space above and below each separator line. Default is 3.

menu.separator.color

Menu separator color. Default is #888888.

menu.title.bg.color

Menu title color. Default is #589bda. Note: A menu title is a separator with a label.

menu.title.text.justify

Specifies how menu titles are aligned in the titlebar. Type justification. Default is Center.

menu.title.text.color

Text color of separator label. Default is #ffffff.

osd.bg.color

Background color of on-screen-display. Inherits window.active.title.bg.color if not set.

osd.border.color

Border color of on-screen-display. Inherits osd.label.text.color if not set.

osd.border.width

Border width of on-screen-display. Inherits border.width if not set.

osd.label.text.color

Text color of on-screen-display. Inherits window.active.label.text.color if not set.

osd.window-switcher.style-classic

Theme for window switcher when using <windowSwitcher style="classic" />. See below for details.

osd.window-switcher.style-classic.width

Width of window switcher in pixels. Width can also be a percentage of the monitor width by adding '%' as suffix (e.g. 70%). Default is 600.

osd.window-switcher.style-classic.padding

Padding of window switcher in pixels. This is the space between the window-switcher border and its items. Default is 4.

osd.window-switcher.style-classic.item.padding.x

Horizontal padding of window switcher entries in pixels. Default is 10.

osd.window-switcher.style-classic.item.padding.y

Vertical padding of window switcher entries in pixels. Default is 1.

osd.window-switcher.style-classic.item.active.border.width

Border width of the selection box in the window switcher in pixels. Default is 2.

osd.window-switcher.style-classic.item.active.border.color

Border color around the selected window switcher item. Default is osd.label.text.color with 50% opacity.

osd.window-switcher.style-classic.item.active.bg.color

Background color of the selected window switcher item. Default is osd.label.text.color with 15% opacity.

osd.window-switcher.style-classic.item.icon.size

Size of the icon in window switcher, in pixels. If not set, the font size derived from <theme><font place="OnScreenDisplay"> is used.

osd.window-switcher.style-thumbnail

Theme for window switcher when using <windowSwitcher style="thumbnail" />. See below for details.

osd.window-switcher.style-thumbnail.width.max

Maximum width of window switcher in pixels. Width can also be a percentage of the monitor width by adding '%' as suffix (e.g. 70%). Default is 80%.

osd.window-switcher.style-thumbnail.padding

Padding of window switcher in pixels. This is the space between the window-switcher border and its items. Default is 4.

osd.window-switcher.style-thumbnail.item.width

Width of window switcher items in pixels. Default is 300.

osd.window-switcher.style-thumbnail.item.height

Height of window switcher items in pixels. Default is 250.

osd.window-switcher.style-thumbnail.item.padding

Padding of window switcher items in pixels. This is the space between the border around selected items and window thumbnail. Default is 2.

osd.window-switcher.style-thumbnail.item.active.border.width

Border width of selected window switcher items in pixels. Default is 2.

osd.window-switcher.style-thumbnail.item.active.border.color

Color of border around selected window switcher items. Default is osd.label.text.color with 50% opacity.

osd.window-switcher.style-thumbnail.item.active.bg.color

Color of selected window switcher items. Default is osd.label.text.color with 15% opacity.

osd.window-switcher.style-thumbnail.item.icon.size

Size of window icons in window switcher items in pixels. Default is 60.

osd.window-switcher.preview.border.width

Border width of the outlines shown as the preview of the window selected by window switcher. Inherits osd.border.width if not set.

osd.window-switcher.preview.border.color

Color(s) of the outlines shown as the preview of the window selected by window switcher. Possible value is a color or up to 3 colors separated by commas (e.g. "#ffffff,#000000,#ffffff"). When multiple colors are specified, a multi-line rectangle with each line having the specified color is drawn. If not set, this inherits the on-screen-display theme ("[osd.bg.color],[osd.label.text.color],[osd.bg.color]").

osd.workspace-switcher.boxes.width

Width of boxes in workspace switcher in pixels. Setting to 0 disables boxes. Default is 20.

osd.workspace-switcher.boxes.height

Height of boxes in workspace switcher in pixels. Setting to 0 disables boxes. Default is 20.

osd.workspace-switcher.boxes.border.width

Border width of boxes in workspace switcher in pixels. Default is 2.

snapping.overlay.region.bg.enabled [yes|no]

Show a filled rectangle as an overlay when a window is snapped to a region. Default is yes for hardware-based renderers and no for software-based renderers.

snapping.overlay.edge.bg.enabled [yes|no]

Show a filled rectangle as an overlay when a window is snapped to an edge. Default is yes for hardware-based renderer and no for software-based renderers.

snapping.overlay.region.border.enabled [yes|no]

Show an outlined rectangle as an overlay when a window is snapped to a region. Default is no for hardware-based renderers and yes for software-based renderers.

snapping.overlay.edge.border.enabled [yes|no]

Show an outlined rectangle as an overlay when a window is snapped to an edge. Default is no for hardware-based renderer and yes for software-based renderers.

snapping.overlay.region.bg.color

Color of a filled rectangle shown as an overlay when a window is snapped to a region. Default is #8080b380.

snapping.overlay.edge.bg.color

Color of a filled rectangle shown as an overlay when a window is snapped to an edge. Default is #8080b380.

snapping.overlay.region.border.width

Border width of an outlined rectangle shown as an overlay when a window is snapped to a region. Inherits `osd.border.width` if not set.

snapping.overlay.edge.border.width

Border width of an outlined rectangle shown as an overlay when a window is snapped to an edge. Inherits `osd.border.width` if not set.

snapping.overlay.region.border.color

Color(s) of an outlined rectangle shown as an overlay when a window is snapped to a region. Possible values and the default value are the same as those of osd.window-switcher.preview.border.color.

snapping.overlay.edge.border.color

Color(s) of an outlined rectangle shown as an overlay when a window is snapped to an edge. Possible values and the default value are the same as those of osd.window-switcher.preview.border.color.

border.color

Set both window.active.border.color and window.inactive.border.color. This is obsolete, but supported for backward compatibility as some themes still contain it.

magnifier.border.width

Width of magnifier window border in pixels. Default is 1.

magnifier.border.color

Color of the magnfier window border. Default is #ff0000 (red).

## BUTTONS
The images used for the titlebar icons are referred to as buttons.

The image formats listed below are supported. They are listed in order of precedence, where the first format in the list is searched for first.

•png

•svg

•xbm

By default, buttons are 1-bit xbm (X Bitmaps). These are masks where 0=clear and 1=colored. The xbm image files are placed in the same directory as the themerc file within a particular theme. The following xbm buttons are supported:

•max.xbm

•iconify.xbm

•close.xbm

•menu.xbm

•max_toggled.xbm

•desk.xbm

•desk_toggled.xbm

•shade.xbm

•shade_toggled.xbm

Additional icons can be defined to be shown when the mouse pointer is hovering over the button in question:

•max_hover.xbm

•iconify_hover.xbm

•close_hover.xbm

•menu_hover.xbm

•max_toggled_hover.xbm

•desk_hover.xbm

•desk_toggle_hover.xbm

•shade_hover.xbm

•shade_toggle_hover.xbm

One advantage of xbm buttons over other formats is that they change color based on the theme. Other formats use the suffices "-active" and "-inactive" to align with the respective titlebar colors. For example: "close-active.png"

For compatibility reasons, the following alternative names are supported for xbm files:

•max_hover_toggled.xbm for max_toggled_hover.xbm

When using png or svg icons, for a full theme experience all of the following icons should be added:

•close-active.[png|svg]

•close_hover-active.[png|svg]

•close_hover-inactive.[png|svg]

•close-inactive.[png|svg]

•iconify-active.[png|svg]

•iconify_hover-active.[png|svg]

•iconify_hover-inactive.[png|svg]

•iconify-inactive.[png|svg]

•max-active.[png|svg]

•max_hover-active.[png|svg]

•max_hover-inactive.[png|svg]

•max-inactive.[png|svg]

•max_toggled-active.[png|svg]

•max_toggled_hover-active.[png|svg]

•max_toggled_hover-inactive.[png|svg]

•max_toggled-inactive.[png|svg]

•menu-active.[png|svg]

•menu_hover-active.[png|svg]

•menu_hover-inactive.[png|svg]

•menu-inactive.[png|svg]

•shade-active.[png|svg]

•shade_hover-active.[png|svg]

•shade_hover-inactive.[png|svg]

•shade-inactive.[png|svg]

•shade_toggled-active.[png|svg]

•shade_toggled-inactive.[png|svg]

•shade_toggled_hover-active.[png|svg]

•shade_toggled_hover-inactive.[png|svg]

•desk-active.[png|svg]

•desk_hover-active.[png|svg]

•desk_hover-inactive.[png|svg]

•desk-inactive.[png|svg]

•desk_toggled-active.[png|svg]

•desk_toggled-inactive.[png|svg]

•desk_toggled_hover-active.[png|svg]

•desk_toggled_hover-inactive.[png|svg]

## DEFINITIONS
The handle is the window edge decoration at the bottom of the window.

## SEE ALSO
labwc(1), labwc-config(5), labwc-actions(5)


lcdproc-config

package: lcdproc

title: lcdproc-config(5)

text:
# lcdproc-config(5)

## NAME
lcdproc-config - format of LCDproc's configuration files

## SYNTAX
The syntax for LCDproc's configuration files is INI-file style.

They are 8-bit text files divided into sections, each containing zero or more key-value pairs. Sections are introduced by section labels which start with '[' and end with ']', and key-value pairs consist of a key name, a '=' sign and a value each.

Key names are sequences of non-space characters, not starting with '[' and not containing '=' or '\n', while values are shell like strings. I.e. they are either simple sequences of non-space characters, or double quoted-strings with C-style syntax (except the missing support for '\NNN' and '\xNN' escape sequences) or or a mix of both of these forms.

Section labels and key names are case-insensitive and may occur more than once. Keys of duplicate sections will be merged into one section, while the values of duplicate keys in a section will be appended to form an array of values for this key. (In the program, all values of a key can be retrieved individually)

Spaces around section labels, keys, and values are ignored. Lines starting with ';' or '#' are considered comments and ignored too.

While all of the above is quite common to almost all INI-file implementations, there are a few special features that make LCDproc's config files special:

- Section labels may contain any character except ']', '\n' or '\0'. However, all characters are interpreted literally (i.e. neither quoting, nor escaping done).

- Key names may contain any non-space character except '\n' or '\0'. However, all characters are interpreted literally (i.e. neither quoting, nor escaping done).

- Comments are allowed after section labels and key value pairs

- Values may be a mix of quoted and unquoted strings similar as strings are interpreted in the shell. E.g. the value 'string" with "blanks"\t!"' will be parsed as 'string with blanks<TAB>!' where <TAB> stands for the TAB character.

In case of a a parsing error the rest of the line is ignored and parsing continues with the next line.

## EXAMPLE
Here is fully working example of an LCDd.conf (formatted somewhat strange to show the features):

```
# the server section
[server]
Bind=127.0.0.1
Port=13666
User="nobody"
#Foreground=no
#ReportLevel=3
#ReportToSyslog=yes
Driver="my Curses Driver"
DriverPath=/usr/lib/lcdproc/
WaitTime= "5"
ServerScreen=no
# assign keys to special functions #
ToggleRotateKey = Enter
PrevScreenKey = Left
NextScreenKey = Right
# ScrollUpKey = Up

 #ScrollDownKey=Down
#  menu section: define keys to use in the server menu #
	 [menu]
MenuKey = Escape	# ESC switches to server menu
EnterKey =Enter
UpKey= Up
DownKey="Down"

 LeftKey= "Left"

 RightKey = "Right"
# configuration of the curses driver #
[my curses Driver]	# yes I use the curse driver
File= "curses.so"
Size="20"x"4"		# LCD screen dimensions
TopLeftX=7		# screen position: X coordinate
TopLeftY=7		# screen position: Y coordinate
Foreground=blue		# foreground color
Background=cyan		# background color when backight is off
Backlight=red		# background color when backight is on
```

## FILES
These are the default config files for the various parts of the LCDproc suite:

/etc/LCDd.conf

configuration of the LCDd server daemon

/etc/lcdproc.conf

configuration of the lcdproc system monitoring client

/etc/lcdexec.conf

configuration of the lcdexec the program starter client

/etc/lcdvc.conf

configuration of the lcdvc virtual console client

## SEE ALSO
LCDd(8), lcdproc(1), lcdexec(1)

## AUTHOR
This manual page has been written by Peter Marschall <peter@adpm.de>


lcovrc

package: lcov

title: lcovrc(5)

summary: lcov configuration file

text:
# lcovrc(5)

## NAME
lcovrc - lcov configuration file

## DESCRIPTION
The lcovrc file contains configuration information for the lcov code coverage tool (see lcov(1)).

The system-wide configuration file is located at /etc/lcovrc. To change settings for a single user, place a customized copy of this file at location ~/.lcovrc. Where available, command-line options override configuration file settings.

Lines in a configuration file can either be:

*

empty lines or lines consisting only of white space characters. These lines are ignored.

*

comment lines which start with a hash sign ('#'). These are treated like empty lines and will be ignored.

*

statements in the form 'key = value'. A list of valid statements and their description can be found in section 'OPTIONS' below.

Example configuration:

\#

\# Example LCOV configuration file

\# # External style sheet file

\#genhtml_css_file = gcov.css

\# Coverage rate limits

genhtml_hi_limit = 90

genhtml_med_limit = 75

\# Width of line coverage field in source code view

genhtml_line_field_width = 12

\# Width of branch coverage field in source code view

genhtml_branch_field_width = 16

\# Width of overview image

genhtml_overview_width = 80

\# Resolution of overview navigation

genhtml_nav_resolution = 4

\# Offset for source code navigation

genhtml_nav_offset = 10

\# Do not remove unused test descriptions if non-zero

genhtml_keep_descriptions = 0

\# Do not remove prefix from directory names if non-zero

genhtml_no_prefix = 0

\# Do not create source code view if non-zero

genhtml_no_source = 0

\# Specify size of tabs

genhtml_num_spaces = 8

\# Highlight lines with converted-only data if non-zero

genhtml_highlight = 0

\# Include color legend in HTML output if non-zero

genhtml_legend = 0

\# Include HTML file at start of HTML output

\#genhtml_html_prolog = prolog.html

\# Include HTML file at end of HTML output

\#genhtml_html_epilog = epilog.html

\# Use custom HTML file extension

\#genhtml_html_extension = html

\# Compress all generated html files with gzip.

\#genhtml_html_gzip = 1

\# Include sorted overview pages

genhtml_sort = 1

\# Include function coverage data display

\#genhtml_function_coverage = 1

\# Include branch coverage data display

\#genhtml_branch_coverage = 1

\# Specify the character set of all generated HTML pages

genhtml_charset=UTF-8

\# Allow HTML markup in test case description text if non-zero

genhtml_desc_html=0

\# Specify the precision for coverage rates

\#genhtml_precision=1

\# Show missed counts instead of hit counts

\#genhtml_missed=1

\# Demangle C++ symbols

\#genhtml_demangle_cpp=1

\# Name of the tool used for demangling C++ function names

\#genhtml_demangle_cpp_tool = c++filt

\# Specify extra parameters to be passed to the demangling tool

\#genhtml_demangle_cpp_params = ""

\# Location of the gcov tool

\#geninfo_gcov_tool = gcov

\# Adjust test names if non-zero

\#geninfo_adjust_testname = 0

\# Calculate a checksum for each line if non-zero

geninfo_checksum = 0

\# Enable libtool compatibility mode if non-zero

geninfo_compat_libtool = 0

\# Specify whether to capture coverage data for external source

\# files

\#geninfo_external = 1

\# Use gcov's --all-blocks option if non-zero

\#geninfo_gcov_all_blocks = 1

\# Specify compatiblity modes (same as --compat option

\# of geninfo)

\#geninfo_compat = libtool=on, hammer=auto, split_crc=auto

\# Adjust path to source files by removing or changing path

\# components that match the specified pattern (Perl regular

\# expression format)

\#geninfo_adjust_src_path = /tmp/build => /usr/src

\# Specify if geninfo should try to automatically determine

\# the base-directory when collecting coverage data.

geninfo_auto_base = 1

\# Use gcov intermediate format? Valid values are 0, 1, auto

geninfo_intermediate = auto

\# Directory containing gcov kernel files

lcov_gcov_dir = /proc/gcov

\# Location for temporary directories

lcov_tmp_dir = /tmp

\# Show full paths during list operation if non-zero

lcov_list_full_path = 0

\# Specify the maximum width for list output. This value is

\# ignored when lcov_list_full_path is non-zero.

lcov_list_width = 80

\# Specify the maximum percentage of file names which may be

\# truncated when choosing a directory prefix in list output.

\# This value is ignored when lcov_list_full_path is non-zero.

lcov_list_truncate_max = 20

\# Specify if function coverage data should be collected and

\# processed.

lcov_function_coverage = 1

\# Specify if branch coverage data should be collected and

\# processed.

lcov_branch_coverage = 0

## OPTIONS
genhtml_css_file = filename

Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by genhtml. During output generation, a copy of this file will be placed in the output directory. This option corresponds to the --css-file command line option of genhtml.

By default, a standard CSS file is generated.

genhtml_hi_limit = hi_limit

genhtml_med_limit = med_limit

Specify coverage rate limits for classifying file entries. Use this option to modify the coverage rates (in percent) for line, function and branch coverage at which a result is classified as high, medium or low coverage. This classification affects the color of the corresponding entries on the overview pages of the HTML output: High: hi_limit <= rate <= 100 default color: green

Medium: med_limit <= rate < hi_limit default color: orange

Low: 0 <= rate < med_limit default color: red

Defaults are 90 and 75 percent.

genhtml_line_field_width = number_of_characters

Specify the width (in characters) of the source code view column containing line coverage information. Default is 12.

genhtml_branch_field_width = number_of_characters

Specify the width (in characters) of the source code view column containing branch coverage information. Default is 16.

genhtml_overview_width = pixel_size

Specify the width (in pixel) of the overview image created when generating HTML output using the --frames option of genhtml. Default is 80.

genhtml_nav_resolution = lines

Specify the resolution of overview navigation when generating HTML output using the --frames option of genhtml. This number specifies the maximum difference in lines between the position a user selected from the overview and the position the source code window is scrolled to. Default is 4.

genhtml_nav_offset = lines

Specify the overview navigation line offset as applied when generating HTML output using the --frames option of genhtml. Clicking a line in the overview image should show the source code view at a position a bit further up, so that the requested line is not the first line in the window. This number specifies that offset.

Default is 10.

genhtml_keep_descriptions = 0|1

If non-zero, keep unused test descriptions when generating HTML output using genhtml. This option corresponds to the --keep-descriptions option of genhtml.

Default is 0.

genhtml_no_prefix = 0|1

If non-zero, do not try to find and remove a common prefix from directory names. This option corresponds to the --no-prefix option of genhtml.

Default is 0.

genhtml_no_source = 0|1

If non-zero, do not create a source code view when generating HTML output using genhtml. This option corresponds to the --no-source option of genhtml.

Default is 0.

genhtml_num_spaces = num

Specify the number of spaces to use as replacement for tab characters in the HTML source code view as generated by genhtml. This option corresponds to the --num-spaces option of genthml.

Default is 8.

genhtml_highlight = 0|1

If non-zero, highlight lines with converted-only data in HTML output as generated by genhtml. This option corresponds to the --highlight option of genhtml.

Default is 0.

genhtml_legend = 0|1

If non-zero, include a legend explaining the meaning of color coding in the HTML output as generated by genhtml. This option corresponds to the --legend option of genhtml.

Default is 0.

genhtml_html_prolog = filename

If set, include the contents of the specified file at the beginning of HTML output. This option corresponds to the --html-prolog option of genhtml.

Default is to use no extra prolog.

genhtml_html_epilog = filename

If set, include the contents of the specified file at the end of HTML output. This option corresponds to the --html-epilog option of genhtml.

Default is to use no extra epilog.

genhtml_html_extension = extension

If set, use the specified string as filename extension for generated HTML files. This option corresponds to the --html-extension option of genhtml.

Default extension is "html".

genhtml_html_gzip = 0|1

If set, compress all html files using gzip. This option corresponds to the --html-gzip option of genhtml.

Default extension is 0.

genhtml_sort = 0|1

If non-zero, create overview pages sorted by coverage rates when generating HTML output using genhtml. This option can be set to 0 by using the --no-sort option of genhtml.

Default is 1.

genhtml_function_coverage = 0|1

If non-zero, include function coverage data when generating HTML output using genhtml. This option can be set to 0 by using the --no-function-coverage option of genhtml.

Default is 1.

genhtml_branch_coverage = 0|1

If non-zero, include branch coverage data when generating HTML output using genhtml. This option can be set to 0 by using the --no-branch-coverage option of genhtml.

Default is 1.

genhtml_charset = charset

Specify the character set of all generated HTML pages. Use this option if the source code contains characters which are not part of the default character set. Note that this option is ignored when a custom HTML prolog is specified (see also genhtml_html_prolog).

Default is UTF-8.

genhtml_demangle_cpp = 0|1

If non-zero, demangle C++ function names in function overviews. Set this option to one if you want to convert C++ internal function names to human readable format for display on the HTML function overview page. This option requires that the c++filt tool is installed (see c++filt(1) ).

This option corresponds to the --demangle-cpp command line option of genhtml.

Default is 0.

genhtml_demangle_cpp_tool = path_to_c++filt

Specify the location of the demangle tool (see c++filt(1)) used to convert C++ internal function names to human readable format for display on the HTML function overview page. Default is 'c++filt'.

genhtml_demangle_cpp_params = parameters

Specify extra parameters to be passed to the demangling tool Use this option if your environment requires additional parameters such as --no-strip-underscore for correctly demangling C++ internal function names. See also c++filt(1)).

Default is "".

genhtml_desc_html = 0|1

If non-zero, test case descriptions may contain HTML markup. Set this option to one if you want to embed HTML markup (for example to include links) in test case descriptions. When set to zero, HTML markup characters will be escaped to show up as plain text on the test case description page.

Default is 0.

genhtml_precision = 1|2|3|4

Specify how many digits after the decimal-point should be used for displaying coverage rates. Default is 1.

genhtml_missed = 0|1

If non-zero, the count of missed lines, functions, or branches is shown as negative numbers in overview pages. Default is 0.

geninfo_gcov_tool = path_to_gcov

Specify the location of the gcov tool (see gcov(1)) which is used to generate coverage information from data files. Default is 'gcov'.

geninfo_adjust_testname = 0|1

If non-zero, adjust test names to include operating system information when capturing coverage data. Default is 0.

geninfo_checksum = 0|1

If non-zero, generate source code checksums when capturing coverage data. Checksums are useful to prevent merging coverage data from incompatible source code versions but checksum generation increases the size of coverage files and the time used to generate those files. This option corresponds to the --checksum and --no-checksum command line option of geninfo.

Default is 0.

geninfo_compat_libtool = 0|1

If non-zero, enable libtool compatibility mode. When libtool compatibility mode is enabled, lcov will assume that the source code relating to a .da file located in a directory named ".libs" can be found in its parent directory. This option corresponds to the --compat-libtool and --no-compat-libtool command line option of geninfo.

Default is 1.

geninfo_external = 0|1

If non-zero, capture coverage data for external source files. External source files are files which are not located in one of the directories (including sub-directories) specified by the --directory or --base-directory options of lcov/geninfo.

Default is 1.

geninfo_gcov_all_blocks = 0|1

If non-zero, call the gcov tool with option --all-blocks. Using --all-blocks will produce more detailed branch coverage information for each line. Set this option to zero if you do not need detailed branch coverage information to speed up the process of capturing code coverage or to work around a bug in some versions of gcov which will cause it to endlessly loop when analysing some files.

Default is 1.

geninfo_compat = mode=value[,mode=value,...]

Specify that geninfo should enable one or more compatibility modes when capturing coverage data. This option corresponds to the --compat command line option of geninfo.

Default is 'libtool=on, hammer=auto, split_crc=auto'.

geninfo_adjust_src_path = pattern => replacement

geninfo_adjust_src_path = pattern

Adjust source paths when capturing coverage data. Use this option in situations where geninfo cannot find the correct path to source code files of a project. By providing a pattern in Perl regular expression format (see perlre(1)) and an optional replacement string, you can instruct geninfo to remove or change parts of the incorrect source path.

Example:

1. When geninfo reports that it cannot find source file

/path/to/src/.libs/file.c

while the file is actually located in

/path/to/src/file.c

use the following parameter:

geninfo_adjust_src_path = /.libs

This will remove all "/.libs" strings from the path.

2. When geninfo reports that it cannot find source file

/tmp/build/file.c

while the file is actually located in

/usr/src/file.c

use the following parameter:

geninfo_adjust_src_path = /tmp/build => /usr/src

This will change all "/tmp/build" strings in the path to "/usr/src".

geninfo_auto_base = 0|1

If non-zero, apply a heuristic to determine the base directory when collecting coverage data. Use this option when using geninfo on projects built with libtool or similar build environments that work with multiple base directories, i.e. environments, where the current working directory when invoking the compiler ist not the same directory in which the source code file is located, and in addition, is different between files of the same project.

Default is 1.

geninfo_intermediate = 0|1|auto

Specify whether to use gcov intermediate format Use this option to control whether geninfo should use the gcov intermediate format while collecting coverage data. The use of the gcov intermediate format should increase processing speed. It also provides branch coverage data when using the --initial command line option.

Valid values are 0 for off, 1 for on, and "auto" to let geninfo automatically use immediate format when supported by gcov.

Default is "auto".

geninfo_no_exception_branch = 0|1

Specify whether to exclude exception branches from branch coverage. Default is 0.

lcov_gcov_dir = path_to_kernel_coverage_data

Specify the path to the directory where kernel coverage data can be found or leave undefined for auto-detection. Default is auto-detection.

lcov_tmp_dir = temp

Specify the location of a directory used for temporary files. Default is '/tmp'.

lcov_list_full_path = 0|1

If non-zero, print the full path to source code files during a list operation. This option corresponds to the --list-full-path option of lcov.

Default is 0.

lcov_list_max_width = width

Specify the maximum width for list output. This value is ignored when lcov_list_full_path is non-zero. Default is 80.

lcov_list_truncate_max = percentage

Specify the maximum percentage of file names which may be truncated when choosing a directory prefix in list output. This value is ignored when lcov_list_full_path is non-zero. Default is 20.

lcov_function_coverage = 0|1

Specify whether lcov should handle function coverage data. Setting this option to 0 can reduce memory and CPU time consumption when lcov is collecting and processing coverage data, as well as reduce the size of the resulting data files. Note that setting genhtml_function_coverage will override this option for HTML generation.

Default is 1.

lcov_branch_coverage = 0|1

Specify whether lcov should handle branch coverage data. Setting this option to 0 can reduce memory and CPU time consumption when lcov is collecting and processing coverage data, as well as reduce the size of the resulting data files. Note that setting genhtml_branch_coverage will override this option for HTML generation.

Default is 0.

lcov_excl_line = expression

Specify the regular expression of lines to exclude. Default is 'LCOV_EXCL_LINE'.

lcov_excl_br_line = expression

Specify the regular expression of lines to exclude from branch coverage. Default is 'LCOV_EXCL_BR_LINE'.

lcov_excl_exception_br_line = expression

Specify the regular expression of lines to exclude from exception branch coverage. Default is 'LCOV_EXCL_EXCEPTION_BR_LINE'.

## FILES
/etc/lcovrc

The system-wide lcov configuration file.

~/.lcovrc

The individual per-user configuration file.

## SEE ALSO
lcov(1), genhtml(1), geninfo(1), gcov(1)