X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fi3bar-protocol;h=62706f74359488688bafa5a83e702aa0af5040f3;hb=3de950e0d9edf80015e70d3fd6a6ab180f15417c;hp=9225d97eab134f90b9567095f2cb2eea622ef3e0;hpb=a1691a08ba33bba654d45e80afab0dcf03cc0cfa;p=i3%2Fi3

diff --git a/docs/i3bar-protocol b/docs/i3bar-protocol
index 9225d97e..62706f74 100644
--- a/docs/i3bar-protocol
+++ b/docs/i3bar-protocol
@@ -6,7 +6,7 @@ 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.
@@ -51,7 +51,7 @@ consists of a single JSON hash:
 
 *All features example*:
 ------------------------------
-{ "version": 1, "stop_signal": 10, "cont_signal": 12 }
+{ "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}+,
@@ -96,7 +96,7 @@ i3status and others will output single statuslines in one line, separated by
 
 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
+https://github.com/i3/i3/blob/next/contrib/trivial-bar-script.sh
 
 === Header in detail
 
@@ -107,16 +107,19 @@ stop_signal::
 	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
+	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. If +full_text+ is an empty string, the block will be
+	skipped.
 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
@@ -134,6 +137,10 @@ 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
@@ -145,7 +152,7 @@ min_width::
         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+ (default), +right+ or +left+ of the block, when
+	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::
@@ -168,6 +175,11 @@ separator_block_width::
 	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
@@ -201,6 +213,8 @@ 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,
@@ -210,3 +224,37 @@ An example of a block which uses all possible entries follows:
  "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
+}
+------------------------------------------