zedfrigg/ironbar
1
0
Fork 0
mirror of https://github.com/Zedfrigg/ironbar.git synced 2025-07-01 10:41:03 +02:00
Code Activity

docs: migrate wiki into main repo

Browse source
This commit is contained in:
Jake Stanger 2022-11-06 22:52:21 +00:00
parent 1c032ae8e3
commit 58d55db660
No known key found for this signature in database
GPG key ID: C51FC8F9CB0BEA61
16 changed files with 1727 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

77
docs/modules/Clock.md Normal file
View file

@ -0,0 +1,77 @@
Displays the current date and time.
Clicking on the widget opens a popup with the time and a calendar.
![Screenshot of clock widget with popup open](https://user-images.githubusercontent.com/5057870/184540521-2278bdec-9742-46f0-9ac2-58a7b6f6ea1d.png)
## Configuration
> Type: `clock`
| Name | Type | Default | Description |
|----------|--------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `format` | `string` | `%d/%m/%Y %H:%M` | Date/time format string. Detail on available tokens can be found here: <https://docs.rs/chrono/latest/chrono/format/strftime/index.html> |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "clock",
"format": "%d/%m/%Y %H:%M"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "clock"
format = "%d/%m/%Y %H:%M"
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "clock"
format: "%d/%m/%Y %H:%M"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "clock"
format = "%d/%m/%Y %H:%M"
}
]
}
```
</details>
## Styling
| Selector | Description |
|-------------------------------|------------------------------------------------------------------------------------|
| `#clock` | Clock widget button |
| `#popup-clock` | Clock popup box |
| `#popup-clock #calendar-clock` | Clock inside the popup |
| `#popup-clock #calendar` | Calendar widget inside the popup. GTK provides some OOTB styling options for this. |

237
docs/modules/Custom.md Normal file
View file

