Cairo

Allows you to render custom content using the Lua and the Cairo drawing library. This is an advanced feature which provides a powerful escape hatch, allowing you to fetch data and render anything using an embedded scripting environment.

Scripts are automatically hot-reloaded.

Example

let {
    $config_dir = ".config/ironbar"
    $cairo = {
        type = "cairo"
        path = "$config_dir/clock.lua"
        frequency = 100
        width = 300
        height = 300
    }
} in {
    center = [ $cairo ]
}

{
  "center": [
    {
      "type": "cairo",
      "path": "$config_dir/clock.lua",
      "frequency": 100,
      "width": 300,
      "height": 300
    }
  ]
}

center:
  - type: cairo
    path: $config_dir/clock.lua
    frequency: 100
    width: 300
    height: 300

[[center]]
type = "cairo"
path = "$config_dir/clock.lua"
frequency = 100
width = 300
height = 300

Configuration

Type: cairo

`common`

See common options.

Default: None

Object keys

`common.class`

Sets one or more CSS classes, allowing you to target it in CSS using .class.

Unlike name, the class property is not expected to be unique.

Type: string
Default: None

`common.disable_popup`

Prevents the popup from opening on-click for this widget.

Type: boolean
Default: None

`common.name`

Sets the unique widget name, allowing you to target it in CSS using #name.

It is best practise (although not required) to ensure that the value is globally unique throughout the Ironbar instance to avoid clashes.

Type: string
Default: None

`common.on_click_left`Enum

A script to run when the module is left-clicked.

Supported script types: oneshot.

Default: None

Example

{ on_click_left = "echo 'event' >> log.txt" }

{
  "on_click_left": "echo 'event' >> log.txt"
}

on_click_left: echo 'event' >> log.txt

on_click_left = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_click_left_double`Enum

A script to run when the module is double-left-clicked.

Supported script types: oneshot.

Default: None

Example

{ on_click_left_double = "echo 'double click' >> log.txt" }

{
  "on_click_left_double": "echo 'double click' >> log.txt"
}

on_click_left_double: echo 'double click' >> log.txt

on_click_left_double = "echo 'double click' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_click_middle`Enum

A script to run when the module is middle-clicked.

Supported script types: oneshot.

Default: None

Example

{ on_click_middle = "echo 'event' >> log.txt" }

{
  "on_click_middle": "echo 'event' >> log.txt"
}

on_click_middle: echo 'event' >> log.txt

on_click_middle = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_click_middle_double`Enum

A script to run when the module is double-middle-clicked.

Supported script types: oneshot.

Default: None

Example

{ on_click_middle_double = "echo 'double click' >> log.txt" }

{
  "on_click_middle_double": "echo 'double click' >> log.txt"
}

on_click_middle_double: echo 'double click' >> log.txt

on_click_middle_double = "echo 'double click' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_click_right`Enum

A script to run when the module is right-clicked.

Supported script types: oneshot. /// # Example

Default: None

Example

{ on_click_right = "echo 'event' >> log.txt" }

{
  "on_click_right": "echo 'event' >> log.txt"
}

on_click_right: echo 'event' >> log.txt

on_click_right = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_click_right_double`Enum

A script to run when the module is double-right-clicked.

Supported script types: oneshot.

Default: None

Example

{ on_click_right_double = "echo 'double click' >> log.txt" }

{
  "on_click_right_double": "echo 'double click' >> log.txt"
}

on_click_right_double: echo 'double click' >> log.txt

on_click_right_double = "echo 'double click' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_mouse_enter`Enum

A script to run when the cursor begins hovering over the module.

Supported script types: oneshot.

Default: None

Example

{ on_mouse_enter = "echo 'event' >> log.txt" }

{
  "on_mouse_enter": "echo 'event' >> log.txt"
}

on_mouse_enter: echo 'event' >> log.txt

on_mouse_enter = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_mouse_exit`Enum

A script to run when the cursor stops hovering over the module.

Supported script types: oneshot.

Default: None

Example

{ on_mouse_exit = "echo 'event' >> log.txt" }

{
  "on_mouse_exit": "echo 'event' >> log.txt"
}

on_mouse_exit: echo 'event' >> log.txt

on_mouse_exit = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_scroll_down`Enum

A script to run when the module is scrolled down on.

Supported script types: oneshot.

Default: None

Example

{ on_scroll_down = "echo 'event' >> log.txt" }

{
  "on_scroll_down": "echo 'event' >> log.txt"
}

on_scroll_down: echo 'event' >> log.txt

