zedfrigg/ironbar
1
0
Fork 0
mirror of https://github.com/Zedfrigg/ironbar.git synced 2025-09-15 19:26:58 +02:00
Code Activity

Merge branch 'develop' into feat/volume-icon

Browse source
This commit is contained in:
Reinout Meliesie 2025-08-20 16:04:53 +02:00
commit 55344bfdae
Signed by: zedfrigg
GPG key ID: 3AFCC06481308BC6
163 changed files with 13798 additions and 6094 deletions
Download patch file Download diff file Expand all files Collapse all files

42
docs/Compiling.md
View file

@ -22,8 +22,12 @@ You also need rust; only the latest stable version is supported.
pacman -S gtk3 gtk-layer-shell
# for http support
pacman -S openssl
# for tray support
pacman -S libdbusmenu-gtk3
# for volume support
pacman -S libpulse
# for keyboard support
pacman -S libinput
# for lua/cairo support
pacman -S luajit lua51-lgi
```
@ -34,8 +38,12 @@ pacman -S luajit lua51-lgi
apt install build-essential libgtk-3-dev libgtk-layer-shell-dev
# for http support
apt install libssl-dev
# for tray support
apt install libdbusmenu-gtk3-dev
# for volume support
apt install libpulse-dev
# for keyboard support
apt install libinput-dev
# for lua/cairo support
apt install luajit-dev lua-lgi
```
@ -46,8 +54,12 @@ apt install luajit-dev lua-lgi
dnf install gtk3-devel gtk-layer-shell-devel
# for http support
dnf install openssl-devel
# for tray support
dnf install libdbusmenu-gtk3-devel
# for volume support
dnf install pulseaudio-libs-devel
# for keyboard support
dnf install libinput-devel
# for lua/cairo support
dnf install luajit-devel lua-lgi
```
@ -88,7 +100,13 @@ cargo build --release --no-default-features \
| cairo | Enables the `cairo` module |
| clipboard | Enables the `clipboard` module. |
| clock | Enables the `clock` module. |
| custom | Enables the `custom` module. |
| focused | Enables the `focused` module. |
| keyboard | Enables the `keyboard` module without keyboard layout support. |
| keyboard+all | Enables the `keyboard` module with keyboard layout support for all compositors. |
| keyboard+sway | Enables the `keyboard` module with keyboard layout support for Sway. |
| keyboard+hyprland | Enables the `keyboard` module with keyboard layout support for Hyprland. |
| label | Enables the `label` module. |
| launcher | Enables the `launcher` module. |
| music+all | Enables the `music` module with support for all player types. |
| music+mpris | Enables the `music` module with MPRIS support. |
@ -96,15 +114,37 @@ cargo build --release --no-default-features \
| network_manager | Enables the `network_manager` module. |
| notifications | Enables the `notiications` module. |
| sys_info | Enables the `sys_info` module. |
| script | Enables the `script` module. |
| tray | Enables the `tray` module. |
| upower | Enables the `upower` module. |
| volume | Enables the `volume` module. |
| workspaces+all | Enables the `workspaces` module with support for all compositors. |
| workspaces+sway | Enables the `workspaces` module with support for Sway. |
| workspaces+hyprland | Enables the `workspaces` module with support for Hyprland. |
| workspaces+niri | Enables the `workspaces` module with support for Niri. |
| **Other** | |
| schema | Enables JSON schema support and the CLI `--print-schema` flag. |
## Shell completions
Compiling Ironbar will produce shell completions for bash, zsh and fish; these can be found in `target/completions`.
You can install these as follows:
Bash:
```shell
install -Dm644 completions/ironbar.bash /usr/share/bash-completion/completions/ironbar
```
Zsh:
```shell
install -Dm644 completions/_ironbar /usr/share/zsh/site-functions/_ironbar
```
Fish:
```shell
install -Dm644 completions/ironbar.fish /usr/share/fish/vendor_completions.d/ironbar.fish
```
## Speeding up compiling
@ -164,4 +204,4 @@ codegen-backend = true
[profile.dev]
codegen-backend = "cranelift"
```
```

24
docs/Configuration guide.md
View file

@ -280,10 +280,12 @@ Check [here](config) for an example config file for a fully configured bar in ea
The following table lists each of the top-level bar config options:
| Name | Type | Default | Description |
|--------------------|-----------------------------------------|---------|---------------------------------------------------------------|
| `ironvar_defaults` | `Map<string, string>` | `{}` | Map of [ironvar](ironvars) keys against their default values. |
| `monitors` | `Map<string, BarConfig or BarConfig[]>` | `null` | Map of monitor names against bar configs. |
| Name | Type | Default | Description |
|--------------------|-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `ironvar_defaults` | `Map<string, string>` | `{}` | Map of [ironvar](ironvars) keys against their default values. |
| `monitors` | `Map<string, BarConfig or BarConfig[]>` | `null` | Map of monitor names against bar configs. |
| `icon_theme` | `string` | `null` | Name of the GTK icon theme to use. Leave blank to use default. |
| `icon_overrides` | `Map<string, string>` | `{}` | Map of image inputs to override names. Usually used for app IDs (or classes) to icon names, overriding the app's default icon. |
> [!TIP]
> `monitors` is only required if you are following **2b** or **2c** (ie not the same bar across all monitors).
@ -308,7 +310,6 @@ The following table lists each of the bar-level bar config options:
| `layer` | `background` or `bottom` or `top` or `overlay` | `top` | The layer-shell layer to place the bar on. |
| `exclusive_zone` | `boolean` | `true` unless `start_hidden` is enabled. | Whether the bar should reserve an exclusive zone around it. |
| `popup_gap` | `integer` | `5` | The gap between the bar and popup window. |
| `icon_theme` | `string` | `null` | Name of the GTK icon theme to use. Leave blank to use default. |
| `start_hidden` | `boolean` | `false`, or `true` if `autohide` set | Whether the bar should be hidden when the application starts. Enabled by default when `autohide` is set. |
| `autohide` | `integer` | `null` | The duration in milliseconds before the bar is hidden after the cursor leaves. Leave unset to disable auto-hide behaviour. |
| `start` | `Module[]` | `[]` | Array of left or top modules. |
@ -350,7 +351,14 @@ For information on the `Script` type, and embedding scripts in strings, see [her
| Name | Type | Default | Description |
|-----------|----------|---------|-----------------------------------------------------------------------------------|
| `tooltip` | `string` | `null` | Shows this text on hover. Supports embedding scripts between `{{double braces}}`. |
| `name` | `string` | `null` | Sets the unique widget name, allowing you to style it using `#name`. |
| `class` | `string` | `null` | Sets one or more CSS classes, allowing you to style it using `.class`. |
| `name` | `string` | `null` | The unique widget name, allowing you to style it using `#name`. |
| `class` | `string` | `null` | One or more CSS classes, allowing you to style it using `.class`. |
For more information on styling, please see the [styling guide](styling-guide).
For more information on styling, please see the [styling guide](styling-guide).
#### Formatting
| Name | Type | Default | Description |
|---------------|--------------------------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `orientation` | `horizontal` or `vertical` (shorthand: `'h'` or `'v'`) | `horizontal` or `vertical` | The direction in which the widget and its text are laid out. Some modules additionally provide a `direction` option to provide further control. |
| `justify` | `left`, `right`, `center`, `fill` | `left` | The justification (alignment) of the widget text shown on the bar. |

25
docs/Controlling Ironbar.md
View file

