mirrors/sway
1
0
Fork 0
mirror of https://github.com/swaywm/sway.git synced 2024-12-27 07:26:55 +01:00
Code Issues Projects Releases Packages Wiki Activity

Add swaybar protocol documentation

Browse source 
This adds swaybar-protocol.7.scd documenting the swaybar status line
protocol including some differences from the i3bar counterpart.
This commit is contained in:
Brian Ashworth 2019-05-30 02:58:46 -04:00 committed by Drew DeVault
parent 6afb392823
commit c3532bc8a1
3 changed files with 273 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
meson.build
View file

@ -107,6 +107,7 @@ if scdoc.found()
'sway/sway-input.5.scd',
'sway/sway-ipc.7.scd',
'sway/sway-output.5.scd',
'swaybar/swaybar-protocol.7.scd',
'swaymsg/swaymsg.1.scd',
'swaynag/swaynag.1.scd',
'swaynag/swaynag.5.scd',

8
sway/sway-bar.5.scd
View file

@ -13,9 +13,8 @@ Sway allows configuring swaybar in the sway configuration file.
*status_command* <status command>
Executes the bar _status command_ with _sh -c_. Each line of text printed
to stdout from this command will be displayed in the status area of the
bar. You may also use the i3bar JSON protocol:
https://i3wm.org/docs/i3bar-protocol.html
bar. You may also use swaybar's JSON status line protocol. See
*swaybar-protocol*(7) for more information on the protocol
If running this command via IPC, you can disable a running status command by
setting the command to a single dash: _swaybar bar bar-0 status\_command -_
@ -202,5 +201,4 @@ must be defined in hex: _#RRGGBB_ or _#RRGGBBAA_.
# SEE ALSO
*sway*(5)
*sway*(5) *swaybar-protocol*(7)

269
swaybar/swaybar-protocol.7.scd Normal file
View file

