GENERAL CASE¶

Use a program that listens to events (such as a change in audio volume levels) and issues new values on the standard output automatically. Launch the_listener_program | xob. Ready to use input programs for audio volume and screen backlight are available on the xob project homepage: https://github.com/florentc/xob

FALLBACK METHOD¶

In case no input program fits your needs, you may trigger changes manually. Append new values in a named pipe (a pipe that persists as a special file on the filesystem) and have xob consume them as they arrive.

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¶

The configuration file adheres to the libconfig syntax. An option is set up using “=” or “:”. The options are separated using “;”.

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¶

All the options described above must be encompassed inside a style specification. A style consists of a group of all or some of the options described above. The name of the style is the name of an option at the root level of the configuration file. When an option is missing from a style, the default values are used instead. A configuration file may specify several styles (at least 1) to choose using the -s argument.

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";


        };


    };
};