Skip to content

Commit c3532bc

Browse files
RedSoxFanddevault
RedSoxFan
authored and
ddevault
committed
Add swaybar protocol documentation
This adds swaybar-protocol.7.scd documenting the swaybar status line protocol including some differences from the i3bar counterpart.
1 parent 6afb392 commit c3532bc

File tree

3 files changed

+273
-5
lines changed

3 files changed

+273
-5
lines changed

‎meson.build

+1
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ if scdoc.found()
107107
'sway/sway-input.5.scd',
108108
'sway/sway-ipc.7.scd',
109109
'sway/sway-output.5.scd',
110+
'swaybar/swaybar-protocol.7.scd',
110111
'swaymsg/swaymsg.1.scd',
111112
'swaynag/swaynag.1.scd',
112113
'swaynag/swaynag.5.scd',

‎sway/sway-bar.5.scd

+3-5
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,8 @@ Sway allows configuring swaybar in the sway configuration file.
1313
*status_command* <status command>
1414
Executes the bar _status command_ with _sh -c_. Each line of text printed
1515
to stdout from this command will be displayed in the status area of the
16-
bar. You may also use the i3bar JSON protocol:
17-
18-
https://i3wm.org/docs/i3bar-protocol.html
16+
bar. You may also use swaybar's JSON status line protocol. See
17+
*swaybar-protocol*(7) for more information on the protocol
1918

2019
If running this command via IPC, you can disable a running status command by
2120
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_.
202201

203202
# SEE ALSO
204203

205-
*sway*(5)
206-
204+
*sway*(5) *swaybar-protocol*(7)

‎swaybar/swaybar-protocol.7.scd