@ -0,0 +1,237 @@
Allows you to compose custom modules consisting of multiple widgets, including popups.
Buttons can interact with the bar or execute commands on click.
![Custom module with a button on the bar, and the popup open. The popup contains a header, shutdown button and restart button.](https://user-images.githubusercontent.com/5057870/196058785-042ef171-7e77-4d5c-921a-eca03c6424bd.png)
## Configuration
> Type: `custom`
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 |
|---------|------------|---------|--------------------------------------|
| `class` | `string` | `null` | Container class name. |
| `bar` | `Widget[]` | `null` | List of widgets to add to the bar. |
| `popup` | `Widget[]` | `[]` | List of widgets to add to the popup. |
### `Widget`
| Name | Type | Default | Description |
|---------------|------------------------------|--------------|---------------------------------------------------------------------------|
| `widget_type` | `box` or `label` or `button` | `null` | Type of GTK widget to create. |
| `name` | `string` | `null` | Widget name. |
| `class` | `string` | `null` | Widget class name. |
| `label` | `string` | `null` | [`label` and `button`] Widget text label. Pango markup supported. |
| `exec` | `string` | `null` | [`button`] Command to execute. More on this [below](#commands). |
| `orientation` | `horizontal` or `vertical` | `horizontal` | [`box`] Whether child widgets should be horizontally or vertically added. |
| `widgets` | `Widget[]` | `[]` | [`box`] List of widgets to add to this box. |
### Commands
Buttons can execute commands that interact with the bar,
as well as any arbitrary shell command.
To execute shell commands, prefix them with an `!`.
For example, if you want to run `~/.local/bin/my-script.sh` on click,
you'd set `exec` to `!~/.local/bin/my-script.sh`.
The following bar commands are supported:
- `popup:toggle`
- `popup:open`
- `popup:close`
XML is arguably better-suited and easier to read for this sort of markup,
but currently not supported.
Nonetheless, it may be worth comparing the examples to the below equivalent
to help get your head around what's going on:
```xml
<?xml version="1.0" encoding="utf-8" ?>
<custom class="power-menu">
<bar>
<button name="power-btn" label="" exec="popup:toggle"/>
</bar>
<popup>
<box orientation="vertical">
<label name="header" label="Power menu" />
<box>
<button class="power-btn" label="" exec="!shutdown now" />
<button class="power-btn" label="" exec="!reboot" />
</box>
</box>
</popup>
</custom>
```
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "custom",
"bar": [
{
"exec": "popup:toggle",
"label": "",
"name": "power-btn",
"type": "button"
}
],
"class": "power-menu",
"popup": [
{
"orientation": "vertical",
"type": "box",
"widgets": [
{
"label": "Power menu",
"name": "header",
"type": "label"
},
{
"type": "box",
"widgets": [
{
"class": "power-btn",
"exec": "!shutdown now",
"label": "<span font-size='40pt'></span>",
"type": "button"
},
{
"class": "power-btn",
"exec": "!reboot",
"label": "<span font-size='40pt'></span>",
"type": "button"
}
]
}
]
}
]
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
class = 'power-menu'
type = 'custom'
[[end.bar]]
exec = 'popup:toggle'
label = ''
name = 'power-btn'
type = 'button'
[[end.popup]]
orientation = 'vertical'
type = 'box'
[[end.popup.widgets]]
label = 'Power menu'
name = 'header'
type = 'label'
[[end.popup.widgets]]
type = 'box'
[[end.popup.widgets.widgets]]
class = 'power-btn'
exec = '!shutdown now'
label = '''<span font-size='40pt'></span>'''
type = 'button'
[[end.popup.widgets.widgets]]
class = 'power-btn'
exec = '!reboot'
label = '''<span font-size='40pt'></span>'''
type = 'button'
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: custom
bar:
- exec: popup:toggle
label: 
name: power-btn
type: button
class: power-menu
popup:
- orientation: vertical
type: box
widgets:
- label: Power menu
name: header
type: label
- type: box
widgets:
- class: power-btn
exec: '!shutdown now'
label: <span font-size='40pt'></span>
type: button
- class: power-btn
exec: '!reboot'
label: <span font-size='40pt'></span>
type: button
```
</details>
<details>
<summary>Corn</summary>
```corn
let {
$power_menu = {
type = "custom"
class = "power-menu"
bar = [ { type = "button" name="power-btn" label = "" exec = "popup:toggle" } ]
popup = [ {
type = "box"
orientation = "vertical"
widgets = [
{ type = "label" name = "header" label = "Power menu" }
{
type = "box"
widgets = [
{ type = "button" class="power-btn" label = "<span font-size='40pt'></span>" exec = "!shutdown now" }
{ type = "button" class="power-btn" label = "<span font-size='40pt'></span>" exec = "!reboot" }
]
}
]
} ]
}
} in {
end = [ $power_menu ]
}
```
</details>
## Styling
Since the widgets are all custom, you can target them using `#name` and `.class`.
| Selector | Description |
|-----------|-------------------------|
| `#custom` | Custom widget container |

90
docs/modules/Focused.md Normal file
View file

@ -0,0 +1,90 @@
Displays the title and/or icon of the currently focused window.
![Screenshot of focused widget, showing this page open on firefox](https://user-images.githubusercontent.com/5057870/184714118-c1fb1c67-cd8c-4cc0-b5cd-6faccff818ac.png)
## Configuration
> 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 |
| `icon_theme` | `string` | `null` | GTK icon theme to use |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "focused",
"show_icon": true,
"show_title": true,
"icon_size": 32,
"icon_theme": "Paper"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "focused"
show_icon = true
show_title = true
icon_size = 32
icon_theme = "Paper"
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "focused"
show_icon: true
show_title: true
icon_size: 32
icon_theme: "Paper"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "focused"
show_icon = true
show_title = true
icon_size = 32
icon_theme = "Paper"
}
]
}
```
</details>
## Styling
| Selector | Description |
|--------------------------|--------------------|
| `#focused` | Focused widget box |
| `#focused #icon` | App icon |
| `#focused #label` | App name |

103
docs/modules/Launcher.md Normal file
View file

