Merge branch 'defect-1480' of https://github.com/Airblader/i3-original into Airblader...

[i3/i3] / docs / i3bar-protocol

diff --git a/docs/i3bar-protocol b/docs/i3bar-protocol
index 121b0c8eb249a97c6f730408c392727c163476bc..8fd51ae9359cfe92ae1fd6f45a2057bf0a591b1a 100644 (file)
--- a/docs/i3bar-protocol
+++ b/docs/i3bar-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}+,
@@ -110,13 +110,17 @@ 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 a 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.
+       value parsed as
+       https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup].
 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
@@ -140,8 +144,12 @@ min_width::
        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+ (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::
@@ -178,6 +186,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*:
@@ -195,3 +214,28 @@ 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 occured
+button::
+       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
+}
+------------------------------------------