BLOCKBAR(1)

NAME
blockbar - Blocks based status bar for X window managers

SYNOPSIS
blockbar [config_file | -h | --help] bbc [command]

OPTIONS

config_file
    Use the provided configuration file, rather than the default.

-h, --help
    Print the help text.

CONFIG
Unless specified, blockbar looks for the configuration file in the following places:

1   $XDG_CONFIG_HOME/blockbar/config

2   $HOME/.config/blockbar/config

The configuration file is a JSON file, that has the following sections:

    {
        <General bar settings>,
        "modules": [
            {
                "path": "...",
                "settings": {
                    ...
                }
            },
            ...
        ],
        "left": [
            <Left block settings objects>,
            {
                ...
            },
            {
                ...
            },
            ...
        ],
        "center": [
            <Center block settings objects>
        ],
        "right: [
            <Right block settings objects>
        ]
    }

A variable of type "Color" can be either:

1   an array in the format of [r, g, b] or [r, g, b, a], where r, g, b, and a are integers in the range of 0-255.

2   a string in the format of "#RRGGBB", "#RGB", "#RRGGBBAA", or "#RGBA", where RR, GG, BB, and AA are hexadecimal integers in the range of 0x00-0xFF. If the string is in the format of "#RGB" or "#RGBA", the string will be interpreted as if it was written as "#RRGGBB" or "#RRGGBBAA" respectively.

A variable of type "Position" can have a value of "left", "right", or "center".

General bar settings
Key | Description | Type | Default
height | Height of the bar. | Integer | 22
marginvert | Margin above or below the bar. | Integer | 0
marginhoriz | Margin on the left and right of the bar. | Integer | 0
xoffset | Horizontal offset of the bar. | Integer | 0
radius | Radius of the curvature of the corners of the bar. | Integer | 0
padding | Padding on both sides of each block. | Integer | 5
background | Background color of the bar. | Color | [0,0,0]
foreground | Default text color. | Color | [255,255,255]
font | Font name and size. | String | System default
position | Postion of the screen that the bar appears on. "top" or "bottom". | String | "top"
divwidth | Divider width. | Integer | 1
divheight | Divider height. | Integer | -
divvertmargin | Margin above and below the dividers. Ignored if divheight is set. | Integer | 4
divcolor | Divider color. | Color | [51,51,51]
borderwidth | Width of the border. | Integer | 0
bordercolor | Color of the border. | Color | [0, 0, 0, 0]
traydiv | If true, a divider is drawn between the blocks and the tray. | Integer | true
traypadding | Padding to the right of each tray icon. | Integer | 2
trayiconsize | Width and height of each tray icon. | Integer | 18
traybar | Name of output (see xrandr) that the tray should display on. | String | -
trayside | Side of the bar that the tray appears on. "left" or "right". | Position | "right"

Block Settings
Key | Description | Type | Default
module | The name of the module that handles the block. | String | "text"
eachmon | If true, the block will execute once per monitor, BAR_OUTPUT will be set to the output's name. | Boolean | false
exec | Path to the executable to run. | String | ""
interval | Time in milliseconds between each execution of the block's script. If 0, the block will only execute once. | Integer | 0
padding | Adds to the padding on both sides of the block. | Integer | 0
paddingleft | Adds to the padding to the left of the block. | Integer | 0
paddingright | Adds to the padding on the right of the block. | Integer | 0
nodiv | If true, the divider to the right of the block is not drawn. | Boolean | false

ENVIRONMENT VARIABLES

The following environment variable should be set before blockbar and bbc are executed.

  BLOCKBAR_SOCKET
The path of the socket used for the communication between bbc and blockbar. If this variable is not set, /tmp/blockbar-socket is used instead.

The following environment variables can be set by blockbar when a block is executed.

  BLOCK_BUTTON
If the block's execution was triggered by a click, this variable will be set to the mouse button's number ("1", "2", etc).

  BAR_OUTPUT
If the block has eachmon=true, or the block was clicked, this variable will be set to the output's name (see xrandr).

  CLICK_X
If the block's execution was triggered by a click, this variable will be set to the x coordinate of the cursor.

  BLOCK_X
If the block has eachmon=true, or the block was clicked, this variable will be set to the x coordinate of the block.

  BLOCK_WIDTH
The width of the block, including padding.

  BLOCK_ID
The ID of the block.

BBC COMMANDS

  list
list Lists blocks by their indices and exec value. Blocks with eachmon=true are indicated by an asterisk following the index.

  exec
exec <index> Executes a block's script.

  list-properties
list-properties Lists the type, name, and description of each block property.

  list-settings
list-settings Lists the type, name, and description of each of the bar's settings.

  property
property <index>[:output] <property> [value] Gets or sets the value of a property of a block. If the block has eachmon=true, the output value will need to be set. If a valid value is provided, the property's value will be changed, otherwise, an error will be returned if the value is invalid, or the current value of the property will be returned if no value is provided.

  setting
setting <setting> [value] Gets or sets the value of a setting of the bar. If a valid value is provided, the setting's value will be changed, otherwise, an error will be returned if the value is invalid, or the current value of the setting will be returned if no value is provided.

  new
new [--eachmon] Creates a new block and returns the new block's index. If --eachmon is passed, the block will be created with eachmon=true.

  rm
rm <index> Removes a block.

  move-left
move-left <index> Moves a block to the left.

  move-right
move-right <index> Moves a block to the right.

  dump
dump [--explicit] Dumps the current configuration to stdout. By default, only properties and settings that differ from their default values will be dumped, however, if --explicit is passed, all properties and settings will be dumped.

  list-modules
list-modules Lists the modules that are currently loaded.

  load-module
load-module <module file> Loads a module.

  unload-module
unload-module <module name> Unloads a module.

  raise
raise <module name> Raises a render module.

  lower
lower <module name> Lowers a render module.

AUTHOR
Sam Bazley <sambazley@protonmail.com>