@ -10,7 +10,8 @@ You can also view help per sub-command or command, for example using `ironbar va
The CLI supports plaintext and JSON output. Plaintext will:
- Print `ok` for empty success responses
- Print the returned body for success responses
- Print the returned body for each success response
- Some commands act on multiple objects, in which case the CLI will print one line for each body.
- Print `error` to followed by the error on the next line for error responses. This is printed to `stderr`.
Example:
@ -34,13 +35,11 @@ All error responses will cause the CLI to exit code 3.
The server listens on a Unix socket.
The path is printed on startup, and can usually be found at `/run/user/$UID/ironbar-ipc.sock`.
Commands and responses are sent as JSON objects.
Commands and responses are sent as JSON objects.
The JSON should be minified and must NOT contain any `\n` characters.
Commands will have a `command` key, and a `subcommand` key when part of a sub-command.
The message buffer is currently limited to `1024` bytes.
Particularly large messages will be truncated or cause an error.
The full spec can be found below.
## Libraries
@ -150,6 +149,9 @@ Each key/value pair is on its own `\n` separated newline. The key and value are
### `bar`
> [!NOTE]
> If there are multiple bars by the same name, the `bar` subcommand will act on all of them and return a `multi` response for commands that get a value.
#### `show`
Forces a bar to be shown, regardless of the current visibility state.
@ -324,6 +326,17 @@ The operation completed successfully, with response data.
}
```
### `multi`
The operation completed successfully on multiple objects, with response data.
```json
{
"type": "multi",
"values": ["lorem ipsum", "dolor sit"]
}
```
### `error`
The operation failed.
@ -335,4 +348,4 @@ Message is optional.
"type": "error",
"message": "lorem ipsum"
}
```
```

2
docs/Dynamic values.md
View file

@ -25,7 +25,7 @@ Dynamic booleans can use a single source of either a script or variable to contr
For scripts, you can just write these directly with no notation.
Only polling scripts are supported.
The script exit code is used, where `0` is `true` and any other code is `false.
The script exit code is used, where `0` is `true` and any other code is `false`.
For variables, use the standard `#name` notation.
An empty string, `0` and `false` are treated as false.

50
docs/GTK4.md Normal file
View file

