1swaybar-protocol(7)    Miscellaneous Information Manual    swaybar-protocol(7)
2
3
4

NAME

6       swaybar-protocol - JSON status line protocol for swaybar
7

SUMMARY

9       swaybar defines the following JSON protocol to specify what information
10       is displayed in the status line on the right side of swaybar. The pro‐
11       tocol comprises a header, that is a JSON object, followed by a newline
12       (0x0A), followed by an infinite JSON array that represents the informa‐
13       tion to display. All communication is done by writing the status line
14       to standard output and reading events from standard input.
15
17       The header is a JSON object with support for the following properties
18       (only version is required):
19
20       ┌─────────────┬───────────┬─────────┬──────────────────┐
21PROPERTY   DATA TYPE DEFAULT DESCRIPTION    
22       ├─────────────┼───────────┼─────────┼──────────────────┤
23       │  version    │  integer  │    -    │ The protocol     │
24       │             │           │         │ version to use.  │
25       │             │           │         │ Currently, this  │
26       │             │           │         │ must be 1        
27       ├─────────────┼───────────┼─────────┼──────────────────┤
28       │click_events │  boolean  │  false  │ Whether to re‐   │
29       │             │           │         │ ceive click      │
30       │             │           │         │ event informa‐   │
31       │             │           │         │ tion to standard │
32       │             │           │         │ input            │
33       ├─────────────┼───────────┼─────────┼──────────────────┤
34       │cont_signal  │  integer  │ SIGCONT │ The signal that  │
35       │             │           │         │ swaybar should   │
36       │             │           │         │ send to continue │
37       │             │           │         │ processing       │
38       ├─────────────┼───────────┼─────────┼──────────────────┤
39       │stop_signal  │  integer  │ SIGSTOP │ The signal that  │
40       │             │           │         │ swaybar should   │
41       │             │           │         │ send to stop     │
42       │             │           │         │ processing       │
43       └─────────────┴───────────┴─────────┴──────────────────┘
44
45   MINIMAL HEADER
46           {
47                "version": 1
48           }
49
50   FULL HEADER
51           {
52                "version": 1,
53                "click_events": true,
54                "cont_signal": 18,
55                "stop_signal": 19
56           }
57

BODY

