Merge pull request #3144 from DebianWall/guaketilda

[i3/i3] / docs / i3bar-protocol

diff --git a/docs/i3bar-protocol b/docs/i3bar-protocol
index 29ce571346985f499b1215bace0ea01f979547d2..cf86531cc5f399774e983770719245729693c17a 100644 (file)
--- 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.
 
 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.
 
 Before describing the protocol, let’s cover why JSON is a building block of
 this protocol.


@@ -45,14 +45,14 @@ to provide the correct version. The header block is terminated by a newline and
 consists of a single JSON hash:
 
 *Minimal example*:
 consists of a single JSON hash:
 
 *Minimal example*:

-----------------
+------------------------------

 { "version": 1 }
 { "version": 1 }

-----------------
+------------------------------

 
 *All features example*:
 
 *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}+,
 byte-for-byte.)
 
 (Note that before i3 v4.3 the precise format had to be +{"version":1}+,
 byte-for-byte.)


@@ -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
 
 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
 
 
 === Header in detail
 


@@ -110,13 +110,15 @@ 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.
        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::
 
 === 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
 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 +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.
        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
 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


@@ -144,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.
        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
 
 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


@@ -158,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*:
 An example of a block which uses all possible entries follows:
 
 *Example*:


@@ -166,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",
  "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",
  "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

 }
 ------------------------------------------
 }
 ------------------------------------------