on_scroll_down = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.on_scroll_up`Enum

A script to run when the module is scrolled up on.

Supported script types: oneshot.

Default: None

Example

{ on_scroll_up = "echo 'event' >> log.txt" }

{
  "on_scroll_up": "echo 'event' >> log.txt"
}

on_scroll_up: echo 'event' >> log.txt

on_scroll_up = "echo 'event' >> log.txt"

1`string`

No description provided.

2`Object (Script)`

No description provided.

Object keys

`common.show_if`Enum

Shows the module only if the dynamic boolean evaluates to true.

This allows for modules to be dynamically shown or hidden based on custom events.

Default: None

1`string`

Either a script or variable, to be determined.

2`Object (Script)`

No description provided.

Object keys

3`string`

No description provided.

`common.smooth_scroll_speed`

A multiplier from 0.0 - 10.0 to control the speed of smooth scrolling on trackpad.

Type: number
Default: None

`common.tooltip`

Shows this text on hover. Supports embedding scripts between {{double braces}}.

Note that full dynamic string support is not currently supported.

Type: string
Default: None

`common.transition_duration`

The length in milliseconds of the transition animation to use when showing/hiding the widget.

Note this has no effect if show_if is not configured.

Type: integer
Default: None

`common.transition_type`

The transition animation to use when showing/hiding the widget.

Note this has no effect if show_if is not configured.

Type: 'none' | 'crossfade' | 'slide_start' | 'slide_end'
Default: None

`frequency`

The number of milliseconds between each draw call.

Type: integer
Default: 200

`height`

The canvas height in pixels.

Type: integer
Default: 42

`path`

The path to the Lua script to load. This can be absolute, or relative to the working directory.

The script must contain the entry draw function.

Required

Type: string
Default: None

`width`

The canvas width in pixels.

Type: integer
Default: 42

Script

Every script must contain a function called draw. This takes a single parameter, which is the Cairo context.

Outside of this, you can do whatever you like. The full lua stdlib is available, and you can load in additional system packages as desired.

The most basic example, which draws a red square, can be seen below:

function draw(cr)
    cr:set_source_rgb(1.0, 0.0, 0.0)
    cr:paint()
end

A longer example, used to create the clock in the image at the top of the page, is shown below:

Circle clock

function get_ms()
    local ms = tostring(io.popen('date +%s%3N'):read('a')):sub(-4, 9999)
    return tonumber(ms) / 1000
end

function draw(cr)
    local center_x = 150
    local center_y = 150
    local radius = 130

    local date_table = os.date("*t")

    local hours = date_table["hour"]
    local minutes = date_table["min"]
    local seconds = date_table["sec"]
    local ms = get_ms()


    local label_seconds = seconds
    seconds = seconds + ms

    local hours_str = tostring(hours)
    if string.len(hours_str) == 1 then
        hours_str = "0" .. hours_str
    end

    local minutes_str = tostring(minutes)
    if string.len(minutes_str) == 1 then
        minutes_str = "0" .. minutes_str
    end

    local seconds_str = tostring(label_seconds)
    if string.len(seconds_str) == 1 then
        seconds_str = "0" .. seconds_str
    end

    local font_size = radius / 5.5

    cr:set_source_rgb(1.0, 1.0, 1.0)

    cr:move_to(center_x - font_size * 2.5 + 10, center_y + font_size / 2.5)
    cr:set_font_size(font_size)
    cr:show_text(hours_str .. ':' .. minutes_str .. ':' .. seconds_str)
    cr:stroke()

    if hours > 12 then
        hours = hours - 12
    end

    local line_width = radius / 8
    local start_angle = -math.pi / 2

    local end_angle = start_angle + ((hours + minutes / 60 + seconds / 3600) / 12) * 2 * math.pi
    cr:set_line_width(line_width)
    cr:arc(center_x, center_y, radius, start_angle, end_angle)
    cr:stroke()

    end_angle = start_angle + ((minutes + seconds / 60) / 60) * 2 * math.pi
    cr:set_line_width(line_width)
    cr:arc(center_x, center_y, radius * 0.8, start_angle, end_angle)
    cr:stroke()

    if seconds == 0 then
        seconds = 60
    end

    end_angle = start_angle + (seconds / 60) * 2 * math.pi
    cr:set_line_width(line_width)
    cr:arc(center_x, center_y, radius * 0.6, start_angle, end_angle)
    cr:stroke()

    return 0
end

Initialization

You can optionally create an init.lua file in your config directory. Any code in here will be executed once, on bar startup.

As variables and functions are global by default in Lua, this provides a mechanism for sharing code between multiple modules.

Styling

Selector	Description
`.cairo`	Cairo widget container.

For more information on styling, please see the styling guide.

Cairo

Example

Configuration

common

common.class

common.disable_popup

common.name

common.on_click_leftEnum

Example

1string

2Object (Script)

common.on_click_left_doubleEnum

Example

1string

2Object (Script)

common.on_click_middleEnum

Example

1string

2Object (Script)

common.on_click_middle_doubleEnum

Example

1string

2Object (Script)

common.on_click_rightEnum

Example

1string

2Object (Script)

common.on_click_right_doubleEnum

Example

1string

2Object (Script)

common.on_mouse_enterEnum

Example

1string

2Object (Script)

common.on_mouse_exitEnum

Example

1string

2Object (Script)

common.on_scroll_downEnum

Example

1string

2Object (Script)

common.on_scroll_upEnum

Example

1string

2Object (Script)

common.show_ifEnum

1string

2Object (Script)

3string

common.smooth_scroll_speed

common.tooltip

common.transition_duration

common.transition_type

frequency

height

path

width

Script

Initialization

Styling

`common`

`common.class`

`common.disable_popup`

`common.name`

`common.on_click_left`Enum

1`string`

2`Object (Script)`

`common.on_click_left_double`Enum

1`string`

2`Object (Script)`

`common.on_click_middle`Enum

1`string`

2`Object (Script)`

`common.on_click_middle_double`Enum

1`string`

2`Object (Script)`

`common.on_click_right`Enum

1`string`

2`Object (Script)`

`common.on_click_right_double`Enum

1`string`

2`Object (Script)`

`common.on_mouse_enter`Enum

1`string`

2`Object (Script)`

`common.on_mouse_exit`Enum

1`string`

2`Object (Script)`

`common.on_scroll_down`Enum

1`string`

2`Object (Script)`

`common.on_scroll_up`Enum

1`string`

2`Object (Script)`

`common.show_if`Enum

1`string`

2`Object (Script)`

3`string`

`common.smooth_scroll_speed`

`common.tooltip`

`common.transition_duration`

`common.transition_type`

`frequency`

`height`

`path`

`width`