59       The body is an infinite array, where each element of the array is a
60       representation of the status line at the time that the element was
61       written. Each element of the array is itself an array of JSON objects,
62       where each object represents a block in the status line. Each block can
63       have the following properties (only full_text is required):
64
65       ┌────────────────┬───────────────────┬─────────────────────┐
66PROPERTY     DATA TYPE     DESCRIPTION     
67       ├────────────────┼───────────────────┼─────────────────────┤
68       │   full_text    │      string       │ The text that will  │
69       │                │                   │ be displayed. If    
70       │                │                   │ missing, the block  
71       │                │                   │ will be skipped.    
72       ├────────────────┼───────────────────┼─────────────────────┤
73       │  short_text    │      string       │ If given and the    │
74       │                │                   │ text needs to be    │
75       │                │                   │ shortened due to    │
76       │                │                   │ space, this will be │
77       │                │                   │ displayed instead   │
78       │                │                   │ of full_text
79       ├────────────────┼───────────────────┼─────────────────────┤
80       │     color      │      string       │ The text color to   │
81       │                │                   │ use in #RRGGBBAA or │
82       │                │                   │ #RRGGBB notation    │
83       ├────────────────┼───────────────────┼─────────────────────┤
84       │  background    │      string       │ The background      │
85       │                │                   │ color for the block │
86       │                │                   │ in #RRGGBBAA or     │
87       │                │                   │ #RRGGBB notation    │
88       ├────────────────┼───────────────────┼─────────────────────┤
89       │    border      │      string       │ The border color    │
90       │                │                   │ for the block in    │
91       │                │                   │ #RRGGBBAA or        │
92       │                │                   │ #RRGGBB notation    │
93       ├────────────────┼───────────────────┼─────────────────────┤
94       │  border_top    │      integer      │ The height in pix‐  │
95       │                │                   │ els of the top bor‐ │
96       │                │                   │ der. The default is │
97       │                │                   │ 1                   │
98       ├────────────────┼───────────────────┼─────────────────────┤
99       │ border_bottom  │      integer      │ The height in pix‐  │
100       │                │                   │ els of the bottom   │
101       │                │                   │ border. The default │
102       │                │                   │ is 1                │
103       ├────────────────┼───────────────────┼─────────────────────┤
104       │  border_left   │      integer      │ The width in pixels │
105       │                │                   │ of the left border. │
106       │                │                   │ The default is 1    │
107       ├────────────────┼───────────────────┼─────────────────────┤
108       │ border_right   │      integer      │ The width in pixels │
109       │                │                   │ of the right bor‐   │
110       │                │                   │ der. The default is │
111       │                │                   │ 1                   │
112       ├────────────────┼───────────────────┼─────────────────────┤
113       │   min_width    │ integer or string │ The minimum width   │
114       │                │                   │ to use for the      │
115       │                │                   │ block. This can ei‐ │
116       │                │                   │ ther be given in    │
117       │                │                   │ pixels or a string  │
118       │                │                   │ can be given to al‐ │
119       │                │                   │ low for it to be    │
120       │                │                   │ calculated based on │
121       │                │                   │ the width of the    │
122       │                │                   │ string.             │
123       ├────────────────┼───────────────────┼─────────────────────┤
124       │     align      │      string       │ If the text does    │
125       │                │                   │ not span the full   │
126       │                │                   │ width of the block, │
127       │                │                   │ this specifies how  │
128       │                │                   │ the text should be  │
129       │                │                   │ aligned inside of   │
130       │                │                   │ the block. This can │
131       │                │                   │ be left (default),  │
132       │                │                   │ right, or center.   │
133       ├────────────────┼───────────────────┼─────────────────────┤
134       │     name       │      string       │ A name for the      │
135       │                │                   │ block. This is only │
136       │                │                   │ used to identify    │
137       │                │                   │ the block for click │
138       │                │                   │ events. If set,     │
139       │                │                   │ each block should   │
140       │                │                   │ have a unique name
141       │                │                   │ and instance pair.  │
142       ├────────────────┼───────────────────┼─────────────────────┤
143       │   instance     │      string       │ The instance of the │
144       │                │                   │ name for the block. │
145       │                │                   │ This is only used   │
146       │                │                   │ to identify the     │
147       │                │                   │ block for click     │
148       │                │                   │ events. If set,     │
149       │                │                   │ each block should   │
150       │                │                   │ have a unique name
151       │                │                   │ and instance pair.  │
152       ├────────────────┼───────────────────┼─────────────────────┤
153       │    urgent      │      boolean      │ Whether the block   │
154       │                │                   │ should be displayed │
155       │                │                   │ as urgent. Cur‐     │
156       │                │                   │ rently swaybar uti‐ │
157       │                │                   │ lizes the colors    │
158       │                │                   │ set in the sway     │
159       │                │                   │ config for urgent   │
160       │                │                   │ workspace buttons.  │
161       │                │                   │ See sway-bar(5) for │
162       │                │                   │ more information on │
163       │                │                   │ bar color configu‐  │
164       │                │                   │ ration.             │
165       ├────────────────┼───────────────────┼─────────────────────┤
166       │   separator    │      boolean      │ Whether the bar     │
167       │                │                   │ separator should be │
168       │                │                   │ drawn after the     │
169       │                │                   │ block. See sway-    
170       │                │                   │ bar(5) for more in‐ │
171       │                │                   │ formation on how to │
172       │                │                   │ set the separator   │
173       │                │                   │ text.               │
174       ├────────────────┼───────────────────┼─────────────────────┤
175       │separa‐         │      integer      │ The amount of pix‐  │
176       │tor_block_width │                   │ els to leave blank  │
177       │                │                   │ after the block.    │
178       │                │                   │ The separator text  │
179       │                │                   │ will be displayed   │
180       │                │                   │ centered in this    │
181       │                │                   │ gap. The default is │
182       │                │                   │ 9 pixels.           │
183       ├────────────────┼───────────────────┼─────────────────────┤
184       │    markup      │      string       │ The type of markup  │
185       │                │                   │ to use when parsing │
186       │                │                   │ the text for the    │
187       │                │                   │ block. This can ei‐ │
188       │                │                   │ ther be pango or    │
189       │                │                   │ none (default).     │
190       └────────────────┴───────────────────┴─────────────────────┘
191       Other properties may be given and swaybar will ignore any property that
192       it does not know. It is recommended to prefix any custom properties
193       with an underscore to make it easier to distinguish them from protocol
194       properties.
195
196   BODY EXAMPLE
197           [
198                [
199                     {
200                          "full_text": "25%",
201                          "min_width": "100%",
202                          "urgent": false
203                     },
204                     {
205                          "full_text": "Thu 30 May 2019 02:15:15"
206                     }
207                ],
208                [
209                     {
210                          "full_text": "20%",
211                          "min_width": "100%",
212                          "urgent": false
213                     },
214                     {
215                          "full_text": "Thu 30 May 2019 02:20:52"
216                     }
217                ],
218                [
219                     {
220                          "full_text": "15%",
221                          "min_width": "100%",
222                          "urgent": true
223                     },
224                     {
225                          "full_text": "Thu 30 May 2019 02:25:41"
226                     }
227                ],
228                ...
229
230   FULL BLOCK EXAMPLE
231           {
232                "full_text": "Thu 30 May 2019 02:09:15",
233                "short_text": "02:09",
234                "color": "#ccccccff",
235                "background": "#111111ff",
236                "border": "#222222ff",
237                "border_top": 1,
238                "border_bottom": 1,
239                "border_left": 1,
240                "border_right": 1,
241                "min_width": 100,
242                "align": "center",
243                "name": "clock",
244                "instance": "edt",
245                "urgent": false,
246                "separator": true,
247                "separator_block_width": 5,
248                "markup": "none"
249           }
250

CLICK EVENTS

252       If requested in the header, swaybar will write a JSON object, that can
253       be read from standard in, when the user clicks on a block. The event
254       object will have the following properties:
255
256       ┌───────────┬───────────┬─────────────────────┐
257PROPERTY  DATA TYPE DESCRIPTION     
258       ├───────────┼───────────┼─────────────────────┤
259       │   name    │  string   │ The name of the     │
260       │           │           │ block, if set       │
261       ├───────────┼───────────┼─────────────────────┤
262       │ instance  │  string   │ The instance of the │
263       │           │           │ block, if set       │
264       ├───────────┼───────────┼─────────────────────┤
265       │    x      │  integer  │ The x location that │
266       │           │           │ the click occurred  │
267       │           │           │ at                  │
268       ├───────────┼───────────┼─────────────────────┤
269       │    y      │  integer  │ The y location that │
270       │           │           │ the click occurred  │
271       │           │           │ at                  │
272       ├───────────┼───────────┼─────────────────────┤
273       │  button   │  integer  │ The x11 button num‐ │
274       │           │           │ ber for the click.  │
275       │           │           │ If the button does  │
276       │           │           │ not have an x11     │
277       │           │           │ button mapping,     │
278       │           │           │ this will be 0.     │
279       ├───────────┼───────────┼─────────────────────┤
280       │  event    │  integer  │ The event code that │
281       │           │           │ corresponds to the  │
282       │           │           │ button for the      │
283       │           │           │ click               │
284       ├───────────┼───────────┼─────────────────────┤
285       │relative_x │  integer  │ The x location of   │
286       │           │           │ the click relative  │
287       │           │           │ to the top-left of  │
288       │           │           │ the block           │
289       ├───────────┼───────────┼─────────────────────┤
290       │relative_y │  integer  │ The y location of   │
291       │           │           │ the click relative  │
292       │           │           │ to the top-left of  │
293       │           │           │ the block           │
294       ├───────────┼───────────┼─────────────────────┤
295       │  width    │  integer  │ The width of the    │
296       │           │           │ block in pixels     │
297       ├───────────┼───────────┼─────────────────────┤
298       │  height   │  integer  │ The height of the   │
299       │           │           │ block in pixels     │
300       └───────────┴───────────┴─────────────────────┘
301       Differences from i3bar's protocol:
302button may be 0 for buttons that do not have x11 button mappings
303event has been introduced to allow for non-x11 buttons to be repre‐
304           sented
305       •   The modifiers property is not currently added by swaybar
306
307
308   EXAMPLE
309           {
310                "name": "clock",
311                "instance": "edt",
312                "x": 1900,
313                "y": 10,
314                "button": 1,
315                "event": 274,
316                "relative_x": 100,
317                "relative_y": 8,
318                "width": 120,
319                "height": 18
320           }
321

SEE ALSO

323       sway-bar(5)
324
325
326
327                                  2022-01-22               swaybar-protocol(7)
Impressum