+269
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
swaybar-protocol(7)
2+
3+
# NAME
4+
5+
swaybar-protocol - JSON status line protocol for swaybar
6+
7+
# SUMMARY
8+
9+
swaybar defines the following JSON protocol to specify what information is
10+
displayed in the status line on the right side of swaybar. The protocol is
11+
compromised of a header, that is a JSON object, followed by an infinite JSON
12+
array that represents the information to display. All communication is done by
13+
writing the status line to standard output and reading events from standard
14+
input.
15+
16+
# HEADER
17+
18+
The header is a JSON object with support for the following properties (only
19+
_version_ is required):
20+
[- *PROPERTY*
21+
:- *DATA TYPE*
22+
:- *DEFAULT*
23+
:- *DESCRIPTION*
24+
|- version
25+
: integer
26+
: -
27+
:[ The protocol version to use. Currently, this must be *1*
28+
|- click_events
29+
: boolean
30+
: false
31+
: Whether to receive click event information to standard input
32+
|- cont_signal
33+
: integer
34+
: SIGCONT
35+
: The signal that swaybar should send to continue processing
36+
|- stop_signal
37+
: integer
38+
: SIGSTOP
39+
: The signal that swaybar should send to stop processing
40+
41+
## MINIMAL HEADER
42+
```
43+
{
44+
"version": 1
45+
}
46+
```
47+
48+
## FULL HEADER
49+
```
50+
{
51+
"version": 1,
52+
"click_events": true,
53+
"cont_signal": 18,
54+
"stop_signal": 19
55+
}
56+
```
57+
58+
# BODY
59+
60+
The body is an infinite array, where each element of the array is a
61+
representation of the status line at the time that the element was written.
62+
Each element of the array is itself an array of JSON objects, where each
63+
object represents a block in the status line. Each block can have the following
64+
properties (only _full_text_ is required):
65+
66+
[- *PROPERTY*
67+
:- *DATA TYPE*
68+
:- *DESCRIPTION*
69+
|- full_text
70+
: string
71+
:[ The text that will be displayed. *If missing, the block will be skipped.*
72+
|- short_text
73+
: string
74+
: If given and the text needs to be shortened due to space, this will be
75+
displayed instead of _full_text_
76+
|- color
77+
: string
78+
: The text color to use in #RRGGBBAA or #RRGGBB notation
79+
|- background
80+
: string
81+
: The background color for the block in #RRGGBBAA or #RRGGBB notation
82+
|- border
83+
: string
84+
: The border color for the block in #RRGGBBAA or #RRGGBB notation
85+
|- border_top
86+
: integer
87+
: Whether to draw the top border. This should be _0_ or _1_ (default).
88+
|- border_bottom
89+
: integer
90+
: Whether to draw the bottom border. This should be _0_ or _1_ (default).
91+
|- border_left
92+
: integer
93+
: Whether to draw the left border. This should be _0_ or _1_ (default).
94+
|- border_right
95+
: integer
96+
: Whether to draw the right border. This should be _0_ or _1_ (default).
97+
|- min_width
98+
: integer or string
99+
: The minimum width to use for the block. This can either be given in pixels
100+
or a string can be given to allow for it to be calculated based on the
101+
width of the string.
102+
|- align
103+
: string
104+
: If the text does not span the full width of the block, this specifies how
105+
the text should be aligned inside of the block. This can be _left_
106+
(default), _right_, or _center_.
107+
|- name
108+
: string
109+
: A name for the block. This is only used to identify the block for click
110+
events. If set, each block should have a unique _name_ and _instance_ pair.
111+
|- instance
112+
: string
113+
: The instance of the _name_ for the block. This is only used to identify the
114+
block for click events. If set, each block should have a unique _name_ and
115+
_instance_ pair.
116+
|- urgent
117+
: boolean
118+
: Whether the block should be displayed as urgent. Currently swaybar utilizes
119+
the colors set in the sway config for urgent workspace buttons. See
120+
*sway-bar*(5) for more information on bar color configuration.
121+
|- separator
122+
: boolean
123+
: Whether the bar separator should be drawn after the block. See *sway-bar*(5)
124+
for more information on how to set the separator text.
125+
|- separator_block_width
126+
: integer
127+
: The amount of pixels to leave blank after the block. The separator text will
128+
be displayed centered in this gap. The default is 9 pixels.
129+
|- markup
130+
: string
131+
: The type of markup to use when parsing the text for the block. This can
132+
either be _pango_ or _none_ (default).
133+
134+
Other properties may be given and swaybar will ignore any property that it does
135+
not know. It is recommended to prefix any custom properties with an underscore
136+
to make it easier to distinguish them from protocol properties.
137+
138+
## BODY EXAMPLE
139+
140+
```
141+
[
142+
[
143+
{
144+
"full_text": "25%",
145+
"min_width": "100%",
146+
"urgent": false
147+
},
148+
{
149+
"full_text": "Thu 30 May 2019 02:15:15"
150+
}
151+
],
152+
[
153+
{
154+
"full_text": "20%",
155+
"min_width": "100%",
156+
"urgent": false
157+
},
158+
{
159+
"full_text": "Thu 30 May 2019 02:20:52"
160+
}
161+
],
162+
[
163+
{
164+
"full_text": "15%",
165+
"min_width": "100%",
166+
"urgent": true
167+
},
168+
{
169+
"full_text": "Thu 30 May 2019 02:25:41"
170+
}
171+
],
172+
...
173+
```
174+
175+
## FULL BLOCK EXAMPLE
176+
```
177+
{
178+
"full_text": "Thu 30 May 2019 02:09:15",
179+
"short_text": "02:09",
180+
"color": "#ccccccff",
181+
"background": "#111111ff",
182+
"border": "#222222ff",
183+
"border_top": 1,
184+
"border_bottom": 1,
185+
"border_left": 1,
186+
"border_right": 1,
187+
"min_width": 100,
188+
"align": "center",
189+
"name": "clock",
190+
"instance": "edt",
191+
"urgent": false,
192+
"separator": true,
193+
"separator_block_width": 5,
194+
"markup": "none"
195+
}
196+
```
197+
198+
# CLICK EVENTS
199+
200+
If requested in the header, swaybar will write a JSON object, that can be read
201+
from standard in, when the user clicks on a block. The event object will have
202+
the following properties:
203+
204+
[- *PROPERTY*
205+
:- *DATA TYPE*
206+
:- *DESCRIPTION*
207+
|- name
208+
: string
209+
:[ The name of the block, if set
210+
|- instance
211+
: string
212+
: The instance of the block, if set
213+
|- x
214+
: integer
215+
: The x location that the click occurred at
216+
|- y
217+
: integer
218+
: The y location that the click occurred at
219+
|- button
220+
: integer
221+
: The x11 button number for the click. If the button does not have an x11
222+
button mapping, this will be _0_.
223+
|- event
224+
: integer
225+
: The event code that corresponds to the button for the click
226+
|- relative_x
227+
: integer
228+
: The x location of the click relative to the top-left of the block
229+
|- relative_y
230+
: integer
231+
: The y location of the click relative to the top-left of the block
232+
|- width
233+
: integer
234+
: The width of the block in pixels
235+
|- height
236+
: integer
237+
: The height of the block in pixels
238+
239+
*Differences from i3bar's protocol:*
240+
- _button_ may be _0_ for buttons that do not have x11 button mappings
241+
- _event_ has been introduced to allow for non-x11 buttons to be represented
242+
- The _modifiers_ property is not currently added by swaybar
243+
244+
## EXAMPLE
245+
246+
```
247+
{
248+
"name": "clock",
249+
"instance": "edt",
250+
"x": 1900,
251+
"y": 10,
252+
"button": 1,
253+
"event": 274,
254+
"relative_x": 100,
255+
"relative_y": 8,
256+
"width": 120,
257+
"height": 18
258+
}
259+
```
260+
261+
# AUTHORS
262+
263+
Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
264+
source contributors. For more information about swaybar development, see
265+
https://github.com/swaywm/sway.
266+
267+
# SEE ALSO
268+
269+
*sway-bar*(5)

0 commit comments

Comments
 (0)