diff options
author | Brian Ashworth <bosrsf04@gmail.com> | 2019-05-30 02:58:46 -0400 |
---|---|---|
committer | Drew DeVault <sir@cmpwn.com> | 2019-05-30 10:54:23 -0400 |
commit | c3532bc8a18e28474350e5b471f00cf33ba5a290 (patch) | |
tree | 1fa8b62a288826a3f046d7da41f07e4c8da60d17 /swaybar/swaybar-protocol.7.scd | |
parent | bindings: allow unlocked and locked bindings (diff) | |
download | sway-c3532bc8a18e28474350e5b471f00cf33ba5a290.tar.gz sway-c3532bc8a18e28474350e5b471f00cf33ba5a290.tar.zst sway-c3532bc8a18e28474350e5b471f00cf33ba5a290.zip |
Add swaybar protocol documentation
This adds swaybar-protocol.7.scd documenting the swaybar status line
protocol including some differences from the i3bar counterpart.
Diffstat (limited to 'swaybar/swaybar-protocol.7.scd')
-rw-r--r-- | swaybar/swaybar-protocol.7.scd | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/swaybar/swaybar-protocol.7.scd b/swaybar/swaybar-protocol.7.scd new file mode 100644 index 00000000..35368ec1 --- /dev/null +++ b/swaybar/swaybar-protocol.7.scd | |||
@@ -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) | ||