From c3532bc8a18e28474350e5b471f00cf33ba5a290 Mon Sep 17 00:00:00 2001 From: Brian Ashworth Date: Thu, 30 May 2019 02:58:46 -0400 Subject: [PATCH] Add swaybar protocol documentation This adds swaybar-protocol.7.scd documenting the swaybar status line protocol including some differences from the i3bar counterpart. --- meson.build | 1 + sway/sway-bar.5.scd | 8 +- swaybar/swaybar-protocol.7.scd | 269 +++++++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+), 5 deletions(-) create mode 100644 swaybar/swaybar-protocol.7.scd diff --git a/meson.build b/meson.build index 4c35b372e..48bce3aa9 100644 --- a/meson.build +++ b/meson.build @@ -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', diff --git a/sway/sway-bar.5.scd b/sway/sway-bar.5.scd index a3df11601..d53574aae 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. *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) diff --git a/swaybar/swaybar-protocol.7.scd b/swaybar/swaybar-protocol.7.scd new file mode 100644 index 000000000..35368ec11 --- /dev/null +++ b/swaybar/swaybar-protocol.7.scd @@ -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 , 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)