@ -0,0 +1,50 @@
As the GTK3 and gtk-layer-shell crates are now deprecated, there is a need to move to GTK 4.
The `refactor/gtk-4` branch and PR [#112](https://github.com/JakeStanger/ironbar/pull/112) are tracking the code upgrade.
This page documents the port progress.
Assistance in the porting process is very much welcomed, no matter how small.
As many modules have not been ported, the default feature set will fail to compile.
It is therefore necessary to compile manually with `--no-default-features`, enabling only the working modules:
```shell
cargo run --no-default-features \
--features config+all,clock,cairo
```
A full list of feature flags can be found [here](Compiling#features).
## Core functionality
| Area | Status | Notes |
|-----------------|--------|-------------------------------------------------------------------------------------------------------|
| Bar | ✅ | |
| Popups | ✅ | Potential styling issues, otherwise working. |
| Theming - CSS | ✅ | |
| Theming - Icons | ⚠️ | GTK4 does not support icon theming - always uses default theme. Image scaling may be incorrect. |
| Config - Format | ❌ ️ | Angle/justify properties have been removed from widgets and should now be controlled via CSS instead. |
| IPC | ⚠️ | Some popup-related commands not implemented. |
## Modules
| Module | Status | Notes |
|-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------|
| Bindmode | ❌ | |
| Cairo | ✅ | |
| Clipboard | ✅ | |
| Clock | ✅ | |
| Custom | ✅ | |
| Focused | ✅ | |
| Keyboard | ✅ | |
| Label | ✅ | |
| Launcher | ⚠️ | Popup behaviour may be a little strange. |
| Music | ✅ | |
| Network Manager | ❌ | |
| Notifications | ✅ | |
| Script | ✅ | |
| SysInfo | ✅ | |
| Tray | ❌ | GTK4 removes widgets required to move the tray. No `libdbusmenu-gtk4` either. will need to manually re-create menus with custom widgets. |
| UPower | ❌ | |
| Volume | ❌ | |
| Workspaces | ✅ | |

17
docs/Ironvars.md
View file

@ -6,4 +6,19 @@ Any UTF-8 string is a valid value.
Reference values using `#my_variable`. These update as soon as the value changes.
You can set defaults using the `ironvar_defaults` key in your top-level config.
You can set defaults using the `ironvar_defaults` key in your top-level config.
Some modules (such as `sys_info`) expose their values over the Ironvar interface,
allowing you to build custom interfaces and integrate into scripts.
These present their values inside read-only namespaces.
Some examples below:
```shell
ironbar var list
ironbar var list sysinfo
ironbar var list sysinfo.disk_percent
ironbar var get sysinfo.disk_percent./home
ironbar var get sysinfo.disk_percent.mean
ironbar var get sysinfo.memory_percent
```

4
docs/_Sidebar.md
View file

@ -4,6 +4,7 @@
- [Configuration guide](configuration-guide)
- [Images](images)
- [Styling guide](styling-guide)
- [GTK 4 Port](gtk4)
# Dynamic content
@ -24,13 +25,16 @@
# Modules
- [Bindmode](bindmode)
- [Cairo](cairo)
- [Clipboard](clipboard)
- [Clock](clock)
- [Custom](custom)
- [Focused](focused)
- [Keyboard](keyboard)
- [Label](label)
- [Launcher](launcher)
- [Menu](menu)
- [Music](music)
- [Network Manager](network-manager)
- [Notifications](notifications)

78
docs/modules/Bindmode.md Normal file
View file

@ -0,0 +1,78 @@
> [!IMPORTANT]
> This module is currently only available on Sway and Hyprland.
Displays Sway's current binding mode or [Hyprland's current submap](https://wiki.hyprland.org/Configuring/Binds/#submaps)
in a label. Nothing is displayed if no binding mode is active.
## Configuration
> Type: `bindmode`
| Name | Type | Default | Description |
| --------------------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `truncate` | `'start'` or `'middle'` or `'end'` or `Map` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "bindmode",
"truncate": "start"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "bindmode"
truncate = "start"
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "bindmode"
truncate: "start"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "bindmode"
truncate = "start"
}
]
}
```
</details>
## Styling
| Selector | Description |
| ----------- | ---------------------- |
| `.bindmode` | Bind mode label widget |
For more information on styling, please see the [styling guide](styling-guide).

18
docs/modules/Clipboard.md
View file

@ -12,15 +12,15 @@ Supports plain text and images.
> Type: `clipboard`
| Name | Type | Default | Description |
|-----------------------|---------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `icon` | `string` or [image](images) | `󰨸` | Icon to show on the widget button. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `max_items` | `integer` | `10` | Maximum number of items to show in the popup. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `Map` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| Name | Type | Default | Description |
|-----------------------|------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `icon` | `string` or [image](images) | `󰨸` | Icon to show on the widget button. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `max_items` | `integer` | `10` | Maximum number of items to show in the popup. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
<details>
<summary>JSON</summary>

13
docs/modules/Clock.md
View file

@ -8,12 +8,13 @@ Clicking on the widget opens a popup with the time and a calendar.
> Type: `clock`
| Name | Type | Default | Description |
|----------------|----------|------------------------------------|-------------------------------------------------------------------------------------|
| `format` | `string` | `%d/%m/%Y %H:%M` | Date/time format string. Pango markup is supported. |
| `format_popup` | `string` | `%H:%M:%S` | Date/time format string to display in the popup header. Pango markup is supported. |
| `locale` | `string` | `$LC_TIME` or `$LANG` or `'POSIX'` | Locale to use (eg `en_GB`). Defaults to the system language (reading from env var). |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the time on the clock button. |
| Name | Type | Default | Description |
|----------------|------------------------------------------------------------|------------------------------------|-------------------------------------------------------------------------------------|
| `format` | `string` | `%d/%m/%Y %H:%M` | Date/time format string. Pango markup is supported. |
| `format_popup` | `string` | `%H:%M:%S` | Date/time format string to display in the popup header. Pango markup is supported. |
| `locale` | `string` | `$LC_TIME` or `$LANG` or `'POSIX'` | Locale to use (eg `en_GB`). Defaults to the system language (reading from env var). |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the time on the clock button. |
| `justify` | `'left'`', `'right'`, `'center'`, or `'fill'` | `'left'` | Justification (alignment) of the date/time shown on the bar. |
> Detail on available tokens can be found here: <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>

31
docs/modules/Custom.md
View file

@ -47,6 +47,8 @@ A container to place nested widgets inside.
|---------------|------------------------------------------------------------|----------------|-------------------------------------------------------------------|
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Whether child widgets should be horizontally or vertically added. |
| `widgets` | `(Module or Widget)[]` | `[]` | List of modules/widgets to add to this box. |
| `halign` | `'start'` or `'center'` or `'end'` or `'fill'` | `'fill'` | The horizontal alignment of the box within its parent container. |
| `valign` | `'start'` or `'center'` or `'end'` or `'fill'` | `'fill'` | The vertical alignment of the box within its parent container. |
#### Label
@ -54,10 +56,16 @@ A text label. Pango markup is supported.
> Type `label`
| Name | Type | Default | Description |
|---------|-------------------------------------------------|---------|---------------------------------------------------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the label. |
| Name | Type | Default | Description |
|-----------------------|------------------------------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the label text. |
| `justify` | `'left'`, `'right'`, `'center'`, or `'fill'` | `'left'` | Justification (alignment) of the label text. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
#### Button
@ -65,12 +73,13 @@ A clickable button, which can run a command when clicked.
> Type `button`
| Name | Type | Default | Description |
|------------|-------------------------------------------------|---------|--------------------------------------------------------------------------------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. Ignored if `widgets` is set. |
| `widgets` | `(Module or Widget)[]` | `[]` | List of modules/widgets to add to this button. |
| `on_click` | `string [command]` | `null` | Command to execute. More on this [below](#commands). |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the button. |
| Name | Type | Default | Description |
|---------------|------------------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. Ignored if `widgets` is set. |
| `widgets` | `(Module or Widget)[]` | `[]` | List of modules/widgets to add to this button. |
| `on_click` | `string [command]` | `null` | Command to execute. More on this [below](#commands). |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the label text. |
| `justify` | `'left'`, `'right'`, `'center'`, or `'fill'` | `'left'` | Justification (alignment) of the label text. |
#### Image
@ -425,4 +434,4 @@ The following top-level selectors are always available:
| `.custom` | Custom widget container. |
| `.popup-custom` | Custom widget popup container. |
For more information on styling, please see the [styling guide](styling-guide).
For more information on styling, please see the [styling guide](styling-guide).

18
docs/modules/Focused.md
View file

@ -10,15 +10,15 @@ Displays the title and/or icon of the currently focused window.
> Type: `focused`
| Name | Type | Default | Description |
|-----------------------|---------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `show_icon` | `boolean` | `true` | Whether to show the app's icon. |
| `show_title` | `boolean` | `true` | Whether to show the app's title. |
| `icon_size` | `integer` | `32` | Size of icon in pixels. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `Map` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| Name | Type | Default | Description |
|-----------------------|------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `show_icon` | `boolean` | `true` | Whether to show the app's icon. |
| `show_title` | `boolean` | `true` | Whether to show the app's title. |
| `icon_size` | `integer` | `32` | Size of icon in pixels. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
<details>
<summary>JSON</summary>

122
docs/modules/Keyboard.md Normal file
View file

@ -0,0 +1,122 @@
> [!NOTE]
> This module requires your user is in the `input` group.
> [!IMPORTANT]
> The keyboard layout feature is only available on Sway and Hyprland.
Displays the toggle state of the capslock, num lock and scroll lock keys, and the current keyboard layout.
![Screenshot of keyboard widget](https://f.jstanger.dev/github/ironbar/keys.png)
## Configuration
> Type: `keyboard`
| Name | Type | Default | Description |
| ------------------ | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `show_caps` | `boolean` | `true` | Whether to show capslock indicator. |
| `show_num` | `boolean` | `true` | Whether to show num lock indicator. |
| `show_scroll` | `boolean` | `true` | Whether to show scroll lock indicator. |
| `show_layout` | `boolean` | `true` | Whether to show the keyboard layout button. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `icons.caps_on` | `string` or [image](images) | `󰪛` | Icon to show for enabled capslock indicator. |
| `icons.caps_off` | `string` or [image](images) | `''` | Icon to show for disabled capslock indicator. |
| `icons.num_on` | `string` or [image](images) | `` | Icon to show for enabled num lock indicator. |
| `icons.num_off` | `string` or [image](images) | `''` | Icon to show for disabled num lock indicator. |
| `icons.scroll_on` | `string` or [image](images) | `` | Icon to show for enabled scroll lock indicator. |
| `icons.scroll_off` | `string` or [image](images) | `''` | Icon to show for disabled scroll lock indicator. |
| `icons.layout_map` | `Map<string, string or image>` | `{}` | Map of icons or labels to show for a particular keyboard layout. Layouts use their actual name if not present in the map. Layouts are matched in the order they appear in the map. If a pattern to match ends with a `*`, it acts as a wildcard, matching any layout name that begins with the part before the `*`. |
| `seat` | `string` | `seat0` | ID of the Wayland seat to attach to. |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "keyboard",
"show_scroll": false,
"icons": {
"caps_on": "󰪛",
"layout_map": {
"English (US)": "🇺🇸",
"Ukrainian": "🇺🇦"
}
}
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "keyboard"
show_scroll = false
[end.icons]
caps_on = "󰪛"
[end.icons.layout_map]
"English (US)" = "🇺🇸"
Ukrainian = "🇺🇦"
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: keyboard
show_scroll: false
icons:
caps_on: 󰪛
layout_map:
"English (US)": 🇺🇸
Ukrainian: 🇺🇦
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "keyboard"
show_scroll = false
icons.caps_on = "󰪛"
icons.layout_map.'English (US)' = "🇺🇸"
icons.layout_map.Ukrainian = "🇺🇦"
}
]
}
```
</details>
## Styling
| Selector | Description |
| -------------------------- | ------------------------------------------ |
| `.keyboard` | Keys box container widget. |
| `.keyboard .key` | Individual key indicator container widget. |
| `.keyboard .key.enabled` | Key indicator where key is toggled on. |
| `.keyboard .key.caps` | Capslock key indicator. |
| `.keyboard .key.num` | Num lock key indicator. |
| `.keyboard .key.scroll` | Scroll lock key indicator. |
| `.keyboard .key.image` | Key indicator image icon. |
| `.keyboard .key.text-icon` | Key indicator textual icon. |
| `.keyboard .layout` | Keyboard layout indicator. |
For more information on styling, please see the [styling guide](styling-guide).