@ -0,0 +1,103 @@
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.
Optionally displays a launchable set of favourites.
![Screenshot showing several open applications, including a focused terminal.](https://user-images.githubusercontent.com/5057870/184540058-120e190e-2a45-4167-99c7-ed76482d1f16.png)
## Configuration
> 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_theme` | `string` | `null` | GTK icon theme to use. |
<details>
<summary>JSON</summary>
```json
{
"start": [
{
"type": "launcher",
"favourites": [
"firefox",
"discord"
],
"show_names": false,
"show_icons": true,
"icon_theme": "Paper"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[start]]
type = "launcher"
favorites = ["firefox", "discord"]
show_names = false
show_icons = true
icon_theme = "Paper"
```
</details>
<details>
<summary>YAML</summary>
```yaml
start:
- type: "launcher"
favorites:
- firefox
- discord
show_names: false
show_icons: true
icon_theme: "Paper"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
start = [
{
type = "launcher"
favorites = ["firefox" "discord"]
show_names = false
show_icons = true
icon_theme = "Paper"
}
]
}
```
</details>
## 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) |
| `#launcher-popup` | Popup container |
| `#launcher-popup .popup-item` | Window button in popup |

131
docs/modules/MPD.md Normal file
View file

@ -0,0 +1,131 @@
Displays currently playing song from MPD.
Clicking on the widget opens a popout displaying info about the current song, album art
and playback controls.
![Screenshot showing MPD widget with track playing with popout open](https://user-images.githubusercontent.com/5057870/184539664-a8f3ad5b-69c0-492d-a27d-82303c09a347.png)
## Configuration
> Type: `mpd`
| | Type | Default | Description |
|----------------|----------|-----------------------------|-----------------------------------------------------------------------|
| `host` | `string` | `localhost:6600` | TCP or Unix socket for the MPD server. |
| `format` | `string` | `{icon} {title} / {artist}` | Format string for the widget. More info below. |
| `icons.play` | `string` | `` | Icon to show when playing. |
| `icons.pause` | `string` | `` | Icon to show when paused. |
| `icons.volume` | `string` | `墳` | Icon to show under popup volume slider. |
| `music_dir` | `string` | `$HOME/Music` | Path to MPD server's music directory on disc. Required for album art. |
<details>
<summary>JSON</summary>
```json
{
"start": [
{
"type": "mpd",
"format": "{icon} {title} / {artist}",
"icons": {
"play": "",
"pause": ""
},
"music_dir": "/home/jake/Music"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[start]]
type = "mpd"
format = "{icon} {title} / {artist}"
music_dir = "/home/jake/Music"
[[start.icons]]
play = ""
pause = ""
```
</details>
<details>
<summary>YAML</summary>
```yaml
start:
- type: "mpd"
format: "{icon} {title} / {artist}"
icons:
play: ""
pause: ""
music_dir: "/home/jake/Music"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
start = [
{
type = "mpd"
format = "{icon} {title} / {artist}"
icons.play = ""
icons.pause = ""
music_dir = "/home/jake/Music"
}
]
}
```
</details>
### Formatting Tokens
The following tokens can be used in the `format` config option,
and will be replaced with values from the currently playing track:
| Token | Description |
|--------------|--------------------------------------|
| `{icon}` | Either `icons.play` or `icons.pause` |
| `{title}` | Title |
| `{album}` | Album name |
| `{artist}` | Artist name |
| `{date}` | Release date |
| `{track}` | Track number |
| `{disc}` | Disc number |
| `{genre}` | Genre |
| `{duration}` | Duration in `mm:ss` |
| `{elapsed}` | Time elapsed in `mm:ss` |
## Styling
| Selector | Description |
|----------------------------------------|------------------------------------------|
| `#mpd` | Tray widget button |
| `#popup-mpd` | Popup box |
| `#popup-mpd #album-art` | Album art image inside popup box |
| `#popup-mpd #title` | Track title container inside popup box |
| `#popup-mpd #title .icon` | Track title icon label inside popup box |
| `#popup-mpd #title .label` | Track title label inside popup box |
| `#popup-mpd #album` | Track album container inside popup box |
| `#popup-mpd #album .icon` | Track album icon label inside popup box |
| `#popup-mpd #album .label` | Track album label inside popup box |
| `#popup-mpd #artist` | Track artist container inside popup box |
| `#popup-mpd #artist .icon` | Track artist icon label inside popup box |
| `#popup-mpd #artist .label` | Track artist label inside popup box |
| `#popup-mpd #controls` | Controls container inside popup box |
| `#popup-mpd #controls #btn-prev` | Previous button inside popup box |
| `#popup-mpd #controls #btn-play-pause` | Play/pause button inside popup box |
| `#popup-mpd #controls #btn-next` | Next button inside popup box |
| `#popup-mpd #volume` | Volume container inside popup box |
| `#popup-mpd #volume #slider` | Volume slider popup box |
| `#popup-mpd #volume .icon` | Volume icon label inside popup box |

76
docs/modules/Script.md Normal file
View file

@ -0,0 +1,76 @@
Executes a script and shows the result of `stdout` on a label.
Pango markup is supported.
## Configuration
> Type: `script`
| Name | Type | Default | Description |
|-----------|----------|---------|---------------------------------------------------------|
| `path` | `string` | `null` | Path to the script on disk |
| `interval` | `number` | `5000` | Number of milliseconds to wait between executing script |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "script",
"path": "/home/jake/.local/bin/phone-battery",
"interval": 5000
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "script"
path = "/home/jake/.local/bin/phone-battery"
interval = 5000
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "script"
path: "/home/jake/.local/bin/phone-battery"
interval : 5000
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "script"
path = "/home/jake/.local/bin/phone-battery"
interval = 5000
}
]
}
```
</details>
## Styling
| Selector | Description |
|---------------|---------------------|
| `#script` | Script widget label |

