JakeStanger/ironbar
1
1
Fork 0
mirror of https://github.com/JakeStanger/ironbar.git synced 2024-11-22 05:34:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

wip doc rewrite

Browse Source
This commit is contained in:
Jake Stanger 2024-02-25 15:52:07 +00:00
parent 47e3e0f9b2
commit 0109073d40
No known key found for this signature in database
GPG Key ID: C51FC8F9CB0BEA61
43 changed files with 1049 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/Scripts.md
View File

@ -9,15 +9,14 @@ Three types of scripts exist: polling, oneshot and watching:
Normally they will repeat this at an interval, hence the name, although in some cases they may only run on a user
event.
If the script exited code 0, the `stdout` will be used. Otherwise, `stderr` will be printed to the log.
- **Oneshot** scripts are a variant of polling scripts.
They wait for script to exit, and may do something with the output, but are only fired by user events instead of the interval.
Generally options that accept oneshot scripts do not support the other types.
- **Watching** scripts start a long-running process. Every time the process writes to `stdout`, the last line is captured
and used.
- **Oneshot** scripts are a variant of polling scripts.
They wait for script to exit, and may do something with the output, but are only fired by user events instead of the interval.
Generally options that accept oneshot scripts do not support the other types.
Oneshot scripts only support shorthand syntax and do not accept mode/interval parameters.
One should prefer to use watch-mode where possible, as it removes the overhead of regularly spawning processes.
That said, there are some cases which only support polling. These are indicated by `Script [polling]` as the option
type.
## Writing script configs

273
docs/configuration/Configuration guide.md Normal file
View File

