Waybar/man/waybar-image.5.scd

waybar-image(5)

# NAME

waybar - image module

# 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*

*path*: ++
	typeof: string ++
	The path to the image.

*exec*: ++
	typeof: string ++
	The path to the script, which should return image path file. ++
	It will only execute if the path is not set

*size*: ++
	typeof: integer ++
	The width/height to render the image.

*interval*: ++
	typeof: 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*: ++
	typeof: 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*: ++
	typeof: string ++
	Command to execute when clicked on the module.

*on-click-middle*: ++
	typeof: string ++
	Command to execute when middle-clicked on the module using mousewheel.

*on-update*: ++
	typeof: string ++
	Command to execute when the module is updated.

*on-scroll-up*: ++
	typeof: string ++
	Command to execute when scrolling up on the module.

*on-scroll-down*: ++
	typeof: string ++
	Command to execute when scrolling down on the module.

*smooth-scrolling-threshold*: ++
	typeof: double ++
	Threshold to be used when scrolling.

*tooltip*: ++
	typeof: bool ++
	default: true ++
	Option to enable tooltip on hover.

*expand*: ++
	typeof: bool ++
	default: 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"
}
```

# STYLE

- *#image*
- *#image.empty*

# CONFIGURATION

For multiple *image*

*size*: ++
	typeof: integer ++
	default: 16 ++
	Minumum size of the rendered image in pixels.

*interval*: ++
	typeof: 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*: ++
	typeof: bool ++
	default: 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*: ++
	typeof: interger ++
	default: 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*: ++
	typeof: array ++
	default: empty array ++
	Json array of objects consisting of several fields ++
	this is a main part of configuration where per image properties are defined

	*path*: ++
	typeof: string ++
	default: empty string ++
	file path of picture to draw

	*marker*: ++
	typeof: string ++
	default: 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*: ++
	typeof: string ++
	default: empty string ++
	description of the image displayed on hover

	*on-click*: ++
	typeof: string ++
	default: 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*: ++
	typeof: string ++
	default: 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*