64
docs/modules/Tray.md Normal file
View file

@ -0,0 +1,64 @@
Displays a fully interactive icon tray using the KDE `libappindicator` protocol.
![Screenshot showing icon tray widget](https://user-images.githubusercontent.com/5057870/184540135-78ffd79d-f802-4c79-b09a-05a733dadc55.png)
## Configuration
> Type: `tray`
***This module provides no configuration options.***
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "tray"
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "tray"
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "tray"
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{ type = "tray" }
]
}
```
</details>
## Styling
| Selector | Description |
|---------------|------------------|
| `#tray` | Tray widget box |
| `#tray .item` | Tray icon button |

94
docs/modules/Workspaces.md Normal file
View file

@ -0,0 +1,94 @@
> ⚠ **This module is currently only supported on Sway**
Shows all current Sway workspaces. Clicking a workspace changes focus to it.
![Screenshot showing workspaces widget using custom icons with browser workspace focused](https://user-images.githubusercontent.com/5057870/184540156-26cfe4ec-ab8d-4e0f-a883-8b641025366b.png)
## Configuration
> Type: `workspaces`
| Name | Type | Default | Description |
|----------------|-----------------------|---------|----------------------------------------------------------------------------------------------------------------------|
| `name_map` | `Map<string, string>` | `{}` | A map of actual workspace names to their display labels. Workspaces use their actual name if not present in the map. |
| `all_monitors` | `boolean` | `false` | Whether to display workspaces from all monitors. When `false`, only shows workspaces on the current monitor. |
<details>
<summary>JSON</summary>
```json
{
"end": [
{
"type": "workspaces",
"name_map": {
"1": "",
"2": "",
"3": ""
},
"all_monitors": false
}
]
}
```
</details>
<details>
<summary>TOML</summary>
```toml
[[end]]
type = "workspaces"
all_monitors = false
[[end.name_map]]
1 = ""
2 = ""
3 = ""
```
</details>
<details>
<summary>YAML</summary>
```yaml
end:
- type: "workspaces"
name_map:
1: ""
2: ""
3: ""
all_monitors: false
```
</details>
<details>
<summary>Corn</summary>
```corn
{
end = [
{
type = "workspaces",
name_map.1 = ""
name_map.2 = ""
name_map.3 = ""
all_monitors = false
}
]
}
```
</details>
## Styling
| Selector | Description |
|-----------------------------|--------------------------------------|
| `#workspaces` | Workspaces widget box |
| `#workspaces .item` | Workspace button |
| `#workspaces .item.focused` | Workspace button (workspace focused) |