11
docs/modules/Label.md
View file

@ -7,9 +7,14 @@ For more advanced use-cases, use [custom](custom).
> Type: `label`
| Name | Type | Default | Description |
|---------|-------------------------------------------------|---------|------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Text to show on label. |
| Name | Type | Default | Description |
|-----------------------|------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Text to show on label. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
<details>
<summary>JSON</summary>

51
docs/modules/Launcher.md
View file

@ -3,7 +3,8 @@
Windows-style taskbar that displays running windows, grouped by program.
Hovering over a program with multiple windows open shows a popup with each window.
Clicking an icon/popup item focuses or launches the program.
Left clicking an icon/popup item focuses the program if it has any open instances or otherwise launches a new instance of the program.
Middle clicking an icon always launches a new instance of the program.
Optionally displays a launchable set of favourites.
![Screenshot showing several open applications, including a popup showing multiple terminal windows.](https://f.jstanger.dev/github/ironbar/launcher.png)
@ -12,13 +13,24 @@ Optionally displays a launchable set of favourites.
> Type: `launcher`
| | Type | Default | Description |
|--------------|------------|---------|-----------------------------------------------------------------------------------------------------|
| `favorites` | `string[]` | `[]` | List of app IDs (or classes) to always show at the start of the launcher |
| `show_names` | `boolean` | `false` | Whether to show app names on the button label. Names will still show on tooltips when set to false. |
| `show_icons` | `boolean` | `true` | Whether to show app icons on the button. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `reversed` | `boolean` | `false` | Whether to reverse the order of favorites/items |
| | Type | Default | Description |
|-----------------------------|---------------------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `favorites` | `string[]` | `[]` | List of app IDs (or classes) to always show at the start of the launcher. |
| `show_names` | `boolean` | `false` | Whether to show app names on the button label. Names will still show on tooltips when set to false. |
| `show_icons` | `boolean` | `true` | Whether to show app icons on the button. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `launch_command` | `string` | `gtk-launch {app_name}` | Command used to launch applications. |
| `reversed` | `boolean` | `false` | Whether to reverse the order of favorites/items |
| `minimize_focused` | `boolean` | `true` | Whether to minimize a focused window when its icon is clicked. Only minimizes single windows. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `end` | Location of the ellipses and where to truncate text from. Applies to application names when `show_names` is enabled. |
| `truncate.length` | `integer` | `null` | Fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | Maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `truncate_popup.mode` | `'start'` or `'middle'` or `'end'` or `off` | `middle` | Location of the ellipses and where to truncate text from. Applies to window names within a group popup. |
| `truncate_popup.length` | `integer` | `null` | Fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate_popup.max_length` | `integer` | `25` | Maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `page_size` | `integer` | `1000` | Number of items to show on a page. When the number of items is reached, controls appear which can be used to move forward/back through the list of items. |
| `icons.page_back` | `string` or [image](images) | `󰅁` | Icon to show for page back button. |
| `icons.page_forward` | `string` or [image](images) | `󰅂` | Icon to show for page forward button. |
<details>
<summary>JSON</summary>
@ -94,14 +106,17 @@ start:
## Styling
| Selector | Description |
|-------------------------------|--------------------------|
| `.launcher` | Launcher widget box |
| `.launcher .item` | App button |
| `.launcher .item.open` | App button (open app) |
| `.launcher .item.focused` | App button (focused app) |
| `.launcher .item.urgent` | App button (urgent app) |
| `.popup-launcher` | Popup container |
| `.popup-launcher .popup-item` | Window button in popup |
| Selector | Description |
|--------------------------------------|---------------------------|
| `.launcher` | Launcher widget box |
| `.launcher .item` | App button |
| `.launcher .item.open` | App button (open app) |
| `.launcher .item.focused` | App button (focused app) |
| `.launcher .item.urgent` | App button (urgent app) |
| `.launcher .pagination` | Pagination controls box |
| `.launcher .pagination .btn-back` | Pagination back button |
| `.launcher .pagination .btn-forward` | Pagination forward button |
| `.popup-launcher` | Popup container |
| `.popup-launcher .popup-item` | Window button in popup |
For more information on styling, please see the [styling guide](styling-guide).
For more information on styling, please see the [styling guide](styling-guide).

158
docs/modules/Menu.md Normal file
View file

@ -0,0 +1,158 @@
Application menu that shows installed programs and optionally custom entries.
This works by reading all `.desktop` files on the system.
Clicking the menu button will open the main menu.
Clicking on any application category will open a sub-menu with any installed applications that match.
It is also possible to add custom categories and actions into the menu.
![Screenshot of open menu showing applications inside Office category](https://f.jstanger.dev/github/ironbar/menu.png)
## Configuration
| | Type | Default | Description |
|-----------------------|------------------------------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `start` | `MenuEntry[]` | `[]` | Items to add to the start of the main menu. |
| `center` | `MenuEntry[]` | Default XDG menu | Items to add to the centre of the main menu. By default this shows a number of XDG entries that should cover all common applications. |
| `end` | `MenuEntry[]` | `[]` | Items to add to the end of the main menu. |
| `height` | `integer` | `null` | Height of the menu. Leave null to resize dynamically. |
| `width` | `integer` | `null` | Width of the menu. Leave null to resize dynamically. |
| `label` | `string` | `≡` | Label to show on the menu button on the bar. |
| `label_icon` | `string` | `null` | Icon to show on the menu button on the bar. |
| `label_icon_size` | `integer` | `16` | Size of the label_icon image. |
| `launch_command` | `string` | `gtk-launch {app_name}` | Command used to launch applications. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | Applies to popup. The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | Applies to popup. The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | Applies to popup. The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | Applies to popup. The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
### `MenuEntry`
Each entry can be one of three types:
- `xdg_entry` - Contains all applications matching the configured `categories`.
- `xdg_other` - Contains all applications not covered by `xdg_entry` categories.
- `custom` - Individual shell command entry.
| | Type | Default | Description |
|--------------|----------------------------------------|---------|----------------------------------------------------------------------------------------|
| `type` | `xdg_entry` or `xdg_other` or `custom` | | Type of the entry. |
| `label` | `string` | `''` | Label of the entry's button. |
| `icon` | `string` | `null` | Icon for the entry's button. |
| `categories` | `string[]` | `[]` | [`xfg_entry`] List of freedesktop.org categories to include in this entry's sub menu . |
| `on_click` | `string` | `''` | [`custom`] Shell command to execute when the entry's button is clicked |
### Default XDG Menu
Setting the `center` menu entries will override the default menu.
The default menu can be found in the `default` example files [here](https://github.com/jakestanger/ironbar/blob/examples/menu/).
<details>
<summary>JSON</summary>
```json
{
"start": [
{
"type": "menu",
"start": [
{
"type": "custom",
"label": "Terminal",
"on_click": "xterm"
}
],
"height": 440,
"width": 200,
"icon": "archlinux",
"label": null
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[start]]
type = "memu"
height = 400
width = 200
icon = "archlinux"
[[start.start]]
type = "custom"
label = "Terminal"
on_click = "xterm"
```
</details>
<details>
<summary>YAML</summary>
```yaml
start:
- type: "menu"
start:
- type: custom
label: Terminal
on_click: xterm
height: 440
width: 200
icon: archlinux
label: null
```
</details>
<details>
<summary>Corn</summary>
```corn
{
start = [
{
type = "menu"
start = [
{
type = "custom"
label = "Terminal"
on_click = "xterm"
}
]
height = 440
width = 200
icon = "archlinux"
label = null
}
]
}
```
</details>
## Styling
| Selector | Description |
|--------------------------------------|-----------------------------------|
| `.menu` | Menu button |
| `.popup-menu` | Main container of the popup |
| `.popup-menu .main` | Main menu of the menu |
| `.popup-menu .main .category` | Category button |
| `.popup-menu .main .category.open` | Open category button |
| `.popup-menu .main .main-start` | Container for `start` entries |
| `.popup-menu .main .main-center` | Container for `center` entries |
| `.popup-menu .main .main-end` | Container for `end` entries |
| `.popup-menu .sub-menu` | All sub-menus |
| `.popup-menu .sub-menu .application` | Application button within submenu |
For more information on styling, please see the [styling guide](styling-guide).

58
docs/modules/Music.md
View file

@ -11,29 +11,39 @@ in MPRIS mode, the widget will listen to all players and automatically detect/di
> Type: `music`
| | Type | Default | Description |
|-----------------------|---------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `player_type` | `'mpris'` or `'mpd'` | `mpris` | Whether to connect to MPRIS players or an MPD server. |
| `format` | `string` | `{title} / {artist}` | Format string for the widget. More info below. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `Map` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` | `null` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `icons.play` | `string` or [image](images) | `` | Icon to show when playing. |
| `icons.pause` | `string` or [image](images) | `` | Icon to show when paused. |
| `icons.prev` | `string` or [image](images) | `󰒮` | Icon to show on previous button. |
| `icons.next` | `string` or [image](images) | `󰒭` | Icon to show on next button. |
| `icons.volume` | `string` or [image](images) | `󰕾` | Icon to show under popup volume slider. |
| `icons.track` | `string` or [image](images) | `󰎈` | Icon to show next to track title. |
| `icons.album` | `string` or [image](images) | `󰀥` | Icon to show next to album name. |
| `icons.artist` | `string` or [image](images) | `󰠃` | Icon to show next to artist name. |
| `show_status_icon` | `boolean` | `true` | Whether to show the play/pause icon on the widget. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `cover_image_size` | `integer` | `128` | Size to render album art image at inside popup. |
| `host` | `string` | `localhost:6600` | [MPD Only] TCP or Unix socket for the MPD server. |
| `music_dir` | `string` | `$HOME/Music` | [MPD Only] Path to MPD server's music directory on disc. Required for album art. |
See [here](images) for information on images.
| | Type | Default | Description |
|------------------------------------|------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `player_type` | `'mpris'` or `'mpd'` | `mpris` | Whether to connect to MPRIS players or an MPD server. |
| `format` | `string` | `{title} / {artist}` | Format string for the widget. More info below. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `truncate_popup_artist` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate_popup_artist.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate_popup_artist.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate_popup_artist.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `truncate_popup_album` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate_popup_album.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate_popup_album.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate_popup_album.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `truncate_popup_title` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate_popup_title.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate_popup_title.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate_popup_title.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
| `icons.play` | `string` or [image](images) | `` | Icon to show when playing. |
| `icons.pause` | `string` or [image](images) | `` | Icon to show when paused. |
| `icons.prev` | `string` or [image](images) | `󰒮` | Icon to show on previous button. |
| `icons.next` | `string` or [image](images) | `󰒭` | Icon to show on next button. |
| `icons.volume` | `string` or [image](images) | `󰕾` | Icon to show under popup volume slider. |
| `icons.track` | `string` or [image](images) | `󰎈` | Icon to show next to track title. |
| `icons.album` | `string` or [image](images) | `󰀥` | Icon to show next to album name. |
| `icons.artist` | `string` or [image](images) | `󰠃` | Icon to show next to artist name. |
| `show_status_icon` | `boolean` | `true` | Whether to show the play/pause icon on the widget. |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `cover_image_size` | `integer` | `128` | Size to render album art image at inside popup. |
| `host` | `string` | `localhost:6600` | [MPD Only] TCP or Unix socket for the MPD server. |
| `music_dir` | `string` | `$HOME/Music` | [MPD Only] Path to MPD server's music directory on disc. Required for album art. |
<details>
<summary>JSON</summary>
@ -170,4 +180,4 @@ and will be replaced with values from the currently playing track:
| `.popup-music .progress .slider` | Slider inside progress container |
| `.popup-music .progress .label` | Duration label inside progress container |
For more information on styling, please see the [styling guide](styling-guide).
For more information on styling, please see the [styling guide](styling-guide).

3
docs/modules/Network-Manager.md
View file

@ -17,6 +17,9 @@ Supports wired ethernet, wifi, cellular data and VPN connections among others.
|-------------|-----------|---------|-------------------------|
| `icon_size` | `integer` | `24` | Size to render icon at. |
> [!NOTE]
> This module does not support module-level [layout options](module-level-options#layout).
<details>
<summary>JSON</summary>

2
docs/modules/Notifications.md
View file

@ -21,6 +21,8 @@ Clicking the widget opens the SwayNC panel.
| `icons.open_some` | `string` | `󱥁` | Icon to show when the panel is open, with notifications. |
| `icons.open_dnd` | `string` | `󱅮` | Icon to show when the panel is open, with DnD enabled. Takes higher priority than count-based icons. |
> [!NOTE]
> This module does not support module-level [layout options](module-level-options#layout).
<details>
<summary>JSON</summary>

290
docs/modules/Sys-Info.md
View file

@ -3,6 +3,8 @@ Displays one or more labels containing system information.
Separating information across several labels allows for styling each one independently.
Pango markup is supported.
Options can be provided in a token to specify operations, units and formatting.
![Screenshot showing sys-info module with widgets for all of the types of formatting tokens](https://user-images.githubusercontent.com/5057870/196059090-4056d083-69f0-4e6f-9673-9e35dc29d9f0.png)
@ -10,17 +12,17 @@ Pango markup is supported.
> Type: `sys_info`
| Name | Type | Default | Description |
|--------------------|--------------------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `format` | `string[]` | `null` | Array of strings including formatting tokens. For available tokens see below. |
| `interval` | `integer` or `Map` | `5` | Seconds between refreshing. Can be a single value for all data or a map of individual refresh values for different data types. |
| `interval.memory` | `integer` | `5` | Seconds between refreshing memory data |
| `interval.cpu` | `integer` | `5` | Seconds between refreshing cpu data |
| `interval.temps` | `integer` | `5` | Seconds between refreshing temperature data |
| `interval.disks` | `integer` | `5` | Seconds between refreshing disk data |
| `interval.network` | `integer` | `5` | Seconds between refreshing network data |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the labels. |
| `direction` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | How the labels are laid out (not the rotation of an individual label). |
| Name | Type | Default | Description |
|--------------------|------------------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------|
| `format` | `string[]` | `null` | Array of strings including formatting tokens. For available tokens see below. |
| `interval` | `integer` or `Map` | `5` | Seconds between refreshing. Can be a single value for all data or a map of individual refresh values for different data types. |
| `interval.memory` | `integer` | `5` | Seconds between refreshing memory data. |
| `interval.cpu` | `integer` | `5` | Seconds between refreshing cpu data. |
| `interval.temps` | `integer` | `5` | Seconds between refreshing temperature data. |
| `interval.disks` | `integer` | `5` | Seconds between refreshing disk data. |
| `interval.network` | `integer` | `5` | Seconds between refreshing network data. |
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the labels. |
| `direction` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | How the labels are laid out (not the rotation of an individual label). |
<details>
<summary>JSON</summary>
@ -30,12 +32,11 @@ Pango markup is supported.
"end": [
{
"format": [
" {cpu_percent}% | {temp_c:k10temp-Tccd1}°C",
" {memory_used} / {memory_total} GB ({memory_percent}%)",
"| {swap_used} / {swap_total} GB ({swap_percent}%)",
"󰋊 {disk_used:/} / {disk_total:/} GB ({disk_percent:/}%)",
"󰓢 {net_down:enp39s0} / {net_up:enp39s0} Mbps",
"󰖡 {load_average:1} | {load_average:5} | {load_average:15}",
" {cpu_percent}% | {cpu_frequency} GHz | {temp_c@CPUTIN}°C",
" {memory_used} / {memory_total} GB ({memory_available} | {memory_percent}%) | {swap_used} / {swap_total} GB ({swap_free} | {swap_percent}%)",
"󰋊 {disk_used#T@/:.1} / {disk_total#T@/:.1} TB ({disk_percent@/}%) | {disk_read} / {disk_write} MB/s",
"󰓢 {net_down@enp39s0} / {net_up@enp39s0} Mbps",
"󰖡 {load_average_1} | {load_average_5} | {load_average_15}",
"󰥔 {uptime}"
],
"interval": {
@ -60,13 +61,12 @@ Pango markup is supported.
[[end]]
type = 'sys_info'
format = [
' {cpu_percent}% | {temp_c:k10temp-Tccd1}°C',
' {memory_used} / {memory_total} GB ({memory_percent}%)',
'| {swap_used} / {swap_total} GB ({swap_percent}%)',
'󰋊 {disk_used:/} / {disk_total:/} GB ({disk_percent:/}%)',
'󰓢 {net_down:enp39s0} / {net_up:enp39s0} Mbps',
'󰖡 {load_average:1} | {load_average:5} | {load_average:15}',
'󰥔 {uptime}',
" {cpu_percent}% | {cpu_frequency} GHz | {temp_c@CPUTIN}°C",
" {memory_used} / {memory_total} GB ({memory_available} | {memory_percent}%) | {swap_used} / {swap_total} GB ({swap_free} | {swap_percent}%)",
"󰋊 {disk_used#T@/:.1} / {disk_total#T@/:.1} TB ({disk_percent@/}%) | {disk_read} / {disk_write} MB/s",
"󰓢 {net_down@enp39s0} / {net_up@enp39s0} Mbps",
"󰖡 {load_average_1} | {load_average_5} | {load_average_15}",
"󰥔 {uptime}"
]
[end.interval]
@ -87,13 +87,12 @@ temps = 5
```yaml
end:
- format:
- ' {cpu_percent}% | {temp_c:k10temp-Tccd1}°C'
- ' {memory_used} / {memory_total} GB ({memory_percent}%)'
- '| {swap_used} / {swap_total} GB ({swap_percent}%)'
- '󰋊 {disk_used:/} / {disk_total:/} GB ({disk_percent:/}%)'
- '󰓢 {net_down:enp39s0} / {net_up:enp39s0} Mbps'
- '󰖡 {load_average:1} | {load_average:5} | {load_average:15}'
- '󰥔 {uptime}'
- " {cpu_percent}% | {cpu_frequency} GHz | {temp_c@CPUTIN}°C"
- " {memory_used} / {memory_total} GB ({memory_available} | {memory_percent2}%) | {swap_used} / {swap_total} GB ({swap_free} | {swap_percent}%)"
- "󰋊 {disk_used#T@/:.1} / {disk_total#T@/:.1} TB ({disk_percent@/}%) | {disk_read} / {disk_write} MB/s"
- "󰓢 {net_down@enp39s0} / {net_up@enp39s0} Mbps"
- "󰖡 {load_average_1} | {load_average_5} | {load_average_15}"
- "󰥔 {uptime}"
interval:
cpu: 1
disks: 300
@ -121,12 +120,11 @@ end:
interval.networks = 3
format = [
" {cpu_percent}% | {temp_c:k10temp-Tccd1}°C"
" {memory_used} / {memory_total} GB ({memory_percent}%)"
"| {swap_used} / {swap_total} GB ({swap_percent}%)"
"󰋊 {disk_used:/} / {disk_total:/} GB ({disk_percent:/}%)"
"󰓢 {net_down:enp39s0} / {net_up:enp39s0} Mbps"
"󰖡 {load_average:1} | {load_average:5} | {load_average:15}"
" {cpu_percent}% | {cpu_frequency} GHz | {temp_c@CPUTIN}°C"
" {memory_used} / {memory_total} GB ({memory_available} | {memory_percent2}%) | {swap_used} / {swap_total} GB ({swap_free} | {swap_percent}%)"
"󰋊 {disk_used#T@/:.1} / {disk_total#T@/:.1} TB ({disk_percent@/}%) | {disk_read} / {disk_write} MB/s"
"󰓢 {net_down@enp39s0} / {net_up@enp39s0} Mbps"
"󰖡 {load_average_1} | {load_average_5} | {load_average_15}"
"󰥔 {uptime}"
]
}
@ -138,39 +136,195 @@ end:
### Formatting Tokens
The following tokens can be used in the `format` configuration option:
The below table lists the tokens which can be used in the `format` configuration option.
More information about each of these and the additional options can be found further below.
| Token | Description |
|--------------------------|------------------------------------------------------------------------------------|
| **CPU** | |
| `{cpu_percent}` | Total CPU utilisation percentage |
| **Memory** | |
| `{memory_free}` | Memory free in GB. |
| `{memory_used}` | Memory used in GB. |
| `{memory_total}` | Memory total in GB. |
| `{memory_percent}` | Memory utilisation percentage. |
| `{swap_free}` | Swap free in GB. |
| `{swap_used}` | Swap used in GB. |
| `{swap_total}` | Swap total in GB. |
| `{swap_percent}` | Swap utilisation percentage. |
| **Temperature** | |
| `{temp_c:[sensor]}` | Temperature in degrees C. Replace `[sensor]` with the sensor label. |
| `{temp_f:[sensor]}` | Temperature in degrees F. Replace `[sensor]` with the sensor label. |
| **Disk** | |
| `{disk_free:[mount]}` | Disk free space in GB. Replace `[mount]` with the disk mountpoint. |
| `{disk_used:[mount]}` | Disk used space in GB. Replace `[mount]` with the disk mountpoint. |
| `{disk_total:[mount]}` | Disk total space in GB. Replace `[mount]` with the disk mountpoint. |
| `{disk_percent:[mount]}` | Disk utilisation percentage. Replace `[mount]` with the disk mountpoint. |
| **Network** | |
| `{net_down:[adapter]}` | Average network download speed in Mbps. Replace `[adapter]` with the adapter name. |
| `{net_up:[adapter]}` | Average network upload speed in Mbps. Replace `[adapter]` with the adapter name. |
| **System** | |
| `{load_average:1}` | 1-minute load average. |
| `{load_average:5}` | 5-minute load average. |
| `{load_average:15}` | 15-minute load average. |
| `{uptime}` | System uptime formatted as `HH:mm`. |
| Token | Default Function | Default Unit | Default Formatting |
|--------------------------|------------------|--------------|--------------------|
| **CPU** | | | |
| `{cpu_frequency[#core]}` | `mean` | MHz | `.2` |
| `{cpu_percent[#core]}` | `mean` | % | `0<2` |
| **Memory** | | | |
| `{memory_free}` | N/A | GB | `0<4.1` |
| `{memory_available}` | N/A | GB | `0<4.1` |
| `{memory_used}` | N/A | GB | `0<4.1` |
| `{memory_total}` | N/A | GB | `0<4.1` |
| `{memory_percent}` | N/A | GB | `0<4.1` |
| `{swap_free}` | N/A | GB | `0<4.1` |
| `{swap_used}` | N/A | GB | `0<4.1` |
| `{swap_total}` | N/A | GB | `0<4.1` |
| `{swap_percent}` | N/A | GB | `0<4.1` |
| **Temperature** | | | |
| `{temp_c[#sensor]}` | `max` | °C | |
| `{temp_f[#sensor]}` | `max` | °F | |
| **Disk** | | | |
| `{disk_free[#mount]}` | `sum` | GB | |
| `{disk_used[#mount]}` | `sum` | GB | |
| `{disk_total[#mount]}` | `sum` | GB | |
| `{disk_percent[#mount]}` | `sum` | % | |
| `{disk_read[#mount]}` | `sum` | MB/s | |
| `{disk_write[#mount]}` | `sum` | MB/s | |
| **Network** | | | |
| `{net_down[#adapter]}` | `sum` | Mb/s | |
| `{net_up[#adapter]}` | `sum` | Mb/s | |
| **System** | | | |
| `{load_average_1}` | N/A | - | `.2` |
| `{load_average_5}` | N/A | - | `.2` |
| `{load_average_15}` | N/A | - | `.2` |
| `{uptime}` | N/A | ??? | ??? |
For Intel CPUs, you can typically use `coretemp-Package-id-0` for the temperature sensor. For AMD, you can use `k10temp-Tccd1`.
#### Functions and names
Many of the tokens operate on a value set, as opposed to an individual value:
- CPU tokens operate on each physical thread.
- Temperature tokens operate on each sensor.
- Disk tokens operate on each mount.
- Network tokens operate on each adapter.
By default, these will apply a function to the full set to reduce them down to a single value.
The list of available functions is shown below:
| Function | Description |
|----------|-----------------------------------------|
| `sum` | Adds each value in the set. |
| `min` | Gets the smallest value in the set. |
| `max` | Gets the largest value in the set. |
| `mean` | Gets the mean average value of the set. |
It is also possible to get only a single value from the set by specifying a name instead of a function.
| Token category | Valid name |
|----------------|------------------------------------------|
| CPU | A CPU thread, eg `cpu0`, `cpu1`, ... |
| Temperature | A sensor name, eg `CPUTIN`. |
| Disk | A disk mountpoint, eg `/`, `/home`, ... |
| Network | An adapter name, eg `eth0` or `enp30s0`. |
To specify a name or function, use a `@`. For example, to show disk percent for `/home`:
```json
"{disk_percent@/home}%"
```
To show total CPU utilization where each core represents 100% (like `htop` etc):
```json
"{cpu_percent@sum}%"
```
> [!TIP]
> Available values can be queried over IPC using the CLI.
> This can be particularly useful for sensors, which tend not to have obvious names.
>
> ```shell
> ironbar var list sysinfo.temp_c
> ```
>
> Some usual cases to look out for:
>
> - `k10temp` is an AMD CPU internal sensor
> - Motherboard chipsets tend to prefix their sensors accordingly. For example, `CPUTIN`, `nct6687 CPU`, `asusec AMD`.
> - `amdgpu` is as it suggests.
>
> Sensor names are pulled from `hwmon` and should vaguely line up with the output of `sensors`
#### Prefixes and units
For tokens which return an appropriate unit, you can specify the SI prefix (or unit in some special cases).
The following options can be supplied:
| Name | Value |
|---------|-------|
| Kilo | `k` |
| Mega | `M` |
| Giga | `G` |
| Tera | `T` |
| Peta | `P` |
| | |
| Kibi | `ki` |
| Mebi | `Mi` |
| Gibi | `Gi` |
| Tebi | `Ti` |
| Pebi | `Pi` |
| | |
| Kilobit | `kb` |
| Megabit | `Mb` |
| Gigabit | `Gb` |
To specify a prefix or unit, use a `#`. For example, to show free total disk space in terabytes:
```json
"{disk_free#T} TB"
```
#### Formatting
To control the formatting of the resultant number,
a subset of Rust's string formatting is implemented. This includes:
- Width
- Fill/Alignment
- Precision
Formatting is specified with a `:` and MUST be the last part of a token.
##### Width
The width controls the minimum string length of the value.
Specifying just a width will left-pad the value with `0` until the value reaches the target length.
The width can be any value from `1-9`. Larger values are not supported.
For example, to render CPU usage as `045%`:
```json
"{cpu_usage:3}%"
```
##### Fill/Alignment
These options can be used to control the `width` property.
To specify the fill and alignment, prefix the width with a character and a direction.
Fill characters can be any single UTF-8 character EXCEPT 1-9. Alignment must be one of:
- `<` - Left fill
- `^` - Center fill
- `>` - Right fill
For example, to render CPU usage as ` 45%`:
```json
"{cpu_usage: <3}%"
```
##### Precision
The number of decimal places a value is shown to can be controlled using precision.
Any value is supported.
To specify precision, include a `.` followed by the value. If other options are supplied, this MUST come after.
For example, to render used disk space to 2dp:
```json
"{disk_used:.2} GB"
```
---
#### Combining Options
Each of the token options can be combined to create more complex solutions.
Putting it all together, you could show the free disk space on your `/home` partition in terabytes,
left-padded with spaces to a min width of 5, and shown to 2dp as follows:
```json
"{disk_used@/home#T: <5.2} TB"
```
## Styling

16
docs/modules/Tray.md
View file

@ -6,11 +6,11 @@ Displays a fully interactive icon tray using the KDE `libappindicator` protocol.
> Type: `tray`
| Name | Type | Default | Description |
|----------------------|-----------|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `direction` | `string` | `left_to_right` if bar is horizontal, `top_to_bottom` otherwise | Direction to display the tray items. Possible values: `top_to_bottom`, `bottom_to_top`, `left_to_right`, `right_to_left` |
| `icon_size` | `integer` | `16` | Size in pixels to display tray icons as. |
| `prefer_theme_icons` | `bool` | `true` | Requests that icons from the theme be used over the item-provided item. Most items only provide one or the other so this will have no effect in most circumstances. |
| Name | Type | Default | Description |
|----------------------|------------------------------------------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `direction` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | Matches bar orientation | The direction in which to pack tray icons. |
| `icon_size` | `integer` | `16` | Size in pixels to display tray icons as. |
| `prefer_theme_icons` | `bool` | `true` | Requests that icons from the theme be used over the item-provided item. Most items only provide one or the other so this will have no effect in most circumstances. |
<details>
<summary>JSON</summary>
@ -55,12 +55,10 @@ end:
```corn
{
end = [
{
end = [{
type = "tray"
direction = "top_to_bottom"
}
]
}]
}
```

3
docs/modules/Upower.md
View file

@ -1,5 +1,8 @@
Displays system power information such as the battery percentage, and estimated time to empty.
> [!NOTE]
> This module requires that `upower` is installed and its service running.
`TODO: ADD SCREENSHOT`
[//]: # (![Screenshot]&#40;https://user-images.githubusercontent.com/5057870/184540521-2278bdec-9742-46f0-9ac2-58a7b6f6ea1d.png&#41;)

27
docs/modules/Volume.md
View file

@ -1,6 +1,7 @@
Displays the current volume level.
Clicking on the widget opens a volume mixer, which allows you to change the device output level,
the default playback device, and control application volume levels individually.
Use `truncate` option to control the display of application titles in the volume mixer.
This requires PulseAudio to function (`pipewire-pulse` is supported).
@ -10,14 +11,18 @@ This requires PulseAudio to function (`pipewire-pulse` is supported).
> Type: `volume`
| Name | Type | Default | Description |
|-----------------------|----------|------------------------|----------------------------------------------------------------------------------------------------------------|
| `format` | `string` | `{icon} {percentage}%` | Format string to use for the widget button label. |
| `max_volume` | `float` | `100` | Maximum value to allow volume sliders to reach. Pulse supports values > 100 but this may result in distortion. |
| `icons.volume_high` | `string` | `󰕾` | Icon to show for high volume levels. |
| `icons.volume_medium` | `string` | `󰖀` | Icon to show for medium volume levels. |
| `icons.volume_low` | `string` | `󰕿` | Icon to show for low volume levels. |
| `icons.muted` | `string` | `󰝟` | Icon to show for muted outputs. |
| Name | Type | Default | Description |
|-----------------------|------------------------------------------------------|------------------------|----------------------------------------------------------------------------------------------------------------|
| `format` | `string` | `{icon} {percentage}%` | Format string to use for the widget button label. |
| `max_volume` | `float` | `100` | Maximum value to allow volume sliders to reach. Pulse supports values > 100 but this may result in distortion. |
| `icons.volume_high` | `string` | `󰕾` | Icon to show for high volume levels. |
| `icons.volume_medium` | `string` | `󰖀` | Icon to show for medium volume levels. |
| `icons.volume_low` | `string` | `󰕿` | Icon to show for low volume levels. |
| `icons.muted` | `string` | `󰝟` | Icon to show for muted outputs. |
| `truncate` | `'start'` or `'middle'` or `'end'` or `off` or `Map` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. Use the long-hand `Map` version if specifying a length. |
| `truncate.mode` | `'start'` or `'middle'` or `'end'` or `off` | `off` | The location of the ellipses and where to truncate text from. Leave null to avoid truncating. |
| `truncate.length` | `integer` | `null` | The fixed width (in chars) of the widget. Leave blank to let GTK automatically handle. |
| `truncate.max_length` | `integer` | `null` | The maximum number of characters before truncating. Leave blank to let GTK automatically handle. |
<details>
<summary>JSON</summary>
@ -29,6 +34,7 @@ This requires PulseAudio to function (`pipewire-pulse` is supported).
"type": "volume",
"format": "{icon} {percentage}%",
"max_volume": 100,
"truncate": "middle",
"icons": {
"volume_high": "󰕾",
"volume_medium": "󰖀",
@ -51,6 +57,7 @@ This requires PulseAudio to function (`pipewire-pulse` is supported).
type = "volume"
format = "{icon} {percentage}%"
max_volume = 100
truncate = "middle"
[end.icons]
volume_high = "󰕾"
@ -69,6 +76,7 @@ end:
- type: "volume"
format: "{icon} {percentage}%"
max_volume: 100
truncate: "middle"
icons:
volume_high: "󰕾"
volume_medium: "󰖀"
@ -88,6 +96,7 @@ end:
type = "volume"
format = "{icon} {percentage}%"
max_volume = 100
truncate = "end"
icons.volume_high = "󰕾"
icons.volume_medium = "󰖀"
icons.volume_low = "󰕿"
@ -125,4 +134,4 @@ The following tokens can be used in the `format` config option:
| `.popup-volume .apps-box .app-box .slider` | Application volume slider. |
| `.popup-volume .apps-box .app-box .btn-mute` | Application volume mute toggle button. |
For more information on styling, please see the [styling guide](styling-guide).
For more information on styling, please see the [styling guide](styling-guide).

38
docs/modules/Workspaces.md
View file

@ -1,4 +1,5 @@
> ⚠ **This module is currently only supported on Sway and Hyprland**
> [!IMPORTANT]
> This module is currently only supported on Sway, Hyprland and Niri**
Shows all current workspaces. Clicking a workspace changes focus to it.
@ -8,14 +9,14 @@ Shows all current workspaces. Clicking a workspace changes focus to it.
> Type: `workspaces`
| Name | Type | Default | Description |
|----------------|---------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name_map` | `Map<string, string or image>` | `{}` | A map of actual workspace names to their display labels/images. Workspaces use their actual name if not present in the map. See [here](images) for information on images. |
| `favorites` | `Map<string, string[]>` or `string[]` | `[]` | Workspaces to always show. This can be for all monitors, or a map to set per monitor. |
| `hidden` | `string[]` | `[]` | A list of workspace names to never show |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `all_monitors` | `boolean` | `false` | Whether to display workspaces from all monitors. When `false`, only shows workspaces on the current monitor. |
| `sort` | `'added'` or `'alphanumeric'` | `alphanumeric` | The method used for sorting workspaces. `added` always appends to the end, `alphanumeric` sorts by number/name. |
| Name | Type | Default | Description |
|----------------|---------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name_map` | `Map<string, string or image>` | `{}` | A map of actual workspace names to their display labels/images. Workspaces use their actual name if not present in the map. See [here](images) for information on images. |
| `favorites` | `Map<string, string[]>` or `string[]` | `[]` | Workspaces to always show. This can be for all monitors, or a map to set per monitor. |
| `hidden` | `string[]` | `[]` | A list of workspace names to never show |
| `icon_size` | `integer` | `32` | Size to render icon at (image icons only). |
| `all_monitors` | `boolean` | `false` | Whether to display workspaces from all monitors. When `false`, only shows workspaces on the current monitor. |
| `sort` | `'added'` or `'label'` or `'name'` | `label` | The method used for sorting workspaces. `added` always appends to the end, `label` sorts by displayed value, and `name` sorts by workspace name. |
<details>
<summary>JSON</summary>
@ -98,15 +99,16 @@ end:
## Styling
| Selector | Description |
|--------------------------------|--------------------------------------|
| `.workspaces` | Workspaces widget box |
| `.workspaces .item` | Workspace button |
| `.workspaces .item.focused` | Workspace button (workspace focused) |
| Selector | Description |
| ------------------------------ | ------------------------------------------------------- |
| `.workspaces` | Workspaces widget box |
| `.workspaces .item` | Workspace button |
| `.workspaces .item.focused` | Workspace button (workspace focused) |
| `.workspaces .item.visible` | Workspace button (workspace visible, including focused) |
| `.workspaces .item.inactive` | Workspace button (favourite, not currently open)
| `.workspaces .item .icon` | Workspace button icon (any type) |
| `.workspaces .item .text-icon` | Workspace button icon (textual only) |
| `.workspaces .item .image` | Workspace button icon (image only) |
| `.workspaces .item.urgent` | Workspace button (workspace contains urgent window) |
| `.workspaces .item.inactive` | Workspace button (favourite, not currently open) |
| `.workspaces .item .icon` | Workspace button icon (any type) |
| `.workspaces .item .text-icon` | Workspace button icon (textual only) |
| `.workspaces .item .image` | Workspace button icon (image only) |
For more information on styling, please see the [styling guide](styling-guide).