X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fi3bar-protocol;h=8b7d2af76ccdefe0a1a99e78843a960ce4f55029;hb=65eb54c0ba73dea6d01a2cb42c3c9b40df8c6820;hp=f66c7a9a6129a8c90b9175aa4a963bbe9ed8c7a2;hpb=e09e077b763bb1ff1975998c87d017afa9c319c3;p=i3%2Fi3 diff --git a/docs/i3bar-protocol b/docs/i3bar-protocol index f66c7a9a..8b7d2af7 100644 --- a/docs/i3bar-protocol +++ b/docs/i3bar-protocol @@ -1,12 +1,12 @@ i3bar input protocol ==================== Michael Stapelberg -February 2012 +August 2012 This document explains the protocol in which i3bar expects its input. It provides support for colors, urgency, shortening and easy manipulation. -== Rationale for chosing JSON +== Rationale for choosing JSON Before describing the protocol, let’s cover why JSON is a building block of this protocol. @@ -44,10 +44,18 @@ understand the old protocol version, but in order to use the new one, you need to provide the correct version. The header block is terminated by a newline and consists of a single JSON hash: -*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 @@ -86,12 +94,31 @@ 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 +https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh + +=== Header in detail + +version:: + The version number (as an integer) of the i3bar protocol you will use. +stop_signal:: + Specify to i3bar the signal (as an integer) to send to stop your + processing. + The default value (if none is specified) is SIGSTOP. +cont_signal:: + Specify to i3bar the signal (as an integer) to send to continue your + processing. + The default value (if none is specified) is SIGCONT. +click_events:: + If specified and true i3bar will write an infinite array (same as above) + to your stdin. + === Blocks in detail full_text:: - 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. short_text:: Where appropriate, the +short_text+ (string) entry should also be provided. It will be used in case the status line needs to be shortened @@ -109,6 +136,24 @@ color:: when it is associated. Colors are specified in hex (like in HTML), starting with a leading hash sign. For example, +#ff0000+ means red. +background:: + Overrides the background color for this particular block. +border:: + Overrides the border color for this particular block. +min_width:: + 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:: + 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. name and instance:: Every block should have a unique +name+ (string) entry so that it can be easily identified in scripts which process the output. i3bar @@ -119,6 +164,21 @@ urgent:: A boolean which specifies whether the current value is urgent. Examples are battery charge values below 1 percent or no more available disk space (for non-root users). The presentation of urgency is up to i3bar. +separator:: + 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+. +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. +markup:: + A string that indicates how the text of the block should be parsed. Set to + +"pango"+ to use https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup]. + Set to +"none"+ to not use any markup (default). Pango markup only works + if you use a pango font. 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 @@ -133,6 +193,17 @@ 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*: @@ -141,8 +212,48 @@ An example of a block which uses all possible entries follows: "full_text": "E: 10.0.0.1 (1000 Mbit/s)", "short_text": "10.0.0.1", "color": "#00ff00", + "background": "#1c1c1c", + "border": "#ee0000", + "min_width": 300, + "align": "right", "urgent": false, "name": "ethernet", - "instance": "eth0" + "instance": "eth0", + "separator": true, + "separator_block_width": 9 +} +------------------------------------------ + +=== Click events + +If enabled i3bar will send you notifications if the user clicks on a block and +looks like this: + +name:: + Name of the block, if set +instance:: + Instance of the block, if set +x, y:: + X11 root window coordinates where the click occurred +button:: + X11 button ID (for example 1 to 3 for left/middle/right mouse button) +relative_x, relative_y:: + Coordinates where the click occurred, with respect to the top left corner + of the block +width, height:: + Width and height (in px) of the block + +*Example*: +------------------------------------------ +{ + "name": "ethernet", + "instance": "eth0", + "button": 1, + "x": 1320, + "y": 1400, + "relative_x": 12, + "relative_y": 8, + "width": 50, + "height": 22 } ------------------------------------------