i3bar input protocol
<michael@i3wm.org>
-February 2012 +August 2012
X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fi3bar-protocol.html;h=a9478fc3ac4fb4849c0ece3c2b5f98f0ce301200;hb=16ab9b7f27367ba3000bc5ac415c4ac8fdb53434;hp=c64aafeac35d5c4f4582430cd23956e1ac91c4a4;hpb=a51955422cfef50d617cd856bddec422cb8c3493;p=i3%2Fi3.github.io diff --git a/docs/i3bar-protocol.html b/docs/i3bar-protocol.html index c64aafe..a9478fc 100644 --- a/docs/i3bar-protocol.html +++ b/docs/i3bar-protocol.html @@ -2,15 +2,15 @@ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
- + - +Before describing the protocol, letâs cover why JSON is a building block of this protocol.
Example:
Minimal example:
{ "version": 1 }
All features example:
{ "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }+
(Note that before i3 v4.3 the precise format had to be {"version":1}, +byte-for-byte.)
What follows is an infinite array (so it should be parsed by a streaming JSON parser, but as described above you can go for a simpler solution), whose elements are one array per status line. A status line is one unit of @@ -135,17 +143,61 @@ be represented by a JSON hash:
Please note that this example was pretty printed for human consumption. i3status and others will output single statuslines in one line, separated by \n.
You can find an example of a shell script which can be used as your +status_command in the bar configuration at +http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next
+ The version number (as an integer) of the i3bar protocol you will use. +
++ Specify to i3bar the signal (as an integer) to send to stop your + processing. + The default value (if none is specified) is SIGSTOP. +
++ Specify to i3bar the signal (as an integer)to send to continue your + processing. + The default value (if none is specified) is SIGCONT. +
++ If specified and true i3bar will write an infinite array (same as above) + to your stdin. +
+- The most simple block you can think of is one which just includes the - only required key, the full_text key. i3bar will display the string - value and thatâs it. + The full_text will be displayed by i3bar on the status line. This is the + only required key.
+ Overrides the background color for this particular block. +
++ Overrides the border color for this particular block. +
++ The minimum width (in pixels) of the block. If the content of the + full_text key take less space than the specified min_width, the block + will be padded to the left and/or the right side, according to the align + key. This is useful when you want to prevent the whole status line to shift + when value take more or less space between each iteration. + The value can also be a string. In this case, the width of the text given + by min_width determines the minimum width of the block. This is useful + when you want to set a sensible minimum width regardless of which font you + are using, and at what particular size. +
++ Align text on the center, right or left (default) of the block, when + the minimum width of the latter, specified by the min_width key, is not + reached. +
++ A boolean which specifies whether a separator line should be drawn + after this block. The default is true, meaning the separator line will + be drawn. Note that if you disable the separator line, there will still + be a gap after the block, unless you also use separator_block_width. +
++ The amount of pixels to leave blank after the block. In the middle of + this gap, a separator line will be drawn unless separator is + disabled. Normally, you want to set this to an odd value (the default + is 9 pixels), since the separator line is drawn in the middle. +
++ A string that indicates how the text of the block should be parsed. Set to + "pango" to use Pango markup. + Set to "none" to not use any markup (default). +
+If you want to put in your own entries into a block, prefix the key with an underscore (_). i3bar will ignore all keys it doesnât understand, and prefixing @@ -212,6 +338,16 @@ of the i3bar protocol.
In the following example, the longest (widest) possible value of the block is +used to set the minimum width:
{ + "full_text": "CPU 4%", + "min_width": "CPU 100%", + "align": "left" +}+
An example of a block which uses all possible entries follows:
Example:
If enabled i3bar will send you notifications if the user clicks on a block and +looks like this:
+ Name of the block, if set +
++ Instance of the block, if set +
++ X11 root window coordinates where the click occurred +
++ X11 button ID (for example 1 to 3 for left/middle/right mouse button) +
+Example:
{ + "name": "ethernet", + "instance": "eth0", + "button": 1, + "x": 1320, + "y": 1400 }