diff options
author | Orestis Floros <orestisflo@gmail.com> | 2023-01-22 18:34:14 +0100 |
---|---|---|
committer | Orestis Floros <orestisflo@gmail.com> | 2023-01-22 18:59:58 +0100 |
commit | ba1f40f45fc03b279f55adcb4f7e00e38d78ba0e (patch) | |
tree | 34b2dfb64a0cacc94255b6a71f79643160dd3508 /docs | |
parent | c52f13900df5da04d86809abbfe25178a4bbe305 (diff) | |
download | i3-ba1f40f45fc03b279f55adcb4f7e00e38d78ba0e.tar.gz i3-ba1f40f45fc03b279f55adcb4f7e00e38d78ba0e.zip |
i3bar: Add protocol for workspace buttons
Closes #3818 (parent issue)
Fixes #1808
Fixes #2333
Fixes #2617
Fixes #3548
Diffstat (limited to 'docs')
-rw-r--r-- | docs/i3bar-workspace-protocol | 184 | ||||
-rw-r--r-- | docs/userguide | 24 |
2 files changed, 208 insertions, 0 deletions
diff --git a/docs/i3bar-workspace-protocol b/docs/i3bar-workspace-protocol new file mode 100644 index 00000000..016fc965 --- /dev/null +++ b/docs/i3bar-workspace-protocol @@ -0,0 +1,184 @@ +i3bar workspace buttons protocol +================================ + +This document explains the protocol in which i3bar expects input for +configuring workspace buttons. This feature is available since i3 version 4.23. + +The program defined by the +workspace_command+ configuration option for i3bar can +modify the workspace buttons displayed by i3bar. The command should constantly +print in its standard output a stream of messages following the protocol +defined in this page. + +If you are looking for the status line protocol instead, see https://i3wm.org/docs/i3bar-protocol.html. + +== The protocol + +Each message should be a newline-delimited JSON array. The array is in the same +format as the +GET_WORKSPACES+ ipc event, see +https://i3wm.org/docs/ipc.html#_workspaces_reply. + +As an example, this is the output of the +i3-msg -t get_workspaces+ command: +------------------------------ +[ + { + "id": 94131549984064, + "num": 1, + "name": "1", + "visible": false, + "focused": false, + "output": "HDMI-A-0", + "urgent": false + }, + { + "id": 94131550477584, + "num": 2, + "name": "2", + "visible": true, + "focused": true, + "output": "HDMI-A-0", + "urgent": false + }, + { + "id": 94131550452704, + "num": 3, + "name": "3:some workspace", + "visible": false, + "focused": false, + "output": "HDMI-A-0", + "urgent": false + } +] +------------------------------ + +Please note that this example was pretty printed for human consumption, with +the +"rect"+ field removed. Workspace button commands should output each array +in one line. + +Each element in the array represents a workspace. i3bar creates one workspace +button for each element in the array. The order of these buttons is the same as +the order of the elements in the array. + +In general, we recommend subscribing to the +workspace+ and +output+ +https://i3wm.org/docs/ipc.html#_workspace_event[events], +fetching the current workspace information with +GET_WORKSPACES+, modifying the +JSON array in the response according to your needs and then printing it to the +standard output. However, you are free to build a new message from the ground +up. + +=== Workspace objects in detail + +The documentation of +GET_WORKSPACES+ should be sufficient to understand the +meaning of each property but here we provide extra notes for each property and +its meaning with respect to i3bar. + +All properties but +name+ are optional. + +id (integer):: + If it is included it will be used to switch to that workspace when you + click the corresponding button. If it's not provided, the +name+ will be + used. You can use the +id+ field to present workspaces under a modified + name. +num (integer):: + The only use of a workspace's number is if the +strip_workspace_numbers+ + setting is enabled. +name (string):: + The only required property. If an +id+ is provided you can freely change + the +name+ as you wish, effectively renaming the buttons of i3bar. +visible (boolean):: + Defaults to +false+ if not included. +focused+ takes precedence over it, + however +visible+ is important for more than one monitors. +focused (boolean):: + Defaults to +false+ if not included. Generally, exactly one of the + workspaces should be +focused+. If not, no button will have the + +focused_workspace+ color. +urgent (boolean):: + Defaults to +false+ if not included. +rect (map):: + Not used by i3bar but will be ignored. +output (string):: + Defaults to the primary output if not included. + +== Examples + +These example scripts require the https://stedolan.github.io/jq/[jq] utility to +be installed but otherwise just use the standard +i3-msg+ utility included with +i3. However, you can write your own scripts in your preferred language, with +the help of one of the +https://i3wm.org/docs/ipc.html#_see_also_existing_libraries[pre-existing i3 +libraries] + +=== Base configuration + +------------------------------ +bar { + … + workspace_command /path/to/your/script.sh + … +} +------------------------------ + +=== Re-create the default behaviour of i3bar + +Not very useful by itself but this will be the basic building block of all the +following scripts. This one does not require +jq+. + +------------------------------ +#!/bin/sh +i3-msg -t subscribe -m '["workspace", "output"]' | { + # Initially print the current workspaces before we receive any events. This + # avoids having an empty bar when starting up. + i3-msg -t get_workspaces; + # Then, while we receive events, update the workspace information. + while read; do i3-msg -t get_workspaces; done; +} +------------------------------ + +=== Hide workspace named +foo+ unless if it is focused. + +------------------------------ +#!/bin/sh +i3-msg -t subscribe -m '["workspace", "output"]' | { + i3-msg -t get_workspaces; + while read; do i3-msg -t get_workspaces; done; +} | jq --unbuffered -c '[ .[] | select(.name != "foo" or .focused) ]' +------------------------------ + +Important! Make sure you use the +--unbuffered+ flag with +jq+, otherwise you +might not get the changes in real-time but whenever they are flushed, which +might mean that you are getting an empty bar until enough events are written. + +=== Show empty workspaces +foo+ and +bar+ on LVDS1 even if they do not exist at the moment. + +------------------------------ +#!/bin/sh +i3-msg -t subscribe -m '["workspace", "output"]' | { + i3-msg -t get_workspaces; + while read; do i3-msg -t get_workspaces; done; +} | jq --unbuffered -c ' + def fake_ws(name): { + name: name, + output: "LVDS1", + }; + . + [ fake_ws("foo"), fake_ws("bar") ] | unique_by(.name) +' +------------------------------ + +=== Sort workspaces in reverse alphanumeric order + +------------------------------ +#!/bin/sh +i3-msg -t subscribe -m '["workspace", "output"]' | { + i3-msg -t get_workspaces; + while read; do i3-msg -t get_workspaces; done; +} | jq --unbuffered -c 'sort_by(.name) | reverse' +------------------------------ + +=== Append "foo" to the name of each workspace + +------------------------------ +#!/bin/sh +i3-msg -t subscribe -m '["workspace", "output"]' | { + i3-msg -t get_workspaces; + while read; do i3-msg -t get_workspaces; done; +} | jq --unbuffered -c '[ .[] | .name |= . + " foo" ]' +------------------------------ diff --git a/docs/userguide b/docs/userguide index 7fe0b9af..1bc5c73b 100644 --- a/docs/userguide +++ b/docs/userguide @@ -1611,6 +1611,30 @@ bar { } ------------------------------------------------- +[[workspace_command]] +=== Workspace buttons command + +Since i3 4.23, i3bar can run a program and use its +stdout+ output to define +the workspace buttons displayed on the left hand side of the bar. With this +feature, you can, for example, rename the buttons of workspaces, hide specific +workspaces, always show a workspace button even if the workspace does not exist +or change the order of the buttons. + +Also see <<status_command>> for the statusline option and +https://i3wm.org/docs/i3bar-workspace-protocol.html for the detailed protocol. + +*Syntax*: +------------------------ +workspace_command <command> +------------------------ + +*Example*: +------------------------------------------------- +bar { + workspace_command /path/to/script.sh +} +------------------------------------------------- + === Display mode You can either have i3bar be visible permanently at one edge of the screen |