@ -0,0 +1,273 @@
By default, you get a single bar at the bottom of all your screens.
To change that, you'll unsurprisingly need a config file.
This page details putting together the skeleton for your config to get you to a stage where you can start configuring
modules.
It may look long and overwhelming, but that is just because the bar supports a lot of scenarios!
If you want to see some ready-to-go config files check
the [examples folder](https://github.com/JakeStanger/ironbar/tree/master/examples)
and the example pages in the sidebar.
## 1. Create config file
The config file lives inside the `ironbar` directory in your `XDG_CONFIG_DIR`, which is usually `~/.config/ironbar`.
Ironbar supports a range of configuration formats, so you can pick your favourite:
- `config.json`
- `config.toml`
- `config.yaml`
- `config.corn` (Experimental, includes variable support for re-using blocks.
See [here](https://github.com/jakestanger/corn) for info)
You can also override the default config path using the `IRONBAR_CONFIG` environment variable.
## 2. Pick your use-case
Ironbar gives you a few ways to configure the bar to suit your needs.
This allows you to keep your config simple and relatively flat if your use-case is simple,
and make it more complex if required.
### a) I want the same bar across all monitors
Place the bar config inside the top-level object. This is automatically applied to each of your monitors.
<details>
<summary>JSON</summary>
```json
{
"position": "bottom",
"height": 42,
"start": [],
"center": [],
"end": []
}
```
</details>
<details>
<summary>TOML</summary>
```toml
position = "bottom"
height = 42
start = []
center = []
end = []
```
</details>
<details>
<summary>YAML</summary>
```yaml
position: "bottom"
height: 42
start: [ ]
center: [ ]
end: [ ]
```
</details>
<details>
<summary>Corn</summary>
```
{
position = "bottom"
height = 42
start = []
center = []
end = []
}
```
</details>
### b) I want my config to differ across one or more monitors
Create a map/object called `monitors` inside the top-level object.
Each of the map's keys should be an output name,
and each value should be an object containing the bar config.
You can still define a top-level "default" config to use for unspecified monitors.
Alternatively, leave the top-level `start`, `center` and `end` keys null to hide bars on unspecified monitors.
> [!TIP]
> To find your output names, run `wayland-info | grep wl_output -A1`.
<details>
<summary>JSON</summary>
```json
{
"monitors": {
"DP-1": {
"start": []
},
"DP-2": {
"position": "bottom",
"height": 30,
"start": []
}
}
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[monitors]
[monitors.DP-1]
start = []
[monitors.DP-2]
position = "bottom"
height = 30
start = []
```
</details>
<details>
<summary>YAML</summary>
```yaml
monitors:
DP-1:
start: [ ]
DP-2:
position: "bottom"
height: 30
start: [ ]
```
</details>
<details>
<summary>Corn</summary>
```
{
monitors.DP-1.start = []
monitors.DP-2 = {
position = "bottom"
height = 30
start = []
}
}
```
</details>
### c) I want one or more monitors to have multiple bars
Create a map/object called `monitors` inside the top-level object.
Each of the map's keys should be an output name.
If you want the screen to have multiple bars, use an array of bar config objects.
If you want the screen to have a single bar, use an object.
To find your output names, run `wayland-info | grep wl_output -A1`.
<details>
<summary>JSON</summary>
```json
{
"monitors": {
"DP-1": [
{
"start": []
},
{
"position": "top",
"start": []
}
],
"DP-2": {
"position": "bottom",
"height": 30,
"start": []
}
}
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[monitors]
[[monitors.DP-1]]
start = []
[[monitors.DP-2]]
position = "top"
start = []
[monitors.DP-2]
position = "bottom"
height = 30
start = []
```
</details>
<details>
<summary>YAML</summary>
```yaml
monitors:
DP-1:
- start: [ ]
- position: "top"
start: [ ]
DP-2:
position: "bottom"
height: 30
start: [ ]
```
</details>
<details>
<summary>Corn</summary>
```corn
{
monitors.DP-1 = [
{ start = [] }
{ position = "top" start = [] }
]
monitors.DP-2 = {
position = "bottom"
height = 30
start = []
}
}
```
</details>
## 3. Write your bar config(s)
Once you have the basic config structure set up, it's time to actually configure your bar(s).
Documentation on the available options can be found in the following locations:
- [Top-level options](top-level-options)
- [Module-level options](module-level-options)
- A [example config file](config) for a fully configured bar in each file format.
- Module-specific options on each module documentation page.

9
docs/configuration/Module level options.md Normal file
View File

@ -0,0 +1,9 @@
## Common options
<% config::common::CommonConfig %>
---
## Truncate options
<% config::truncate::TruncateMode %>

1
docs/configuration/Top level options.md Normal file
View File

@ -0,0 +1 @@
<% config::Config { depth = 0 } %>

7
docs/modules/Cairo.md
View File

@ -14,12 +14,7 @@ Scripts are automatically hot-reloaded.
> Type: `cairo`
| Name | Type | Default | Description |
|--------------------|-----------|---------|----------------------------------------------------|
| `path` | `string` | `null` | The path to the Lua script to load. |
| `frequency` | `float` | `200` | The number of milliseconds between each draw call. |
| `width` | `integer` | `42` | The canvas width in pixels. |
| `height` | `integer` | `42` | The canvas height in pixels. |
<% modules::cairo::CairoModule %>
<details>
<summary>JSON</summary>

10
docs/modules/Clipboard.md
View File

@ -12,15 +12,7 @@ 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. |
<% modules::clipboard::ClipboardModule %>
<details>
<summary>JSON</summary>

9
docs/modules/Clock.md
View File

@ -8,14 +8,7 @@ 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. |
> Detail on available tokens can be found here: <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
<% modules::clock::ClockModule %>
<details>
<summary>JSON</summary>

60
docs/modules/Custom.md
View File

@ -18,10 +18,7 @@ or [label](label) if you only need a single text label.
This module can be quite fiddly to configure as you effectively have to build a tree of widgets by hand.
It is well worth looking at the examples.
| Name | Type | Default | Description |
|---------|------------------------|------------|------------------------------------------|
| `bar` | `(Module or Widget)[]` | `[]` | Modules and widgets to add to the bar. |
| `popup` | `(Module or Widget)[]` | `null` | Modules and widgets to add to the popup. |
<% modules::custom::CustomModule %>
### `Widget`
@ -31,11 +28,7 @@ You can think of these like HTML elements and their attributes.
Every widget has the following options available; `type` is mandatory.
You can also add common [module-level options](https://github.com/JakeStanger/ironbar/wiki/configuration-guide#32-module-level-options) on a widget.
| Name | Type | Default | Description |
|---------|-------------------------------------------------------------------------------|---------|-------------------------------|
| `type` | `'box'` or `'label'` or `'button'` or `'image'` or `'slider'` or `'progress'` | `null` | Type of GTK widget to create. |
| `name` | `string` | `null` | Widget name. |
| `class` | `string` | `null` | Widget class name. |
<% modules::custom::Widget { table = true } %>
#### Box
@ -43,10 +36,7 @@ A container to place nested widgets inside.
> Type: `box`
| Name | Type | Default | Description |
|---------------|------------------------------------------------------------|----------------|-------------------------------------------------------------------|
| `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. |
<% modules::custom::r#box::BoxWidget { depth = 3 } %>
#### Label
@ -54,10 +44,7 @@ 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. |
<% modules::custom::label::LabelWidget { depth = 3 } %>
#### Button
@ -65,12 +52,7 @@ 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. |
<% modules::custom::button::ButtonWidget { depth = 3 } %>
#### Image
@ -78,10 +60,7 @@ An image or icon from disk or http.
> Type `image`
| Name | Type | Default | Description |
|--------|---------------------------------------------------------------------|---------|-------------------------------------------------------|
| `src` | [image](images) via [Dynamic String](dynamic-values#dynamic-string) | `null` | Image source. |
| `size` | `integer` | `null` | Width/height of the image. Aspect ratio is preserved. |
<% modules::custom::image::ImageWidget { depth = 3 } %>
#### Slider
@ -89,20 +68,6 @@ A draggable slider.
> Type: `slider`
Note that `on_change` will provide the **floating point** value as an argument.
If your input program requires an integer, you will need to round it.
| Name | Type | Default | Description |
|---------------|------------------------------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------|
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Orientation of the slider. |
| `value` | `Script` | `null` | Script to run to get the slider value. Output must be a valid number. |
| `on_change` | `string [command]` | `null` | Command to execute when the slider changes. More on this [below](#commands). |
| `min` | `float` | `0` | Minimum slider value. |
| `max` | `float` | `100` | Maximum slider value. |
| `step` | `float` | - | The increment to change when scrolling with the mouse wheel. If left blank, will use the default determined by the environment. |
| `length` | `integer` | `null` | Slider length. GTK will automatically size if left unset. |
| `show_label` | `boolean` | `true` | Whether to show the value label above the slider. |
The example slider widget below shows a volume control for MPC,
which updates the server when changed, and polls the server for volume changes to keep the slider in sync.
@ -121,21 +86,14 @@ $slider = {
}
```
<% modules::custom::slider::SliderWidget { depth = 3 } %>
#### Progress
A progress bar.
> Type: `progress`
Note that `value` expects a numeric value **between 0-`max`** as output.
| Name | Type | Default | Description |
|---------------|------------------------------------------------------------|--------------|---------------------------------------------------------------------------------|
| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `horizontal` | Orientation of the progress bar. |
| `value` | `Script` | `null` | Script to run to get the progress bar value. Output must be a valid percentage. |
| `max` | `float` | `100` | Maximum progress bar value. |
| `length` | `integer` | `null` | Slider length. GTK will automatically size if left unset. |
The example below shows progress for the current playing song in MPD,
and displays the elapsed/length timestamps as a label above:
@ -153,6 +111,8 @@ $progress = {
}
```
<% modules::custom::progress::ProgressWidget { depth = 3 } %>
### Label Attributes
> ℹ This is different to the `label` widget, although applies to it.

10
docs/modules/Focused.md
View File

@ -10,15 +10,7 @@ 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. |
<% modules::focused::FocusedModule %>
<details>
<summary>JSON</summary>

4
docs/modules/Label.md
View File

@ -7,9 +7,7 @@ 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. |
<% modules::label::LabelModule %>
<details>
<summary>JSON</summary>

9
docs/modules/Launcher.md
View File

@ -12,13 +12,8 @@ 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 |
<% modules::launcher::LauncherModule %>
<details>
<summary>JSON</summary>

26
docs/modules/Music.md
View File

@ -11,29 +11,11 @@ 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. |
<% modules::music::config::MusicModule %>
See [here](images) for information on images.
### Icons
<% modules::music::config::Icons { depth = 2 } %>
<details>
<summary>JSON</summary>

13
docs/modules/Notifications.md
View File

@ -11,16 +11,11 @@ Clicking the widget opens the SwayNC panel.
> Type: `notifications`
| Name | Type | Default | Description |
|---------------------|-----------|---------|--------------------------------------------------------------------------------------------------------|
| `show_count` | `boolean` | `true` | Whether to show the current notification count. |
| `icons.closed_none` | `string` | `󰍥` | Icon to show when the panel is closed, with no notifications. |
| `icons.closed_some` | `string` | `󱥂` | Icon to show when the panel is closed, with notifications. |
| `icons.closed_dnd` | `string` | `󱅯` | Icon to show when the panel is closed, with DnD enabled. Takes higher priority than count-based icons. |
| `icons.open_none` | `string` | `󰍡` | Icon to show when the panel is open, with no notifications. |
| `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. |
<% modules::notifications::NotificationsModule %>
### Icons
<% modules::notifications::Icons { depth = 2 } %>
<details>
<summary>JSON</summary>

6
docs/modules/Script.md
View File

@ -8,11 +8,7 @@ For more advanced use-cases, use [custom](custom).
> Type: `script`
| Name | Type | Default | Description |
|------------|-----------------------|---------|---------------------------------------------------------|
| `cmd` | `string` | `null` | Path to the script on disk |
| `mode` | `'poll'` or `'watch'` | `poll` | See [#modes](#modes) |
| `interval` | `number` | `5000` | Number of milliseconds to wait between executing script |
<% modules::script::ScriptModule %>
### Modes

17
docs/modules/Sys-Info.md
View File

@ -10,17 +10,12 @@ 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). |
<% modules::sysinfo::SysInfoModule %>
### Interval
<% modules::sysinfo::Intervals { depth = 2 } %>
<details>
<summary>JSON</summary>

6
docs/modules/Tray.md
View File

@ -6,11 +6,7 @@ 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. |
<% modules::tray::TrayModule %>
<details>
<summary>JSON</summary>

5
docs/modules/Upower.md
View File

@ -9,10 +9,7 @@ Displays system power information such as the battery percentage, and estimated
> Type: `upower`
| Name | Type | Default | Description |
|-------------|-----------|-----------------|---------------------------------------------------|
| `format` | `string` | `{percentage}%` | Format string to use for the widget button label. |
| `icon_size` | `integer` | `24` | Size to render icon at. |
<% modules::upower::UpowerModule %>
<details>
<summary>JSON</summary>

13
docs/modules/Volume.md
View File

@ -10,14 +10,11 @@ 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. |
<% modules::volume::VolumeModule %>
### Icons
<% modules::volume::Icons { depth = 2 } %>
<details>
<summary>JSON</summary>

9
docs/modules/Workspaces.md
View File

@ -8,14 +8,7 @@ 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. |
<% modules::workspaces::WorkspacesModule %>
<details>
<summary>JSON</summary>

133
src/config/common.rs
View File

@ -7,23 +7,150 @@ use gtk::{EventBox, Orientation, Revealer, RevealerTransitionType};
use serde::Deserialize;
use tracing::trace;
/// Common configuration options
/// which can be set on every module.
/// The following are module-level options which are present on **all** modules.
///
/// Each module also provides options specific to its type.
/// For details on those, check the relevant module documentation.
///
/// For information on the Script type, and embedding scripts in strings,
/// see [here](script).
/// For information on styling, please see the [styling guide](styling-guide).
#[derive(Debug, Default, Deserialize, Clone)]
pub struct CommonConfig {
pub class: Option<String>,
/// 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.
///
/// **Default**: `null`
pub name: Option<String>,
/// Sets one or more CSS classes,
/// allowing you to target it in CSS using `.class`.
///
/// Unlike [name](#name), the `class` property is not expected to be unique.
///
/// **Default**: `null`
pub class: Option<String>,
/// Shows this text on hover.
/// Supports embedding scripts between `{{double braces}}`.
///
/// Note that full dynamic string support is not currently supported.
///
/// **Default**: `null`
pub tooltip: Option<String>,
/// 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**: `null`
pub show_if: Option<DynamicBool>,
/// The transition animation to use when showing/hiding the widget.
///
/// Note this has no effect if `show_if` is not configured.
///
/// **Valid options**: `slide_start`, `slide_end`, `crossfade`, `none`
/// <br>
/// **Default**: `slide_start`
pub transition_type: Option<TransitionType>,
/// 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.
///
/// **Default**: `250`
pub transition_duration: Option<u32>,
/// A [script](scripts) to run when the module is left-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
///
/// # Example
///
/// ```corn
/// { on_click_left = "echo 'event' >> log.txt" }
/// ```
pub on_click_left: Option<ScriptInput>,
/// A [script](scripts) to run when the module is right-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// /// # Example
///
/// ```corn
/// { on_click_right = "echo 'event' >> log.txt" }
/// ```
pub on_click_right: Option<ScriptInput>,
/// A [script](scripts) to run when the module is middle-clicked.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_click_middle = "echo 'event' >> log.txt" }
/// ```
pub on_click_middle: Option<ScriptInput>,
/// A [script](scripts) to run when the module is scrolled up on.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_scroll_up = "echo 'event' >> log.txt" }
/// ```
pub on_scroll_up: Option<ScriptInput>,
/// A [script](scripts) to run when the module is scrolled down on.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_scroll_down = "echo 'event' >> log.txt" }
/// ```
pub on_scroll_down: Option<ScriptInput>,
/// A [script](scripts) to run when the cursor begins hovering over the module.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_mouse_enter = "echo 'event' >> log.txt" }
/// ```
pub on_mouse_enter: Option<ScriptInput>,
/// A [script](scripts) to run when the cursor stops hovering over the module.
///
/// **Supported script types**: `oneshot`.
/// <br>
/// **Default**: `null`
/// # Example
///
/// ```corn
/// { on_mouse_exit = "echo 'event' >> log.txt" }
/// ```
pub on_mouse_exit: Option<ScriptInput>,
pub tooltip: Option<String>,

133
src/config/mod.rs
View File

@ -155,32 +155,143 @@ pub struct MarginConfig {
pub top: i32,
}
/// The following is a list of all top-level bar config options.
///
/// These options can either be written at the very top object of your config,
/// or within an object in the [monitors](#monitors) config,
/// depending on your [use-case](#2-pick-your-use-case).
///
#[derive(Debug, Deserialize, Clone)]
pub struct BarConfig {
#[serde(default)]
pub position: BarPosition,
#[serde(default = "default_true")]
pub anchor_to_edges: bool,
#[serde(default = "default_bar_height")]
pub height: i32,
#[serde(default)]
pub margin: MarginConfig,
/// A unique identifier for the bar, used for controlling it over IPC.
/// If not set, uses a generated integer suffix.
///
/// **Default**: `bar-n`
pub name: Option<String>,
/// The bar's position on screen.
///
/// **Valid options**: `top`, `bottom`, `left`, `right`
/// <br>
/// **Default**: `bottom`
#[serde(default)]
pub position: BarPosition,
/// Whether to anchor the bar to the edges of the screen.
/// Setting to false centers the bar.
///
/// **Default**: `true`
#[serde(default = "default_true")]
pub anchor_to_edges: bool,
/// The bar's height in pixels.
///
/// Note that GTK treats this as a target minimum,
/// and if content inside the bar is over this,
/// it will automatically expand to fit.
///
/// **Default**: `42`
#[serde(default = "default_bar_height")]
pub height: i32,
/// The margin to use on each side of the bar, in pixels.
/// Object which takes `top`, `bottom`, `left` and `right` keys.
///
/// **Default**: `0` on all sides.
///
/// # Example
///
/// The following would set a 10px margin around each edge.
///
/// ```corn
/// {
/// margin.top = 10
/// margin.bottom = 10
/// margin.left = 10
/// margin.right = 10
/// }
/// ```
#[serde(default)]
pub margin: MarginConfig,
#[serde(default = "default_popup_gap")]
/// The size of the gap in pixels
/// between the bar and the popup window.
///
/// **Default**: `5`
pub popup_gap: i32,
/// Whether the bar should be hidden when Ironbar starts.
///
/// **Default**: `false`, unless `autohide` is set.
#[serde(default)]
pub start_hidden: Option<bool>,
/// The duration in milliseconds before the bar is hidden after the cursor leaves.
/// Leave unset to disable auto-hide behaviour.
///
/// **Default**: `null`
#[serde(default)]
pub autohide: Option<u64>,
/// GTK icon theme to use.
/// The name of the GTK icon theme to use.
/// Leave unset to use the default Adwaita theme.
///
/// **Default**: `null`
pub icon_theme: Option<String>,
/// A map of [ironvar](ironvar) keys and values
/// to initialize Ironbar with on startup.
///
/// **Default**: `{}`
///
/// # Example
///
/// The following initializes an ironvar called `foo` set to `bar` on startup:
///
/// ```corn
/// { ironvar_defaults.foo = "bar" }
/// ```
///
/// The variable can then be immediately fetched without needing to be manually set:
///
/// ```sh
/// $ ironbar get foo
/// ok
/// bar
/// ```
pub ironvar_defaults: Option<HashMap<Box<str>, String>>,
/// An array of modules to append to the start of the bar.
/// Depending on the orientation, this is either the top of the left edge.
///
/// **Default**: `[]`
pub start: Option<Vec<ModuleConfig>>,
/// An array of modules to append to the center of the bar.
///
/// **Default**: `[]`
pub center: Option<Vec<ModuleConfig>>,
/// An array of modules to append to the end of the bar.
/// Depending on the orientation, this is either the bottom or right edge.
///
/// **Default**: `[]`
pub end: Option<Vec<ModuleConfig>>,
#[serde(default = "default_popup_gap")]
pub popup_gap: i32,
/// A map of monitor names to configs.
///
/// The config values can be either:
///
/// - a single object, which denotes a single bar for that monitor,
/// - an array of multiple objects, which denotes multiple for that monitor.
///
/// Each object is one of [Config](#config).
///
/// > [!NOTE]
/// > This option can only be set at the top-level.
/// > Setting this within a bar config has no effect.
pub monitors: Option<HashMap<String, MonitorConfig>>,
}
impl Default for BarConfig {

55
src/config/truncate.rs
View File

@ -20,13 +20,68 @@ impl From<EllipsizeMode> for GtkEllipsizeMode {
}
}
/// Some modules provide options for truncating text.
/// This is controlled using a common `TruncateMode` type,
/// which is defined below.
///
/// The option can be configured in one of two modes.
///
#[derive(Debug, Deserialize, Clone, Copy)]
#[serde(untagged)]
pub enum TruncateMode {
/// Auto mode lets GTK decide when to ellipsize.
///
/// To use this mode, set the truncate option to a string
/// declaring the location to truncate text from and place the ellipsis.
///
/// # Example
///
/// ```corn
/// { truncate = "start" }
/// ```
///
/// **Valid options**: `start`, `middle`, `end`
/// <br>
/// **Default**: `null`
Auto(EllipsizeMode),
/// Length mode defines a fixed point at which to ellipsize.
///
/// Generally you will want to set only one of `length` or `max_length`,
/// but you can set both if required.
///
/// # Example
///
/// ```corn
/// {
/// truncate.mode = "start"
/// truncate.length = 50
/// truncate.max_length = 70
/// }
/// ```
Length {
/// The location to truncate text from and place the ellipsis.
/// **Valid options**: `start`, `middle`, `end`
/// <br>
/// **Default**: `null`
mode: EllipsizeMode,
/// The fixed width (in characters) of the widget.
///
/// The widget will be expanded to this width
/// if it would have otherwise been smaller.
///
/// Leave unset to let GTK automatically handle.
///
/// **Default**: `null`
length: Option<i32>,
/// The maximum number of characters to show
/// before truncating.
///
/// Leave unset to let GTK automatically handle.
///
/// **Default**: `null`
max_length: Option<i32>,
},
}

15
src/modules/cairo.rs
View File

@ -19,16 +19,31 @@ use tracing::{debug, error};
#[derive(Debug, Clone, Deserialize)]
pub struct CairoModule {
/// 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.
path: PathBuf,
/// The number of milliseconds between each draw call.
///
/// **Default**: `200`
#[serde(default = "default_frequency")]
frequency: u64,
/// The canvas width in pixels.
///
/// **Default**: `42`
#[serde(default = "default_size")]
width: u32,
/// The canvas height in pixels.
///
/// **Default**: `42`
#[serde(default = "default_size")]
height: u32,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

14
src/modules/clipboard.rs
View File

@ -18,18 +18,32 @@ use tracing::{debug, error};
#[derive(Debug, Deserialize, Clone)]
pub struct ClipboardModule {
/// The icon to show on the bar widget button.
/// Supports [image](images) icons.
///
/// **Default**: `󰨸`
#[serde(default = "default_icon")]
icon: String,
/// The size to render the icon at.
/// Note this only applies to image-type icons.
///
/// **Default**: `32`
#[serde(default = "default_icon_size")]
icon_size: i32,
/// The maximum number of items to keep in the history,
/// and to show in the popup.
///
/// **Default**: `10`
#[serde(default = "default_max_items")]
max_items: usize,
// -- Common --
/// See [truncate options](module-level-options#truncate-mode).
truncate: Option<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

28
src/modules/clock.rs
View File

@ -17,23 +17,47 @@ use crate::{glib_recv, module_impl, send_async, spawn, try_send};
#[derive(Debug, Deserialize, Clone)]
pub struct ClockModule {
/// Date/time format string.
/// Default: `%d/%m/%Y %H:%M`
/// The format string to use for the date/time shown on the bar.
/// Pango markup is supported.
///
/// Detail on available tokens can be found here:
/// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
///
/// **Default**: `%d/%m/%Y %H:%M`
#[serde(default = "default_format")]
format: String,
/// The format string to use for the date/time shown in the popup header.
/// Pango markup is supported.
///
/// Detail on available tokens can be found here:
/// <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
///
/// **Default**: `%H:%M:%S`
#[serde(default = "default_popup_format")]
format_popup: String,
/// The locale to use when formatting dates.
///
/// Note this will not control the calendar -
/// for that you must set `LC_TIME`.
///
/// **Valid options**: See [here](https://docs.rs/pure-rust-locales/0.8.1/pure_rust_locales/enum.Locale.html#variants)
/// <br>
/// **Default**: `$LC_TIME` or `$LANG` or `'POSIX'`
#[serde(default = "default_locale")]
locale: String,
/// The orientation to display the widget contents.
/// Setting to vertical will rotate text 90 degrees.
///
/// **Valid options**: `horizontal`, `vertical`
/// <br>
/// **Default**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

8
src/modules/custom/box.rs
View File

@ -7,9 +7,17 @@ use serde::Deserialize;
#[derive(Debug, Deserialize, Clone)]
pub struct BoxWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Whether child widgets should be horizontally or vertically added.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default option**: `horizontal`
orientation: Option<ModuleOrientation>,
/// Modules and widgets to add to this box.
widgets: Option<Vec<WidgetConfig>>,
}

22
src/modules/custom/button.rs
View File

@ -11,13 +11,33 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent, WidgetConfig};
#[derive(Debug, Deserialize, Clone)]
pub struct ButtonWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Widget text label. Pango markup and embedded scripts are supported.
///
/// This is a shorthand for adding a label widget to the button.
/// Ignored if `widgets` is set.
///
/// This is a [Dynamic String](dynamic-values#dynamic-string).
label: Option<String>,
/// Command to execute. More on this [below](#commands).
on_click: Option<String>,
widgets: Option<Vec<WidgetConfig>>,
/// Orientation of the button.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default option**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// Modules and widgets to add to this box.
widgets: Option<Vec<WidgetConfig>>,
}
impl CustomWidget for ButtonWidget {

12
src/modules/custom/image.rs
View File

@ -10,9 +10,21 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct ImageWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Image source.
///
/// This is an [image](image) via [Dynamic String](dynamic-values#dynamic-string).
src: String,
/// The width/height of the image.
/// Aspect ratio is preserved.
///
/// **Default**: `32`
#[serde(default = "default_size")]
size: i32,
}

15
src/modules/custom/label.rs
View File

@ -10,9 +10,23 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct LabelWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Widget text label. Pango markup and embedded scripts are supported.
///
/// This is a [Dynamic String](dynamic-values#dynamic-string).
label: String,
/// Orientation of the label.
/// Setting to vertical will rotate text 90 degrees.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default option**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
}
@ -24,7 +38,6 @@ impl CustomWidget for LabelWidget {
let label = build!(self, Self::Widget);
label.set_angle(self.orientation.to_angle());
label.set_use_markup(true);
{

11
src/modules/custom/mod.rs
View File

@ -29,11 +29,12 @@ use tracing::{debug, error};
#[derive(Debug, Deserialize, Clone)]
pub struct CustomModule {
/// Widgets to add to the bar container
/// Modules and widgets to add to the bar container.
bar: Vec<WidgetConfig>,
/// Widgets to add to the popup container
/// Modules and widgets to add to the popup container.
popup: Option<Vec<WidgetConfig>>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
@ -56,11 +57,17 @@ pub enum WidgetOrModule {
#[derive(Debug, Deserialize, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Widget {
/// A container to place nested widgets inside.
Box(BoxWidget),
/// A text label. Pango markup is supported.
Label(LabelWidget),
/// A clickable button, which can run a command when clicked.
Button(ButtonWidget),
/// An image or icon from disk or http.
Image(ImageWidget),
/// A draggable slider.
Slider(SliderWidget),
/// A progress bar.
Progress(ProgressWidget),
}

24
src/modules/custom/progress.rs
View File

@ -14,14 +14,38 @@ use super::{CustomWidget, CustomWidgetContext};
#[derive(Debug, Deserialize, Clone)]
pub struct ProgressWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Orientation of the progress bar.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default option**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// Text label to show for the progress bar.
///
/// This is a [Dynamic String](dynamic-values#dynamic-string).
label: Option<String>,
/// Script to run to get the progress bar value.
/// Output must be a valid percentage.
///
/// Note that this expects a numeric value between `0`-`max` as output.
value: Option<ScriptInput>,
/// The maximum progress bar value.
///
/// **Default**: `100`
#[serde(default = "default_max")]
max: f64,
/// The progress bar length, in pixels.
/// GTK will automatically determine the size if left blank.
length: Option<i32>,
}

37
src/modules/custom/slider.rs
View File

@ -17,18 +17,55 @@ use super::{CustomWidget, CustomWidgetContext, ExecEvent};
#[derive(Debug, Deserialize, Clone)]
pub struct SliderWidget {
/// Widget name.
name: Option<String>,
/// Widget class name.
class: Option<String>,
/// Orientation of the slider.
///
/// **Valid options**: `horizontal`, `vertical`, `h`, `v`
/// <br />
/// **Default option**: `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// Script to run to get the slider value.
/// Output must be a valid number.
value: Option<ScriptInput>,
/// Command to execute when the slider changes.
/// More on this [below](#slider).
///
/// Note that this will provide the floating point value as an argument.
/// If your input program requires an integer, you will need to round it.
on_change: Option<String>,
/// Minimum slider value.
///
/// **Default**: `0`
#[serde(default = "default_min")]
min: f64,
/// Maximum slider value.
///
/// **Default**: `100`
#[serde(default = "default_max")]
max: f64,
/// If the increment to change when scrolling with the mousewheel.
/// If left blank, GTK will use the default value,
/// determined by the current environment.
step: Option<f64>,
/// The slider length.
/// GTK will automatically determine the size if left blank.
length: Option<i32>,
/// Whether to show the value label above the slider.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
show_label: bool,
}

3
src/modules/focused.rs
View File

@ -24,8 +24,11 @@ pub struct FocusedModule {
#[serde(default = "default_icon_size")]
icon_size: i32,
// -- common --
/// See [truncate options](module-level-options#truncate-mode).
truncate: Option<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

3
src/modules/label.rs
View File

@ -10,8 +10,11 @@ use tokio::sync::mpsc;
#[derive(Debug, Deserialize, Clone)]
pub struct LabelModule {
/// The text to show on the label.
/// This is a [Dynamic String](dynamic-values#dynamic-string).
label: String,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

16
src/modules/launcher/mod.rs
View File

@ -23,19 +23,35 @@ pub struct LauncherModule {
/// List of app IDs (or classes) to always show regardless of open state,
/// in the order specified.
favorites: Option<Vec<String>>,
/// Whether to show application names on the bar.
///
/// **Default**: `false`
#[serde(default = "crate::config::default_false")]
show_names: bool,
/// Whether to show application icons on the bar.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
show_icons: bool,
/// Size in pixels to render icon at (image icons only).
///
/// **Default**: `32`
#[serde(default = "default_icon_size")]
icon_size: i32,
/// Whether items should be added from right-to-left
/// instead of left-to-right.
///
/// This includes favourites.
///
/// **Default**: `false`
#[serde(default = "crate::config::default_false")]
reversed: bool,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

51
src/modules/music/config.rs
View File

@ -21,19 +21,19 @@ pub struct Icons {
#[serde(default = "default_icon_next")]
pub(crate) next: String,
/// Icon to display under volume slider
/// Icon to display under volume slider.
#[serde(default = "default_icon_volume")]
pub(crate) volume: String,
/// Icon to display nex to track title
/// Icon to display nex to track title.
#[serde(default = "default_icon_track")]
pub(crate) track: String,
/// Icon to display nex to album name
/// Icon to display nex to album name.
#[serde(default = "default_icon_album")]
pub(crate) album: String,
/// Icon to display nex to artist name
/// Icon to display nex to artist name.
#[serde(default = "default_icon_artist")]
pub(crate) artist: String,
}
@ -73,33 +73,58 @@ pub struct MusicModule {
pub(crate) player_type: PlayerType,
/// Format of current song info to display on the bar.
///
/// Info on formatting tokens [below](#formatting-tokens).
///
/// **Default**: `{title} / {artist}`
#[serde(default = "default_format")]
pub(crate) format: String,
/// Player state icons
/// Player state icons.
#[serde(default)]
pub(crate) icons: Icons,
// -- MPD --
/// TCP or Unix socket address.
#[serde(default = "default_socket")]
pub(crate) host: String,
/// Path to root of music directory.
#[serde(default = "default_music_dir")]
pub(crate) music_dir: PathBuf,
/// Whether to show the play/pause status icon
/// on the bar.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
pub(crate) show_status_icon: bool,
/// Size to render the icons at, in pixels (image icons only).
///
/// **Default** `32`
#[serde(default = "default_icon_size")]
pub(crate) icon_size: i32,
/// Size to render the album art image at inside the popup, in pixels.
///
/// **Default**: `128`
#[serde(default = "default_cover_image_size")]
pub(crate) cover_image_size: i32,
// -- MPD --
/// *[MPD Only]*
/// TCP or Unix socket address of the MPD server.
/// For TCP, this should include the port number.
///
/// **Default**: `localhost:6600`
#[serde(default = "default_socket")]
pub(crate) host: String,
/// *[MPD Only]*
/// Path to root of the MPD server's music directory.
/// This is required for displaying album art.
///
/// **Default**: `$HOME/Music`
#[serde(default = "default_music_dir")]
pub(crate) music_dir: PathBuf,
// -- Common --
/// See [truncate options](module-level-options#truncate-mode).
pub(crate) truncate: Option<TruncateMode>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

30
src/modules/notifications.rs
View File

@ -11,28 +11,58 @@ use tracing::error;
#[derive(Debug, Deserialize, Clone)]
pub struct NotificationsModule {
/// Whether to show the current notification count.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
show_count: bool,
/// SwayNC state icons.
#[serde(default)]
icons: Icons,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
#[derive(Debug, Deserialize, Clone)]
struct Icons {
/// Icon to show when the panel is closed, with no notifications.
///
/// **Default**: `󰍥`
#[serde(default = "default_icon_closed_none")]
closed_none: String,
/// Icon to show when the panel is closed, with notifications.
///
/// **Default**: `󱥂`
#[serde(default = "default_icon_closed_some")]
closed_some: String,
/// Icon to show when the panel is closed, with DnD enabled.
/// Takes higher priority than count-based icons.
///
/// **Default**: `󱅯`
#[serde(default = "default_icon_closed_dnd")]
closed_dnd: String,
/// Icon to show when the panel is open, with no notifications.
///
/// **Default**: `󰍡`
#[serde(default = "default_icon_open_none")]
open_none: String,
/// Icon to show when the panel is open, with notifications.
///
/// **Default**: `󱥁`
#[serde(default = "default_icon_open_some")]
open_some: String,
/// Icon to show when the panel is open, with DnD enabled.
/// Takes higher priority than count-based icons.
///
/// **Default**: `󱅮`
#[serde(default = "default_icon_open_dnd")]
open_dnd: String,
}

15
src/modules/script.rs
View File

@ -12,14 +12,27 @@ use tracing::error;
#[derive(Debug, Deserialize, Clone)]
pub struct ScriptModule {
/// Path to script to execute.
///
/// This can be an absolute path,
/// or relative to the working directory.
cmd: String,
/// Script execution mode
/// Script execution mode.
/// See [modes](#modes) for more info.
///
/// **Valid options**: `poll`, `watch`
/// <br />
/// **Default**: `poll`
#[serde(default = "default_mode")]
mode: ScriptMode,
/// Time in milliseconds between executions.
///
/// **Default**: `5000`
#[serde(default = "default_interval")]
interval: u64,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

45
src/modules/sysinfo.rs
View File

@ -15,33 +15,74 @@ use tokio::time::sleep;
#[derive(Debug, Deserialize, Clone)]
pub struct SysInfoModule {
/// List of formatting strings.
/// List of strings including formatting tokens.
/// For available tokens, see [below](#formatting-tokens).
format: Vec<String>,
/// Number of seconds between refresh
/// Number of seconds between refresh.
///
/// This can be set as a global interval,
/// or passed as an object to customize the interval per-system.
///
/// **Default**: `5`
#[serde(default = "Interval::default")]
interval: Interval,
/// The orientation of text for the labels.
///
/// **Valid options**: `horizontal`, `vertical, `h`, `v`
/// <br>
/// **Default** : `horizontal`
#[serde(default)]
orientation: ModuleOrientation,
/// The orientation by which the labels are laid out.
///
/// **Valid options**: `horizontal`, `vertical, `h`, `v`
/// <br>
/// **Default** : `horizontal`
direction: Option<ModuleOrientation>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
#[derive(Debug, Deserialize, Copy, Clone)]
pub struct Intervals {
/// The number of seconds between refreshing memory data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
memory: u64,
/// The number of seconds between refreshing CPU data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
cpu: u64,
/// The number of seconds between refreshing temperature data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
temps: u64,
/// The number of seconds between refreshing disk data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
disks: u64,
/// The number of seconds between refreshing network data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
networks: u64,
/// The number of seconds between refreshing system data.
///
/// **Default**: `5`
#[serde(default = "default_interval")]
system: u64,
}

13
src/modules/tray/mod.rs
View File

@ -20,15 +20,28 @@ use tracing::{debug, error, warn};
#[derive(Debug, Deserialize, Clone)]
pub struct TrayModule {
/// 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.
///
/// **Default**: `true`
#[serde(default = "crate::config::default_true")]
prefer_theme_icons: bool,
/// Size in pixels to display the tray icons as.
///
/// **Default**: `16`
#[serde(default = "default_icon_size")]
icon_size: u32,
/// Direction to display the tray items.
///
/// **Valid options**: `top_to_bottom`, `bottom_to_top`, `left_to_right`, `right_to_left`
/// <br>
/// **Default**: `left_to_right` if bar is horizontal, `top_to_bottom` if bar is vertical
#[serde(default, deserialize_with = "deserialize_orientation")]
direction: Option<PackDirection>,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

8
src/modules/upower.rs
View File

@ -23,12 +23,20 @@ const MINUTE: i64 = 60;
#[derive(Debug, Deserialize, Clone)]
pub struct UpowerModule {
/// The format string to use for the widget button label.
/// For available tokens, see [below](#formatting-tokens).
///
/// **Default**: `{percentage}%`
#[serde(default = "default_format")]
format: String,
/// The size to render the icon at, in pixels.
///
/// **Default**: `24`
#[serde(default = "default_icon_size")]
icon_size: i32,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}

25
src/modules/volume.rs
View File

@ -15,15 +15,25 @@ use tokio::sync::mpsc;
#[derive(Debug, Clone, Deserialize)]
pub struct VolumeModule {
/// The format string to use for the widget button label.
/// For available tokens, see [below](#formatting-tokens).
///
/// **Default**: `{icon} {percentage}%`
#[serde(default = "default_format")]
format: String,
/// Maximum value to allow volume sliders to reach.
/// Pulse supports values > 100 but this may result in distortion.
///
/// **Default**: `100`
#[serde(default = "default_max_volume")]
max_volume: f64,
/// Volume state icons.
#[serde(default)]
icons: Icons,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}
@ -34,12 +44,27 @@ fn default_format() -> String {
#[derive(Debug, Clone, Deserialize)]
pub struct Icons {
/// Icon to show for high volume levels.
///
/// **Default**: `󰕾`
#[serde(default = "default_icon_volume_high")]
volume_high: String,
/// Icon to show for medium volume levels.
///
/// **Default**: `󰖀`
#[serde(default = "default_icon_volume_medium")]
volume_medium: String,
/// Icon to show for low volume levels.
///
/// **Default**: `󰕿`
#[serde(default = "default_icon_volume_low")]
volume_low: String,
/// Icon to show for muted outputs.
///
/// **Default**: `󰝟`
#[serde(default = "default_icon_muted")]
muted: String,
}

45
src/modules/workspaces.rs
View File

@ -45,26 +45,65 @@ impl Default for Favorites {
#[derive(Debug, Deserialize, Clone)]
pub struct WorkspacesModule {
/// Map of actual workspace names to custom names.
///
/// Custom names can be [images](images).
///
/// If a workspace is not present in the map,
/// it will fall back to using its actual name.
name_map: Option<HashMap<String, String>>,
/// Array of always shown workspaces, and what monitor to show on
/// Workspaces which should always be shown.
/// This can either be an array of workspace names,
/// or a map of monitor names to arrays of workspace names.
///
/// # Example
///
/// ```corn
/// // array format
/// {
/// type = "workspaces"
/// favorites = ["1", "2", "3"]
/// }
///
/// // map format
/// {
/// type = "workspaces"
/// favorites.DP-1 = ["1", "2", "3"]
/// favorites.DP-2 = ["4", "5", "6"]
/// }
/// ```
#[serde(default)]
favorites: Favorites,
/// List of workspace names to never show
/// A list of workspace names to never show.
///
/// This may be useful for scratchpad/special workspaces, for example.
#[serde(default)]
hidden: Vec<String>,
/// Whether to display buttons for all monitors.
/// Whether to display workspaces from all monitors.
/// When false, only shows workspaces on the current monitor.
///
/// **Default**: `false`
#[serde(default = "crate::config::default_false")]
all_monitors: bool,
/// The method used for sorting workspaces.
/// `added` always appends to the end, `alphanumeric` sorts by number/name.
///
/// **Valid options**: `added`, `alphanumeric`
/// <br>
/// **Default**: `alphanumeric`
#[serde(default)]
sort: SortOrder,
/// The size to render icons at (image icons only).
///
/// **Default**: `32`
#[serde(default = "default_icon_size")]
icon_size: i32,
/// See [common options](module-level-options#common-options).
#[serde(flatten)]
pub common: Option<CommonConfig>,
}