@ -0,0 +1,269 @@
swaybar-protocol(7)
# NAME
swaybar-protocol - JSON status line protocol for swaybar
# SUMMARY
swaybar defines the following JSON protocol to specify what information is
displayed in the status line on the right side of swaybar. The protocol is
compromised of a header, that is a JSON object, followed by an infinite JSON
array that represents the information to display. All communication is done by
writing the status line to standard output and reading events from standard
input.
# HEADER
The header is a JSON object with support for the following properties (only
_version_ is required):
[- *PROPERTY*
:- *DATA TYPE*
:- *DEFAULT*
:- *DESCRIPTION*
|- version
: integer
: -
:[ The protocol version to use. Currently, this must be *1*
|- click_events
: boolean
: false
: Whether to receive click event information to standard input
|- cont_signal
: integer
: SIGCONT
: The signal that swaybar should send to continue processing
|- stop_signal
: integer
: SIGSTOP
: The signal that swaybar should send to stop processing
## MINIMAL HEADER
```
{
"version": 1
}
```
## FULL HEADER
```
{
"version": 1,
"click_events": true,
"cont_signal": 18,
"stop_signal": 19
}
```
# BODY
The body is an infinite array, where each element of the array is a
representation of the status line at the time that the element was written.
Each element of the array is itself an array of JSON objects, where each
object represents a block in the status line. Each block can have the following
properties (only _full_text_ is required):
[- *PROPERTY*
:- *DATA TYPE*
:- *DESCRIPTION*
|- full_text
: string
:[ The text that will be displayed. *If missing, the block will be skipped.*
|- short_text
: string
: If given and the text needs to be shortened due to space, this will be
displayed instead of _full_text_
|- color
: string
: The text color to use in #RRGGBBAA or #RRGGBB notation
|- background
: string
: The background color for the block in #RRGGBBAA or #RRGGBB notation
|- border
: string
: The border color for the block in #RRGGBBAA or #RRGGBB notation
|- border_top
: integer
: Whether to draw the top border. This should be _0_ or _1_ (default).
|- border_bottom
: integer
: Whether to draw the bottom border. This should be _0_ or _1_ (default).
|- border_left
: integer
: Whether to draw the left border. This should be _0_ or _1_ (default).
|- border_right
: integer
: Whether to draw the right border. This should be _0_ or _1_ (default).
|- min_width
: integer or string
: The minimum width to use for the block. This can either be given in pixels
or a string can be given to allow for it to be calculated based on the
width of the string.
|- align
: string
: If the text does not span the full width of the block, this specifies how
the text should be aligned inside of the block. This can be _left_
(default), _right_, or _center_.
|- name
: string
: A name for the block. This is only used to identify the block for click
events. If set, each block should have a unique _name_ and _instance_ pair.
|- instance
: string
: The instance of the _name_ for the block. This is only used to identify the
block for click events. If set, each block should have a unique _name_ and
_instance_ pair.
|- urgent
: boolean
: Whether the block should be displayed as urgent. Currently swaybar utilizes
the colors set in the sway config for urgent workspace buttons. See
*sway-bar*(5) for more information on bar color configuration.
|- separator
: boolean
: Whether the bar separator should be drawn after the block. See *sway-bar*(5)
for more information on how to set the separator text.
|- separator_block_width
: integer
: The amount of pixels to leave blank after the block. The separator text will
be displayed centered in this gap. The default is 9 pixels.
|- markup
: string
: The type of markup to use when parsing the text for the block. This can
either be _pango_ or _none_ (default).
Other properties may be given and swaybar will ignore any property that it does
not know. It is recommended to prefix any custom properties with an underscore
to make it easier to distinguish them from protocol properties.
## BODY EXAMPLE
```
[
[
{
"full_text": "25%",
"min_width": "100%",
"urgent": false
},
{
"full_text": "Thu 30 May 2019 02:15:15"
}
],
[
{
"full_text": "20%",
"min_width": "100%",
"urgent": false
},
{
"full_text": "Thu 30 May 2019 02:20:52"
}
],
[
{
"full_text": "15%",
"min_width": "100%",
"urgent": true
},
{
"full_text": "Thu 30 May 2019 02:25:41"
}
],
...
```
## FULL BLOCK EXAMPLE
```
{
"full_text": "Thu 30 May 2019 02:09:15",
"short_text": "02:09",
"color": "#ccccccff",
"background": "#111111ff",
"border": "#222222ff",
"border_top": 1,
"border_bottom": 1,
"border_left": 1,
"border_right": 1,
"min_width": 100,
"align": "center",
"name": "clock",
"instance": "edt",
"urgent": false,
"separator": true,
"separator_block_width": 5,
"markup": "none"
}
```
# CLICK EVENTS
If requested in the header, swaybar will write a JSON object, that can be read
from standard in, when the user clicks on a block. The event object will have
the following properties:
[- *PROPERTY*
:- *DATA TYPE*
:- *DESCRIPTION*
|- name
: string
:[ The name of the block, if set
|- instance
: string
: The instance of the block, if set
|- x
: integer
: The x location that the click occurred at
|- y
: integer
: The y location that the click occurred at
|- button
: integer
: The x11 button number for the click. If the button does not have an x11
button mapping, this will be _0_.
|- event
: integer
: The event code that corresponds to the button for the click
|- relative_x
: integer
: The x location of the click relative to the top-left of the block
|- relative_y
: integer
: The y location of the click relative to the top-left of the block
|- width
: integer
: The width of the block in pixels
|- height
: integer
: The height of the block in pixels
*Differences from i3bar's protocol:*
- _button_ may be _0_ for buttons that do not have x11 button mappings
- _event_ has been introduced to allow for non-x11 buttons to be represented
- The _modifiers_ property is not currently added by swaybar
## EXAMPLE
```
{
"name": "clock",
"instance": "edt",
"x": 1900,
"y": 10,
"button": 1,
"event": 274,
"relative_x": 100,
"relative_y": 8,
"width": 120,
"height": 18
}
```
# AUTHORS
Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
source contributors. For more information about swaybar development, see
https://github.com/swaywm/sway.
# SEE ALSO
*sway-bar*(5)