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 | |
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.
-rw-r--r-- | meson.build | 1 | ||||
-rw-r--r-- | sway/sway-bar.5.scd | 8 | ||||
-rw-r--r-- | swaybar/swaybar-protocol.7.scd | 269 |
3 files changed, 273 insertions, 5 deletions
diff --git a/meson.build b/meson.build index 4c35b372..48bce3aa 100644 --- a/meson.build +++ b/meson.build | |||
@@ -107,6 +107,7 @@ if scdoc.found() | |||
107 | 'sway/sway-input.5.scd', | 107 | 'sway/sway-input.5.scd', |
108 | 'sway/sway-ipc.7.scd', | 108 | 'sway/sway-ipc.7.scd', |
109 | 'sway/sway-output.5.scd', | 109 | 'sway/sway-output.5.scd', |
110 | 'swaybar/swaybar-protocol.7.scd', | ||
110 | 'swaymsg/swaymsg.1.scd', | 111 | 'swaymsg/swaymsg.1.scd', |
111 | 'swaynag/swaynag.1.scd', | 112 | 'swaynag/swaynag.1.scd', |
112 | 'swaynag/swaynag.5.scd', | 113 | 'swaynag/swaynag.5.scd', |
diff --git a/sway/sway-bar.5.scd b/sway/sway-bar.5.scd index a3df1160..d53574aa 100644 --- a/sway/sway-bar.5.scd +++ b/sway/sway-bar.5.scd | |||
@@ -13,9 +13,8 @@ Sway allows configuring swaybar in the sway configuration file. | |||
13 | *status_command* <status command> | 13 | *status_command* <status command> |
14 | Executes the bar _status command_ with _sh -c_. Each line of text printed | 14 | Executes the bar _status command_ with _sh -c_. Each line of text printed |
15 | to stdout from this command will be displayed in the status area of the | 15 | to stdout from this command will be displayed in the status area of the |
16 | bar. You may also use the i3bar JSON protocol: | 16 | bar. You may also use swaybar's JSON status line protocol. See |
17 | 17 | *swaybar-protocol*(7) for more information on the protocol | |
18 | https://i3wm.org/docs/i3bar-protocol.html | ||
19 | 18 | ||
20 | If running this command via IPC, you can disable a running status command by | 19 | If running this command via IPC, you can disable a running status command by |
21 | setting the command to a single dash: _swaybar bar bar-0 status\_command -_ | 20 | 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_. | |||
202 | 201 | ||
203 | # SEE ALSO | 202 | # SEE ALSO |
204 | 203 | ||
205 | *sway*(5) | 204 | *sway*(5) *swaybar-protocol*(7) |
206 | |||
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) | ||