GENERAL CASE

FALLBACK METHOD

Create a named pipe, e.g. /tmp/xobpipe, on your filesystem.

mkfifo /tmp/xobpipe

    

Have xob consume new values as they arrive on the pipe.

tail -f /tmp/xobpipe | xob

    

Write values to the pipe when you deem it relevant. In the classic audio volume bar example, that would be after the user has pressed a button and you changed the volume (usually set up as a keybinding in your window manager or desktop environment).

command_that_outputs_a_value >> /tmp/xobpipe

    

To try it manually, issue a test value such as echo 43 >> /tmp/xobpipe.

SYNTAX

option1 = value1;
option2 = value2;

    

Commented lines start with “#”.

# This is a comment

    

Options can be grouped together inside curly brackets. Some options expect a group as a value.

option3 = {
    suboptionA = valueA;
    suboptionB = {
        subsuboptionB1 = valueB1;
        subsuboptionB2 = valueB2;
        };
    suboptionC = valueC;
};

    

OPTIONS

                length
      ───────────────────────────
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] outline
░░███████████████████████████████████░░] border
░░██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██░░] padding
░░██░░████████████░░░░░░░░░░░░░░░░░██░░│
░░██░░█foreground█░░░░background░░░██░░│ thickness
░░██░░████████████░░░░░░░░░░░░░░░░░██░░│
░░██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██░░] padding
░░██████████████border███████████████░░] border
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] outline
      |                          |
      0                       maximum

    

In the following, a dot “.” means “suboption”. For instance “color.normal.fg” means “The suboption fg of the suboption normal of option color”.

orientation “horizontal” | “vertical” (default: vertical)

Orientation of the bar which either fills up from left to right (“horizontal”) or bottom to top (“vertical”).

x.relative ratio (default: 1.0)

Relative horizontal position on screen between 0.0 (left edge) and 1.0 (right edge). Centered by default (0.5).

x.offset pixels (default: -48)

Horizontal offset in pixels from the position specified with x.relative. This can be used for absolute positioning from an edge of the screen, creating gaps, stacking bars, etc.

y.relative ratio (default: 0.5)

Relative vertical position on screen between 0.0 (top edge) and 1.0 (bottom edge).

y.offset pixels (default: 0)

Vertical offset in pixels from the position specified with y.relative. This can be used for absolute positioning from an edge of the screen, creating gaps, stacking bars, etc.

length.relative ratio (default: 0.3)

Relative length (horizontal bar) or height (vertical bar) of the bar between 0.0 (collapsed) and 1.0 (full available length on screen).

length.offset pixels (default: 0)

Length offset in pixels from the relative length specified with length.relative. This can be used for absolute sizes (using positive values and 0 as length.relative) or creating gaps (using negative values and 1 as length.relative).

thickness.absolute positive integer (default: 24)

Height (horizontal bar) or width (vertical bar) in pixels without taking borders into account.

border pixels (default: 4)

Size of the border in pixels.

outline pixels (default: 3)

Size of the outline in pixels.

padding pixels (default: 3)

Size of the padding in pixels.

overflow “hidden” | “proportional” (default: proportional)

When “hidden” is set, a full bar is displayed using the overflow color when the value exceeds the maximum, whatever that value is. When “proportional” is set, only a portion of the bar whose size depends on the overflow is displayed using the overflow color. If the value is twice the maximum, half the bar is displayed using the overflow color. The two zones are separated by a padding-sized gap.

Each of the following have three suboptions “.fg”, “.bg”, and “.border” corresponding to hexadecimal RGB or RGBA specifications (e.g. #ff0000 or #ff0000ff) of the colors of the foreground, the backgroud, and the border. If xob is built without transparency support, the alpha channel is ignored.

color.normal colors (default: {fg = “#ffffff”; bg = “#00000090”; border = “#ffffff”;})

Colors in the general case.

color.alt colors (default: {fg = “#555555”; bg = “#00000090”; border = “#555555”;})

Colors for alternate display (e.g. muted).

color.overflow colors (default: {fg = “#ff0000”; bg = “#00000090”; border = “#ff0000”;})

Colors in case of overflow (the displayed valued exceeds the maximum).

color.altoverflow colors (default: {fg = “#ff0000”; bg = “#00000090”; border = “#555555”;})

Colors for alternate display in case of overflow.

STYLES

This example configuration file provides two styles “volume” and “backlight”. Instances of xog launched with -s volume and -s backlight will look according to the corresponding style.

volume = {
    thickness = 24;
    outline   = 1;
    border    = 2;
    padding   = 0;
    y = {
        relative = 0.9;
        offset = 0;
    };
};
backlight = {
    thickness = 24;
    outline   = 1;
    border    = 2;
    padding   = 0;
    y = {
        relative = 0.9;
        # To prevent overlap with the volume bar if displayed at the same time
        offset = -30;
    };
    color = {
        normal = {
            fg     = "#0000ff";
            bg     = "#000000";
            border = "#0000ff";
        };
    };
};

    

DEFAULT CONFIGURATION FILE

default = {
    x         = {relative = 1; offset = -48;};
    y         = {relative = 0.5; offset = 0;};
    length    = {relative = 0.3; offset = 0;};
    thickness = 24;
    outline   = 3;
    border    = 4;
    padding   = 3;
    orientation = "vertical";
    overflow = "proportional";
    color = {
        normal = {
            fg     = "#ffffff";
            bg     = "#00000090";
            border = "#ffffff";
        };
        alt = {
            fg     = "#555555";
            bg     = "#00000090";
            border = "#555555";
        };
        overflow = {
            fg     = "#ff0000";
            bg     = "#00000090";
            border = "#ff0000";
        };
        altoverflow = {
            fg     = "#550000";
            bg     = "#00000090";
            border = "#550000";
        };
    };
};