From 607c7285d7e01265a8c8417e2941b2099e61aa42 Mon Sep 17 00:00:00 2001 From: Jake Stanger Date: Thu, 29 Jun 2023 16:13:15 +0100 Subject: [PATCH] docs: update for ipc/cli, tidy a bit --- docs/Compiling.md | 2 + docs/Configuration guide.md | 33 ++++----- docs/Controlling Ironbar.md | 136 ++++++++++++++++++++++++++++++++++++ docs/Dynamic values.md | 39 +++++++++++ docs/Ironvars.md | 9 +++ docs/_Sidebar.md | 10 ++- docs/modules/Clipboard.md | 20 +++--- docs/modules/Custom.md | 81 +++++++++++---------- docs/modules/Focused.md | 18 ++--- docs/modules/Label.md | 11 +-- docs/modules/Music.md | 42 +++++------ docs/modules/Script.md | 3 + docs/modules/Workspaces.md | 12 ++-- 13 files changed, 306 insertions(+), 110 deletions(-) create mode 100644 docs/Controlling Ironbar.md create mode 100644 docs/Dynamic values.md create mode 100644 docs/Ironvars.md diff --git a/docs/Compiling.md b/docs/Compiling.md index 10a79a7..19a8ab2 100644 --- a/docs/Compiling.md +++ b/docs/Compiling.md @@ -58,6 +58,8 @@ cargo build --release --no-default-features \ |---------------------|-----------------------------------------------------------------------------------| | **Core** | | | http | Enables HTTP features. Currently this includes the ability to load remote images. | +| ipc | Enables the IPC server. | +| cli | Enables the CLI. Will also enable `ipc`. | | config+all | Enables support for all configuration languages. | | config+json | Enables configuration support for JSON. | | config+yaml | Enables configuration support for YAML. | diff --git a/docs/Configuration guide.md b/docs/Configuration guide.md index a4e1684..1ebf69b 100644 --- a/docs/Configuration guide.md +++ b/docs/Configuration guide.md @@ -267,20 +267,21 @@ 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 | -|-------------------|----------------------------------------|----------|-----------------------------------------------------------------------------------------| -| `position` | `top` or `bottom` or `left` or `right` | `bottom` | The bar's position on screen. | -| `anchor_to_edges` | `boolean` | `false` | Whether to anchor the bar to the edges of the screen. Setting to false centres the bar. | -| `height` | `integer` | `42` | The bar's height in pixels. | -| `popup_gap` | `integer` | `5` | The gap between the bar and popup window. | -| `margin.top` | `integer` | `0` | The margin on the top of the bar | -| `margin.bottom` | `integer` | `0` | The margin on the bottom of the bar | -| `margin.left` | `integer` | `0` | The margin on the left of the bar | -| `margin.right` | `integer` | `0` | The margin on the right of the bar | -| `icon_theme` | `string` | `null` | Name of the GTK icon theme to use. Leave blank to use default. | -| `start` | `Module[]` | `[]` | Array of left or top modules. | -| `center` | `Module[]` | `[]` | Array of center modules. | -| `end` | `Module[]` | `[]` | Array of right or bottom modules. | +| Name | Type | Default | Description | +|--------------------|----------------------------------------|-----------|-----------------------------------------------------------------------------------------| +| `position` | `top` or `bottom` or `left` or `right` | `bottom` | The bar's position on screen. | +| `anchor_to_edges` | `boolean` | `false` | Whether to anchor the bar to the edges of the screen. Setting to false centres the bar. | +| `height` | `integer` | `42` | The bar's height in pixels. | +| `popup_gap` | `integer` | `5` | The gap between the bar and popup window. | +| `margin.top` | `integer` | `0` | The margin on the top of the bar | +| `margin.bottom` | `integer` | `0` | The margin on the bottom of the bar | +| `margin.left` | `integer` | `0` | The margin on the left of the bar | +| `margin.right` | `integer` | `0` | The margin on the right of the bar | +| `icon_theme` | `string` | `null` | Name of the GTK icon theme to use. Leave blank to use default. | +| `ironvar_defaults` | `Map` | `{}` | Map of [ironvar](ironvars) keys against their default values. | +| `start` | `Module[]` | `[]` | Array of left or top modules. | +| `center` | `Module[]` | `[]` | Array of center modules. | +| `end` | `Module[]` | `[]` | Array of right or bottom modules. | ### 3.2 Module-level options @@ -306,9 +307,9 @@ For information on the `Script` type, and embedding scripts in strings, see [her | Name | Type | Default | Description | |-----------------------|-------------------------------------------------------|---------------|--------------------------------------------------------------------------------------------------------------------| -| `show_if` | `Script [polling]` | `null` | Polls the script to check its exit code. If exit code is zero, the module is shown. For other codes, it is hidden. | +| `show_if` | [Dynamic Boolean](dynamic-values#dynamic-boolean) | `null` | Polls the script to check its exit code. If exit code is zero, the module is shown. For other codes, it is hidden. | | `transition_type` | `slide_start` or `slide_end` or `crossfade` or `none` | `slide_start` | The transition animation to use when showing/hiding the widget. | -| `transition_duration` | `Integer` | `250` | The length of the transition animation to use when showing/hiding the widget. | +| `transition_duration` | `integer` | `250` | The length of the transition animation to use when showing/hiding the widget. | #### Appearance diff --git a/docs/Controlling Ironbar.md b/docs/Controlling Ironbar.md new file mode 100644 index 0000000..2b97b37 --- /dev/null +++ b/docs/Controlling Ironbar.md @@ -0,0 +1,136 @@ +Ironbar includes a simple IPC server which can be used to control it programmatically at runtime. + +It also includes a command line interface, which can be used for interacting with the IPC server. + +# CLI + +This is shipped as part of the `ironbar` binary. To view commands, you can use `ironbar --help`. +You can also view help per-command, for example using `ironbar set --help`. + +Responses are handled by writing their type to stdout, followed by any value starting on the next line. +Error responses are written to stderr in the same format. + +Example: + +```shell +$ ironbar set subject world +ok + +$ ironbar get subject +ok +world +``` + +# IPC + +The server listens on a Unix socket. +This can usually be found at `/run/user/$UID/ironbar-ipc.sock`. + +Commands and responses are sent as JSON objects, denoted by their `type` key. + +The message buffer is currently limited to `1024` bytes. +Particularly large messages will be truncated or cause an error. + +## Commands + +### `ping` + +Sends a ping request to the IPC. + +Responds with `ok`. + +```json +{ + "type": "ping" +} +``` + +### `inspect` + +Opens the GTK inspector window. + +Responds with `ok`. + +```json +{ + "type": "inspect" +} +``` + +### `get` + +Gets an [ironvar](ironvars) value. + +Responds with `ok_value` if the value exists, otherwise `error`. + +```json +{ + "type": "get", + "key": "foo" +} +``` + +### `set` + +Sets an [ironvar](ironvars) value. + +Responds with `ok`. + +```json +{ + "type": "set", + "key": "foo", + "value": "bar" +} +``` + +### `load_css` + +### `get` + +Loads an additional CSS stylesheet, with hot-reloading enabled. + +Responds with `ok` if the stylesheet exists, otherwise `error`. + +```json +{ + "type": "load_css", + "path": "/path/to/style.css" +} +``` + +## Responses + +### `ok` + +The operation completed successfully, with no response data. + +```json +{ + "type": "ok" +} +``` + +### `ok_value` + +The operation completed successfully, with response data. + +```json +{ + "type": "ok_value", + "value": "lorem ipsum" +} +``` + +### `error` + +The operation failed. + +Message is optional. + +```json +{ + "type": "error", + "message": "lorem ipsum" +} +``` \ No newline at end of file diff --git a/docs/Dynamic values.md b/docs/Dynamic values.md new file mode 100644 index 0000000..371b0e8 --- /dev/null +++ b/docs/Dynamic values.md @@ -0,0 +1,39 @@ +In some configuration locations, Ironbar supports dynamic values, +meaning you can inject content into the bar from an external source. + +Currently two dynamic content sources are supported - scripts and ironvars. + +## Dynamic String + +Dynamic strings can contain any mixture of static string elements, scripts and variables. + +Scripts should be placed inside `{{double braces}}`. Both polling and watching scripts are supported. + +Variables use the standard `#name` syntax. Variables cannot be placed inside scripts. + +To use a literal hash, use `##`. This is only necessary outside of scripts. + +Example: + +```toml +label = "{{cat greeting.txt}}, #subject" +``` + +## Dynamic Boolean + +Dynamic booleans can use a single source of either a script or variable to control a true/false value. + +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. + +For variables, use the standard `#name` notation. +An empty string, `0` and `false` are treated as false. +Any other value is true. + +Example: + +```toml +show_if = "exit 0" # script +show_if = "#show_module" # variable +``` \ No newline at end of file diff --git a/docs/Ironvars.md b/docs/Ironvars.md new file mode 100644 index 0000000..ae75806 --- /dev/null +++ b/docs/Ironvars.md @@ -0,0 +1,9 @@ +Ironvars are runtime variables that can be referenced in several places in your config, +then set using the IPC server (such as via the CLI) using the `set` command. + +Any UTF-8 string *without whitespace* is a valid key. +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. \ No newline at end of file diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index e4583bf..2553fe8 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -2,10 +2,16 @@ - [Compiling from source](compiling) - [Configuration guide](configuration-guide) - - [Scripts](scripts) - [Images](images) - [Styling guide](styling-guide) +# Dynamic content + +- [Controlling Ironbar](controlling-ironbar) +- [Dynamic values](dynamic-values) +- [Scripts](scripts) +- [Ironvars](ironvars) + # Examples - [Config](config) @@ -28,4 +34,4 @@ - [Sys_Info](sys-info) - [Tray](tray) - [Upower](upower) -- [Workspaces](workspaces) \ No newline at end of file +- [Workspaces](workspaces) diff --git a/docs/modules/Clipboard.md b/docs/modules/Clipboard.md index fa3f35e..3daa5be 100644 --- a/docs/modules/Clipboard.md +++ b/docs/modules/Clipboard.md @@ -9,17 +9,15 @@ Supports plain text and images. > Type: `clipboard` -| Name | Type | Default | Description | -|-----------------------|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------| -| `icon` | `string/image` | `󰨸` | 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. | - -See [here](images) for information on images. +| 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. |
JSON diff --git a/docs/modules/Custom.md b/docs/modules/Custom.md index bd42ec4..298e0a3 100644 --- a/docs/modules/Custom.md +++ b/docs/modules/Custom.md @@ -1,6 +1,9 @@ Allows you to compose custom modules consisting of multiple widgets, including popups. Labels can display dynamic content from scripts, and buttons can interact with the bar or execute commands on click. +If you only intend to run a single script, prefer the [script](script) module, +or [label](label) if you only need a single text label. + ![Custom module with a button on the bar, and the popup open. The popup contains a header, shutdown button and restart button.](https://f.jstanger.dev/github/ironbar/custom-power-menu.png?raw) ## Configuration @@ -18,11 +21,11 @@ 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. | +| 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. | #### Box @@ -30,20 +33,20 @@ 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` | `Widget[]` | `[]` | List of widgets to add to this box. | +| Name | Type | Default | Description | +|---------------|------------------------------------------------------------|----------------|-------------------------------------------------------------------| +| `orientation` | `'horizontal'` or `'vertical'` (shorthand: `'h'` or `'v'`) | `'horizontal'` | Whether child widgets should be horizontally or vertically added. | +| `widgets` | `Widget[]` | `[]` | List of widgets to add to this box. | #### Label -A text label. Pango markup and embedded scripts are supported. +A text label. Pango markup is supported. > Type `label` -| Name | Type | Default | Description | -|---------|----------|--------------|---------------------------------------------------------------------| -| `label` | `string` | `horizontal` | Widget text label. Pango markup and embedded scripts are supported. | +| Name | Type | Default | Description | +|---------|-------------------------------------------------|---------|---------------------------------------------------------------------| +| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. | #### Button @@ -51,10 +54,10 @@ A clickable button, which can run a command when clicked. > Type `button` -| Name | Type | Default | Description | -|------------|--------------------|--------------|---------------------------------------------------------------------| -| `label` | `string` | `horizontal` | Widget text label. Pango markup and embedded scripts are supported. | -| `on_click` | `string [command]` | `null` | Command to execute. More on this [below](#commands). | +| Name | Type | Default | Description | +|------------|-------------------------------------------------|---------|---------------------------------------------------------------------| +| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Widget text label. Pango markup and embedded scripts are supported. | +| `on_click` | `string [command]` | `null` | Command to execute. More on this [below](#commands). | #### Image @@ -62,10 +65,10 @@ An image or icon from disk or http. > Type `image` -| Name | Type | Default | Description | -|--------|-----------|---------|---------------------------------------------------------------------------------------------| -| `src` | `image` | `null` | Image source. See [here](images) for information on images. Embedded scripts are supported. | -| `size` | `integer` | `null` | Width/height of the image. Aspect ratio is preserved. | +| 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. | #### Slider @@ -76,18 +79,16 @@ A draggable 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 | -|---------------|----------------------------------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------| -| `src` | `image` | `null` | Image source. See [here](images) for information on images. | -| `size` | `integer` | `null` | Width/height of the image. Aspect ratio is preserved. | -| `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. | +| 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. @@ -115,14 +116,12 @@ A progress bar. Note that `value` expects a numeric value **between 0-`max`** as output. -| Name | Type | Default | Description | -|---------------|----------------------------------------------------|--------------|---------------------------------------------------------------------------------| -| `src` | `image` | `null` | Image source. See [here](images) for information on images. | -| `size` | `integer` | `null` | Width/height of the image. Aspect ratio is preserved. | -| `orientation` | `horizontal` or `vertical` (shorthand: `h` or `v`) | `horizontal` | Orientation of the slider. | -| `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. | +| 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: diff --git a/docs/modules/Focused.md b/docs/modules/Focused.md index 4172e5f..bacf72e 100644 --- a/docs/modules/Focused.md +++ b/docs/modules/Focused.md @@ -7,15 +7,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 `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. |
JSON diff --git a/docs/modules/Label.md b/docs/modules/Label.md index 2196c19..c203554 100644 --- a/docs/modules/Label.md +++ b/docs/modules/Label.md @@ -1,12 +1,15 @@ -Displays custom text, with the ability to embed [scripts](https://github.com/JakeStanger/ironbar/wiki/scripts#embedding). +Displays custom text, with markup support. + +If you only intend to run a single script, prefer the [script](script) module. +For more advanced use-cases, use [custom](custom). ## Configuration > Type: `label` -| Name | Type | Default | Description | -|---------|----------|---------|-----------------------------------------| -| `label` | `string` | `null` | Text, optionally with embedded scripts. | +| Name | Type | Default | Description | +|---------|-------------------------------------------------|---------|------------------------| +| `label` | [Dynamic String](dynamic-values#dynamic-string) | `null` | Text to show on label. |
JSON diff --git a/docs/modules/Music.md b/docs/modules/Music.md index 2f912ee..959aad3 100644 --- a/docs/modules/Music.md +++ b/docs/modules/Music.md @@ -11,27 +11,27 @@ 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/image` | `` | Icon to show when playing. | -| `icons.pause` | `string/image` | `` | Icon to show when paused. | -| `icons.prev` | `string/image` | `玲` | Icon to show on previous button. | -| `icons.next` | `string/image` | `怜` | Icon to show on next button. | -| `icons.volume` | `string/image` | `墳` | Icon to show under popup volume slider. | -| `icons.track` | `string/image` | `` | Icon to show next to track title. | -| `icons.album` | `string/image` | `` | Icon to show next to album name. | -| `icons.artist` | `string/image` | `ﴁ` | 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. | +| | 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. diff --git a/docs/modules/Script.md b/docs/modules/Script.md index 8adea5b..afab086 100644 --- a/docs/modules/Script.md +++ b/docs/modules/Script.md @@ -1,6 +1,9 @@ Executes a script and shows the result of `stdout` on a label. Pango markup is supported. +If you want to be able to embed multiple scripts and/or variables, prefer the [label](label) module. +For more advanced use-cases, use [custom](custom). + ## Configuration > Type: `script` diff --git a/docs/modules/Workspaces.md b/docs/modules/Workspaces.md index af91e50..5963c6e 100644 --- a/docs/modules/Workspaces.md +++ b/docs/modules/Workspaces.md @@ -8,12 +8,12 @@ Shows all current workspaces. Clicking a workspace changes focus to it. > Type: `workspaces` -| Name | Type | Default | Description | -|----------------|-----------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `name_map` | `Map` | `{}` | 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. | -| `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` | `{}` | 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. | +| `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. |
JSON