Module: Image

Note

This page is auto-generated from man/waybar-image.5.scd on the master branch. Do not edit it here — changes will be overwritten on the next sync. To update it, edit the man page(s) and open a PR.

DESCRIPTION

The image module displays container of images(or image) from a provided paths

REMARK

This module has been rewritten to add multiple image rendering functionality. To avoid users inconvenience of breaking changes, everything related to old(only one image) implementation has been left untouched including configuration part. For this reason this wiki page is split into two parts

CONFIGURATION

For single image

Option	Typeof	Default	Description
path	string		The path to the image.
exec	string		The path to the script, which should return image path file. It will only execute if the path is not set
size	integer		The width/height to render the image.
interval	integer or float		The interval (in seconds) to re-render the image. If set to a positive value, the minimum is 0.001 (1ms). Values smaller than 1ms will be set to 1ms. Zero or negative values are treated as "once". This is useful if the contents of path changes. If no interval is defined, the image will only be rendered once.
signal	integer		The signal number used to update the module. This can be used instead of interval if the file changes irregularly. The number is valid between 1 and N, where SIGRTMIN+N = SIGRTMAX.
on-click	string		Command to execute when clicked on the module.
on-click-middle	string		Command to execute when middle-clicked on the module using mousewheel.
on-update	string		Command to execute when the module is updated.
on-scroll-up	string		Command to execute when scrolling up on the module.
on-scroll-down	string		Command to execute when scrolling down on the module.
smooth-scrolling-threshold	double		Threshold to be used when scrolling.
tooltip	bool	true	Option to enable tooltip on hover.
expand	bool	false	Enables this module to consume all left over space dynamically.

SCRIPT OUTPUT

Similar to the custom module, output values of the script are newline separated. The following is the output format:

$path\n$tooltip

EXAMPLES

"image#album-art": {
	"path": "/tmp/mpd_art",
	"size": 32,
	"interval": 5,
	"on-click": "mpc toggle"
}

Using exec to fetch the image via a script:

"image#album-art": {
	"exec": "~/.config/waybar/custom/spotify/album_art.sh",
	"size": 32,
	"interval": 30
}

Where album_art.sh looks like this:

#!/bin/bash
album_art=$(playerctl -p spotify metadata mpris:artUrl)
if [[ -z $album_art ]]; then
	# spotify is dead, we should die too.
	exit
fi
curl -s "${album_art}" --output "/tmp/cover.jpeg"
echo "/tmp/cover.jpeg"

STYLE

• #image

• #image.empty

CONFIGURATION

For multiple image

Option	Typeof	Default	Description
size	integer	16	Minumum size of the rendered image in pixels.
interval	integer or float		The interval (in seconds) to re-render the module. If set to a positive value, the minimum is 0.001 (1ms). Values smaller than 1ms will be set to 1ms. Zero or negative values (and the literal "once") are treated as "once". This is useful if image path or other property is being changed over time. If no interval is provided, the module will only be rendered once.
multiple	bool	false	this parameter is used to decide if old image implementation should be used(therefore render only one image) or to pick a new implementation to rended multiple images provided from this config. default value of this parameter is false.
signal	interger	0	The signal number is used to redraw the module. This is used if interval is not provided and module should change regularly depended on external events, e.g when clicking on it. The provided value is valid between 1 and N, where SIGRTMIN+N <= SIGRTMAX. e.g if signal = 7, 34 + 7 = 41, which means waybar process should receive signal 41 to redraw this module, since SIGRTMIN = 34 (see 'kill -l').
entries	array	empty array	Json array of objects consisting of several fields this is a main part of configuration where per image properties are defined
path	string	empty string	file path of picture to draw
marker	string	empty string	user defined per image keyword(marker) to identify them, e.g in styles.css e.g if you want to draw 3 pictures and one of them dimmed, you can give marker: "dimmed" value and in styles.css write something like this #image .dimmed { opacity: 0.3 }
tooltip	string	empty string	description of the image displayed on hover
on-click	string	empty string	action to perform when clicking on the image. The action can be any system or custom binary/script e.g if { "on-click": "notify-send "hello world"" } "hello world" will appear as notification.
exec	string	empty string	same as entries but provided from external script which should dynamically return json array of objects consisting of same keys as entries. This option is specifically useful in combination with signal option without interval provided.

Examples

With entries

"image#wentr": {
  "entries": [
    {
      "path": "/home/user/Pictures/idk1.png",
      "marker": "dimmed",
      "tooltip": "dimmed image",
      "on-click": "notify-send "hello world""
    },
    {
      "path": "/home/user/Pictures/idk2.png",
      "marker": "normal",
      "on-click": "myCustomScript.py"
    }
  ],
  "size": 32,
  "interval": 1 // will redraw every 5 seconds
}

With exec

"image#wexec": {
  "exec": "imageProvider.py",
  "size": 32,
  "signal": 7 // e.g 'pkill -n waybar --signal 41' will trigger redraw
}

where imageProvider.py looks like this

#!/usr/bin/python

import json

dir = "/home/user/Pictures/"
out = [
    {"path": dir + "idk1.png", "marker": "clickable", "on-click": "echo 'hello world'"},
    {"path": dir + "idk2.png", "marker": "normal", "tooltip": "sample tooltip"},
    {"path": dir + "idk3.png", "marker": "important"},
]
res = json.dumps(out)
print(res)

Example styles

#image .important {
    opacity: 0.9;
}

#image button.important {
    opacity: 0.2
}

#image .normal {
    opacity: 0.3
}

STYLE

• #image

• #image.empty /*when image could not be rendered*/

• #image button /*when on-click is provided; a Gtk::Button is matched by the element selector, not a class*/

• #image.marker /*where marker is parameter from config*/

• #image button.marker