Name

x11-overlay! - display text file as a desktop overlay

Synopsis

x11-overlay [OPTION...] FILE

Description

x11-overlay is a tiny program to display the content of text files as an overlay on your desktop. Its goal is simplicity, a non-distracting visualization and especially it should not interfere with user interactions targeting the underlying content.

It is designed as a front-end tool to show alarms or the health status of any system. To do so, just write your custom script that generates and updates a text file with the information you want to be displayed. Use this file as input for x11-overlay and that's it. But of course, it's absolutely not limited to alarming dashboards. Be creative!

General

• -c, --config=FILE

  Path to a configuration file. If not specified, the default path ~/.config/x11-overlayrc is used when present. Configuration values are merged in the following order of precedence: built-in defaults < config file < command-line arguments.

• -h, --help

  Print program usage and quit.

• -v, --verbose

  Print the resolved configuration after merging built-in defaults, config file values, and command-line arguments. Also prints the path to the default configuration file and any parsing errors encountered.

• -V, --version

  Print version number and quit.

Positioning

• -e PIXEL

  Adds spacing (in pixels) from the screen edge to the overlay. The affected edge depends on the selected orientation and has no effect when the orientation is set to CENTER. Can be a negative value and defaults to 0.

• -l PIXEL

  Adds extra vertical spacing (in pixels) between each text line. Must be a non-negative value and defaults to 0.

• -m INDEX

  Specifies the monitor to display the overlay on in multi-monitor setups. The first monitor index is 0. Must be a non-negative value and defaults to 0.

• -o ORIENTATION

  Positions the overlay along the screen edge specified by the orientation and aligns text lines accordingly. Defaults to NW. Possible values are N, NE, E, SE, S, SW, W, NW and CENTER.

Font

• -f, --font-name=FONT,..

  Font name as known to fontconfig. Up to 10 comma-separated font names can be specified, mapped to ANSI alternative font selection escape sequences (font slots 0–9). If a slot is left empty, font slot 0 is used as fallback. Defaults to NotoSansMono.

• -s, --font-size=SIZE,..

  Font size in points. Up to 10 comma-separated sizes can be specified, corresponding to the 10 font slots. If a slot is left empty, the size from slot 0 is used as fallback. Each value must be at least 1. Defaults to 12.

Colors

• -p, --profile=PROFILE

  ANSI color profile used for interpreting 3–4 bit and 8 bit color codes. Determines the RGB values mapped to the standard ANSI color indices. Possible values are VGA and XP. Defaults to VGA.

• --fg-color=COLOR

  Default foreground (text) color, specified as an ANSI SGR color sequence (the leading ESC character can be omitted). Supports 3–4 bit (e.g. [97), 8 bit (e.g. [38;5;15), and 24 bit (e.g. [38;2;255;255;255) formats. Defaults to [97 (equals [38;2;255;255;255).

• --fg-alpha=ALPHA

  Foreground (text) opacity. Range is 0 (fully transparent) to 255 (fully opaque). Defaults to 200.

• --bg-color=COLOR

  Default background color, specified as an ANSI SGR color sequence (the leading ESC character can be omitted). Supports the same formats as --fg-color. Defaults to [40 (equals [48;2;0;0;0).

• --bg-alpha=ALPHA

  Background opacity. Range is 0 (fully transparent) to 255 (fully opaque). Defaults to 100.

Behavior

• -d, --dim=PERCENT

  Dimming percentage applied when the mouse cursor is over or near the overlay. Higher values produce stronger dimming. Range is 0–100. Defaults to 75%.

• -D PERCENT

  Constant dimming percentage applied to the overlay at all times, regardless of mouse position. Range is 0–100. Defaults to 0%.

• -t PIXEL

  Expands the detection area (in pixels) around the overlay for triggering mouse-over dimming. Must be a non-negative value and defaults to 0.