i3bar: Add protocol for workspace buttons
Closes #3818 (parent issue) Fixes #1808 Fixes #2333 Fixes #2617 Fixes #3548
This commit is contained in:
Orestis Floros
184
docs/i3bar-workspace-protocol
Normal file
184
docs/i3bar-workspace-protocol
Normal file
@ -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" ]'
|
||||
------------------------------
|
||||
@ -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
|
||||
|
||||
Reference in New Issue
Block a user