X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc.html;h=350483e33f37c8463906ac6da522aa4867504de3;hb=8924ec1339061840e02c918d36c86dd179a86aac;hp=88b13b7d331aa0684a1998c4feddc2e169896a33;hpb=7423f7cfe6cc48d000918b9bdf42d387b94adffd;p=i3%2Fi3.github.io diff --git a/docs/ipc.html b/docs/ipc.html index 88b13b7..350483e 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -2,15 +2,15 @@ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> - + - + i3: IPC interface (interprocess communication) @@ -22,16 +22,17 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
+

All i3 utilities, like i3-msg and i3-input will read the I3_SOCKET_PATH +X11 property, stored on the X11 root window.

+
+ + + +
+
Warning
+		 +
Use an existing library!
There are existing libraries for many languages. You can have a look at +[libraries] or search the web if your language of choice is not mentioned. +Usually, it is not necessary to implement low-level communication with i3 +directly.
+
@@ -58,7 +75,8 @@ snippet illustrates this in Perl:

use IO::Socket::UNIX;
-my $sock = IO::Socket::UNIX->new(Peer => '~/.i3/ipc.sock');
+chomp(my $path = qx(i3 --get-socketpath)); +my $sock = IO::Socket::UNIX->new(Peer => $path);
@@ -74,46 +92,94 @@ they are in native byte order).

The magic string currently is "i3-ipc" and will only be changed when a change in the IPC API is done which breaks compatibility (we hope that we don’t need to do that).

-

Currently implemented message types are the following:

-
-
-COMMAND (0) -
-
-

- The payload of the message is a command for i3 (like the commands you - can bind to keys in the configuration file) and will be executed - directly after receiving it. There is no reply to this message. -

-
-
-GET_WORKSPACES (1) -
-
-

- Gets the current workspaces. The reply will be a JSON-encoded list of - workspaces (see the reply section). -

-
-
-SUBSCRIBE (2) -
-
-

- Subscribes your connection to certain events. See [events] for a - description of this message and the concept of events. -

-
-
-GET_OUTPUTS (3) -
-
-

- Gets the current outputs. The reply will be a JSON-encoded list of outputs - (see the reply section). -

-
-
+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Currently implemented message types
Type (numeric) Type (name) Reply type Purpose

0

RUN_COMMAND

COMMAND

Run the payload as an i3 command (like the commands you can bind to keys).

1

GET_WORKSPACES

WORKSPACES

Get the list of current workspaces.

2

SUBSCRIBE

SUBSCRIBE

Subscribe this IPC connection to the event types specified in the message payload. See [events].

3

GET_OUTPUTS

OUTPUTS

Get the list of current outputs.

4

GET_TREE

TREE

Get the i3 layout tree.

5

GET_MARKS

MARKS

Gets the names of all currently set marks.

6

GET_BAR_CONFIG

BAR_CONFIG

Gets the specified bar configuration or the names of all bar configurations if payload is empty.

7

GET_VERSION

VERSION

Gets the i3 version.

8

GET_BINDING_MODES

BINDING_MODES

Gets the names of all currently configured binding modes.

9

GET_CONFIG

CONFIG

Returns the last loaded i3 config.

10

SEND_TICK

TICK

Sends a tick event with the specified payload.

+

So, a typical message could look like this:

@@ -123,7 +189,7 @@ GET_OUTPUTS (3) 
00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
-00000010  69 74 0a                                          |it.|
+00000010 69 74 |it|

To generate and send such a message, you could use the following code in Perl:

@@ -160,11 +226,11 @@ COMMAND (0)

- Confirmation/Error code for the COMMAND message. + Confirmation/Error code for the RUN_COMMAND message.

-GET_WORKSPACES (1) +WORKSPACES (1)

@@ -180,27 +246,84 @@ SUBSCRIBE (2)

-GET_OUTPUTS (3) +OUTPUTS (3)

Reply to the GET_OUTPUTS message.

+
+TREE (4) +
+
+

+ Reply to the GET_TREE message. +

+
+
+MARKS (5) +
+
+

+ Reply to the GET_MARKS message. +

+
+
+BAR_CONFIG (6) +
+
+

+ Reply to the GET_BAR_CONFIG message. +

+
+
+VERSION (7) +
+
+

+ Reply to the GET_VERSION message. +

+
+
+BINDING_MODES (8) +
+
+

+ Reply to the GET_BINDING_MODES message. +

+
+
+GET_CONFIG (9) +
+
+

+ Reply to the GET_CONFIG message. +

+
+
+TICK (10) +
+
+

+ Reply to the SEND_TICK message. +

+

3.2. COMMAND reply

-

The reply consists of a single serialized map. At the moment, the only -property is success (bool), but this will be expanded in future versions.

+

The reply consists of a list of serialized maps for each command that was +parsed. Each has the property success (bool) and may also include a +human-readable error message in the property error (string).

Example:

-
{ "success": true }
+
[{ "success": true }]
-

3.3. GET_WORKSPACES reply

+

3.3. WORKSPACES reply

The reply consists of a serialized list of workspaces. Each workspace has the following properties:

@@ -210,7 +333,7 @@ num (integer)

The logical number of the workspace. Corresponds to the command - to switch to this workspace. + to switch to this workspace. For named workspaces, this will be -1.

@@ -313,7 +436,7 @@ default) or whether a JSON parse error occurred.

-

3.5. GET_OUTPUTS reply

+

3.5. OUTPUTS reply

The reply consists of a serialized list of outputs. Each output has the following properties:

@@ -334,12 +457,20 @@ active (boolean)

-current_workspace (integer) +primary (boolean) +
+
+

+ Whether this output is currently the primary output. +

+
+
+current_workspace (string)

- The current workspace which is visible on this output. null if the - output is not active. + The name of the current workspace that is visible on this output. null if + the output is not active.

@@ -359,7 +490,7 @@ rect (map) { "name": "LVDS1", "active": true, - "current_workspace": 4, + "current_workspace": "4", "rect": { "x": 0, "y": 0, @@ -370,154 +501,1350 @@ rect (map) { "name": "VGA1", "active": true, - "current_workspace": 1, + "current_workspace": "1", "rect": { "x": 1280, "y": 0, "width": 1280, "height": 1024 - }, + } } ]
- - -
-

4. Events

-
-

To get informed when certain things happen in i3, clients can subscribe to -events. Events consist of a name (like "workspace") and an event reply type -(like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format -as replies to specific commands. However, the highest bit of the message type -is set to 1 to indicate that this is an event reply instead of a normal reply.

-

Caveat: As soon as you subscribe to an event, it is not guaranteed any longer -that the requests to i3 are processed in order. This means, the following -situation can happen: You send a GET_WORKSPACES request but you receive a -"workspace" event before receiving the reply to GET_WORKSPACES. If your -program does not want to cope which such kinds of race conditions (an -event based library may not have a problem here), I suggest you create a -separate connection to receive events.

-
-

4.1. Subscribing to events

-

By sending a message of type SUBSCRIBE with a JSON-encoded array as payload -you can register to an event.

-

Example:

-
-
-
type: SUBSCRIBE
-payload: [ "workspace", "focus" ]
-
-
-

4.2. Available events

-

The numbers in parenthesis is the event type (keep in mind that you need to -strip the highest bit first).

+

3.6. TREE reply

+

The reply consists of a serialized tree. Each node in the tree (representing +one container) has at least the properties listed below. While the nodes might +have more properties, please do not use any properties which are not documented +here. They are not yet finalized and will probably change!

-workspace (0) +id (integer)

- Sent when the user switches to a different workspace, when a new - workspace is initialized or when a workspace is removed (because the - last client vanished). + The internal ID (actually a C pointer value) of this container. Do not + make any assumptions about it. You can use it to (re-)identify and + address containers when talking to i3.

-output (1) +name (string)

- Sent when RandR issues a change notification (of either screens, - outputs, CRTCs or output properties). + The internal name of this container. For all containers which are part + of the tree structure down to the workspace contents, this is set to a + nice human-readable name of the container. + For containers that have an X11 window, the content is the title + (_NET_WM_NAME property) of that window. + For all other containers, the content is not defined (yet).

-
-

Example:

-
-
-
# the appropriate 4 bytes read from the socket are stored in $input
-
-# unpack a 32-bit unsigned integer
-my $message_type = unpack("L", $input);
-
-# check if the highest bit is 1
-my $is_event = (($message_type >> 31) == 1);
-
-# use the other bits
-my $event_type = ($message_type & 0x7F);
-
-if ($is_event) {
-  say "Received event of type $event_type";
-}
-
-
-
-

4.3. workspace event

-

This event consists of a single serialized map containing a property -change (string) which indicates the type of the change ("focus", "init", -"empty", "urgent").

-

Example:

-
-
-
{ "change": "focus" }
-
-
-
-

4.4. output event

-

This event consists of a single serialized map containing a property -change (string) which indicates the type of the change (currently only -"unspecified").

-

Example:

-
-
-
{ "change": "unspecified" }
-
-
-
-
-
-

5. See also

-
-

For some languages, libraries are available (so you don’t have to implement -all this on your own). This list names some (if you wrote one, please let me -know):

-
-C +type (string)

- i3 includes a headerfile i3/ipc.h which provides you all constants. - However, there is no library yet. + Type of this container. Can be one of "root", "output", "con", + "floating_con", "workspace" or "dockarea".

-Ruby +border (string)

- http://github.com/badboy/i3-ipc + Can be either "normal", "none" or "pixel", depending on the + container’s border style.

-Perl +current_border_width (integer)

- http://search.cpan.org/search?query=AnyEvent::I3 + Number of pixels of the border width.

-Python +layout (string) +
+
+

+ Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or + "output". + Other values might be possible in the future, should we add new + layouts. +

+
+
+orientation (string) +
+
+

+ Can be either "none" (for non-split containers), "horizontal" or + "vertical". + THIS FIELD IS OBSOLETE. It is still present, but your code should not + use it. Instead, rely on the layout field. +

+
+
+percent (float) +
+
+

+ The percentage which this container takes in its parent. A value of + null means that the percent property does not make sense for this + container, for example for the root container. +

+
+
+rect (map) +
+
+

+ The absolute display coordinates for this container. Display + coordinates means that when you have two 1600x1200 monitors on a single + X11 Display (the standard way), the coordinates of the first window on + the second monitor are { "x": 1600, "y": 0, "width": 1600, "height": + 1200 }. +

+
+
+window_rect (map) +
+
+

+ The coordinates of the actual client window inside its container. + These coordinates are relative to the container and do not include the + window decoration (which is actually rendered on the parent container). + So, when using the default layout, you will have a 2 pixel border on + each side, making the window_rect { "x": 2, "y": 0, "width": 632, + "height": 366 } (for example). +

+
+
+deco_rect (map) +
+
+

+ The coordinates of the window decoration inside its container. These + coordinates are relative to the container and do not include the actual + client window. +

+
+
+geometry (map) +
+
+

+ The original geometry the window specified when i3 mapped it. Used when + switching a window to floating mode, for example. +

+
+
+window (integer) +
+
+

+ The X11 window ID of the actual client window inside this container. + This field is set to null for split containers or otherwise empty + containers. This ID corresponds to what xwininfo(1) and other + X11-related tools display (usually in hex). +

+
+
+urgent (bool) +
+
+

+ Whether this container (window, split container, floating container or + workspace) has the urgency hint set, directly or indirectly. All parent + containers up until the workspace container will be marked urgent if they + have at least one urgent child. +

+
+
+focused (bool) +
+
+

+ Whether this container is currently focused. +

+
+
+focus (array of integer) +
+
+

+ List of child node IDs (see nodes, floating_nodes and id) in focus + order. Traversing the tree by following the first entry in this array + will result in eventually reaching the one node with focused set to + true. +

+
+
+nodes (array of node) +
+
+

+ The tiling (i.e. non-floating) child containers of this node. +

+
+
+floating_nodes (array of node)

- http://github.com/thepub/i3ipc + The floating child containers of this node. Only non-empty on nodes with + type workspace.

+

Please note that in the following example, I have left out some keys/values +which are not relevant for the type of the node. Otherwise, the example would +be by far too long (it already is quite long, despite showing only 1 window and +one dock window).

+

It is useful to have an overview of the structure before taking a look at the +JSON dump:

+
    +
  • +

    +root +

    +
      +
    • +

      +LVDS1 +

      +
        +
      • +

        +topdock +

        +
        • +
      • +

        +content +

        +
          +
        • +

          +workspace 1 +

          +
            +
          • +

            +window 1 +

            +
            • +
          +
          • +
        +
        • +
      • +

        +bottomdock +

        +
          +
        • +

          +dock window 1 +

          +
          • +
        +
        • +
      +
      • +
    • +

      +VGA1 +

      +
      • +
    +
    • +
+

Example:

+
+
+
{
+ "id": 6875648,
+ "name": "root",
+ "rect": {
+   "x": 0,
+   "y": 0,
+   "width": 1280,
+   "height": 800
+ },
+ "nodes": [
+
+   {
+    "id": 6878320,
+    "name": "LVDS1",
+    "layout": "output",
+    "rect": {
+      "x": 0,
+      "y": 0,
+      "width": 1280,
+      "height": 800
+    },
+    "nodes": [
+
+      {
+       "id": 6878784,
+       "name": "topdock",
+       "layout": "dockarea",
+       "orientation": "vertical",
+       "rect": {
+         "x": 0,
+         "y": 0,
+         "width": 1280,
+         "height": 0
+       }
+      },
+
+      {
+       "id": 6879344,
+       "name": "content",
+       "rect": {
+         "x": 0,
+         "y": 0,
+         "width": 1280,
+         "height": 782
+       },
+       "nodes": [
+
+         {
+          "id": 6880464,
+          "name": "1",
+          "orientation": "horizontal",
+          "rect": {
+            "x": 0,
+            "y": 0,
+            "width": 1280,
+            "height": 782
+          },
+          "floating_nodes": [],
+          "nodes": [
+
+            {
+             "id": 6929968,
+             "name": "#aa0000",
+             "border": "normal",
+             "percent": 1,
+             "rect": {
+               "x": 0,
+               "y": 18,
+               "width": 1280,
+               "height": 782
+             }
+            }
+
+          ]
+         }
+
+       ]
+      },
+
+      {
+       "id": 6880208,
+       "name": "bottomdock",
+       "layout": "dockarea",
+       "orientation": "vertical",
+       "rect": {
+         "x": 0,
+         "y": 782,
+         "width": 1280,
+         "height": 18
+       },
+       "nodes": [
+
+         {
+          "id": 6931312,
+          "name": "#00aa00",
+          "percent": 1,
+          "rect": {
+            "x": 0,
+            "y": 782,
+            "width": 1280,
+            "height": 18
+          }
+         }
+
+       ]
+      }
+    ]
+   }
+ ]
+}
+
+
+
+

3.7. MARKS reply

+

The reply consists of a single array of strings for each container that has a +mark. A mark can only be set on one container, so the array is unique. +The order of that array is undefined.

+

If no window has a mark the response will be the empty array [].

+
+
+

3.8. BAR_CONFIG reply

+

This can be used by third-party workspace bars (especially i3bar, but others +are free to implement compatible alternatives) to get the bar block +configuration from i3.

+

Depending on the input, the reply is either:

+
+
+empty input +
+
+

+ An array of configured bar IDs +

+
+
+Bar ID +
+
+

+ A JSON map containing the configuration for the specified bar. +

+
+
+

Each bar configuration has the following properties:

+
+
+id (string) +
+
+

+ The ID for this bar. Included in case you request multiple + configurations and want to differentiate the different replies. +

+
+
+mode (string) +
+
+

+ Either dock (the bar sets the dock window type) or hide (the bar + does not show unless a specific key is pressed). +

+
+
+position (string) +
+
+

+ Either bottom or top at the moment. +

+
+
+status_command (string) +
+
+

+ Command which will be run to generate a statusline. Each line on stdout + of this command will be displayed in the bar. At the moment, no + formatting is supported. +

+
+
+font (string) +
+
+

+ The font to use for text on the bar. +

+
+
+workspace_buttons (boolean) +
+
+

+ Display workspace buttons or not? Defaults to true. +

+
+
+binding_mode_indicator (boolean) +
+
+

+ Display the mode indicator or not? Defaults to true. +

+
+
+verbose (boolean) +
+
+

+ Should the bar enable verbose output for debugging? Defaults to false. +

+
+
+colors (map) +
+
+

+ Contains key/value pairs of colors. Each value is a color code in hex, + formatted #rrggbb (like in HTML). +

+
+
+

The following colors can be configured at the moment:

+
+
+background +
+
+

+ Background color of the bar. +

+
+
+statusline +
+
+

+ Text color to be used for the statusline. +

+
+
+separator +
+
+

+ Text color to be used for the separator. +

+
+
+focused_background +
+
+

+ Background color of the bar on the currently focused monitor output. +

+
+
+focused_statusline +
+
+

+ Text color to be used for the statusline on the currently focused + monitor output. +

+
+
+focused_separator +
+
+

+ Text color to be used for the separator on the currently focused + monitor output. +

+
+
+focused_workspace_text/focused_workspace_bg/focused_workspace_border +
+
+

+ Text/background/border color for a workspace button when the workspace + has focus. +

+
+
+active_workspace_text/active_workspace_bg/active_workspace_border +
+
+

+ Text/background/border color for a workspace button when the workspace + is active (visible) on some output, but the focus is on another one. + You can only tell this apart from the focused workspace when you are + using multiple monitors. +

+
+
+inactive_workspace_text/inactive_workspace_bg/inactive_workspace_border +
+
+

+ Text/background/border color for a workspace button when the workspace + does not have focus and is not active (visible) on any output. This + will be the case for most workspaces. +

+
+
+urgent_workspace_text/urgent_workspace_bg/urgent_workspace_border +
+
+

+ Text/background/border color for workspaces which contain at least one + window with the urgency hint set. +

+
+
+binding_mode_text/binding_mode_bg/binding_mode_border +
+
+

+ Text/background/border color for the binding mode indicator. +

+
+
+

Example of configured bars:

+
+
+
["bar-bxuqzf"]
+
+

Example of bar configuration:

+
+
+
{
+ "id": "bar-bxuqzf",
+ "mode": "dock",
+ "position": "bottom",
+ "status_command": "i3status",
+ "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
+ "workspace_buttons": true,
+ "binding_mode_indicator": true,
+ "verbose": false,
+ "colors": {
+   "background": "#c0c0c0",
+   "statusline": "#00ff00",
+   "focused_workspace_text": "#ffffff",
+   "focused_workspace_bg": "#000000"
+ }
+}
+
+
+
+

3.9. VERSION reply

+

The reply consists of a single JSON dictionary with the following keys:

+
+
+major (integer) +
+
+

+ The major version of i3, such as 4. +

+
+
+minor (integer) +
+
+

+ The minor version of i3, such as 2. Changes in the IPC interface (new + features) will only occur with new minor (or major) releases. However, + bugfixes might be introduced in patch releases, too. +

+
+
+patch (integer) +
+
+

+ The patch version of i3, such as 1 (when the complete version is + 4.2.1). For versions such as 4.2, patch will be set to 0. +

+
+
+human_readable (string) +
+
+

+ A human-readable version of i3 containing the precise git version, + build date and branch name. When you need to display the i3 version to + your users, use the human-readable version whenever possible (since + this is what i3 --version displays, too). +

+
+
+loaded_config_file_name (string) +
+
+

+ The current config path. +

+
+
+

Example:

+
+
+
{
+   "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
+   "loaded_config_file_name" : "/home/hwangcc23/.i3/config",
+   "minor" : 2,
+   "patch" : 0,
+   "major" : 4
+}
+
+
+
+

3.10. BINDING_MODES reply

+

The reply consists of an array of all currently configured binding modes.

+

Example:

+
+
+
["default", "resize"]
+
+
+
+

3.11. CONFIG reply

+

The config reply is a map which currently only contains the "config" member, +which is a string containing the config file as loaded by i3 most recently.

+

Example:

+
+
+
{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }
+
+
+
+

3.12. TICK reply

+

The reply is a map containing the "success" member. After the reply was +received, the tick event has been written to all IPC connections which subscribe +to tick events. UNIX sockets are usually buffered, but you can be certain that +once you receive the tick event you just triggered, you must have received all +events generated prior to the SEND_TICK message (happened-before relation).

+

Example:

+
+
+
{ "success": true }
+
+
+
+ +
+

4. Events

+
+

To get informed when certain things happen in i3, clients can subscribe to +events. Events consist of a name (like "workspace") and an event reply type +(like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format +as replies to specific commands. However, the highest bit of the message type +is set to 1 to indicate that this is an event reply instead of a normal reply.

+

Caveat: As soon as you subscribe to an event, it is not guaranteed any longer +that the requests to i3 are processed in order. This means, the following +situation can happen: You send a GET_WORKSPACES request but you receive a +"workspace" event before receiving the reply to GET_WORKSPACES. If your +program does not want to cope which such kinds of race conditions (an +event based library may not have a problem here), I suggest you create a +separate connection to receive events.

+
+

4.1. Subscribing to events

+

By sending a message of type SUBSCRIBE with a JSON-encoded array as payload +you can register to an event.

+

Example:

+
+
+
type: SUBSCRIBE
+payload: [ "workspace", "output" ]
+
+
+
+

4.2. Available events

+

The numbers in parenthesis is the event type (keep in mind that you need to +strip the highest bit first).

+
+
+workspace (0) +
+
+

+ Sent when the user switches to a different workspace, when a new + workspace is initialized or when a workspace is removed (because the + last client vanished). +

+
+
+output (1) +
+
+

+ Sent when RandR issues a change notification (of either screens, + outputs, CRTCs or output properties). +

+
+
+mode (2) +
+
+

+ Sent whenever i3 changes its binding mode. +

+
+
+window (3) +
+
+

+ Sent when a client’s window is successfully reparented (that is when i3 + has finished fitting it into a container), when a window received input + focus or when certain properties of the window have changed. +

+
+
+barconfig_update (4) +
+
+

+ Sent when the hidden_state or mode field in the barconfig of any bar + instance was updated and when the config is reloaded. +

+
+
+binding (5) +
+
+

+ Sent when a configured command binding is triggered with the keyboard or + mouse +

+
+
+shutdown (6) +
+
+

+ Sent when the ipc shuts down because of a restart or exit by user command +

+
+
+tick (7) +
+
+

+ Sent when the ipc client subscribes to the tick event (with "first": + true) or when any ipc client sends a SEND_TICK message (with "first": + false). +

+
+
+

Example:

+
+
+
# the appropriate 4 bytes read from the socket are stored in $input
+
+# unpack a 32-bit unsigned integer
+my $message_type = unpack("L", $input);
+
+# check if the highest bit is 1
+my $is_event = (($message_type >> 31) == 1);
+
+# use the other bits
+my $event_type = ($message_type & 0x7F);
+
+if ($is_event) {
+  say "Received event of type $event_type";
+}
+
+
+
+

4.3. workspace event

+

This event consists of a single serialized map containing a property +change (string) which indicates the type of the change ("focus", "init", +"empty", "urgent", "reload", "rename", "restored", "move"). A +current (object) property will be present with the affected workspace +whenever the type of event affects a workspace (otherwise, it will be +null).

+

When the change is "focus", an old (object) property will be present with the +previous workspace. When the first switch occurs (when i3 focuses the +workspace visible at the beginning) there is no previous workspace, and the +old property will be set to null. Also note that if the previous is empty +it will get destroyed when switching, but will still be present in the "old" +property.

+

Example:

+
+
+
{
+ "change": "focus",
+ "current": {
+  "id": 28489712,
+  "type": "workspace",
+  ...
+ }
+ "old": {
+  "id": 28489715,
+  "type": "workspace",
+  ...
+ }
+}
+
+
+
+

4.4. output event

+

This event consists of a single serialized map containing a property +change (string) which indicates the type of the change (currently only +"unspecified").

+

Example:

+
+
+
{ "change": "unspecified" }
+
+
+
+

4.5. mode event

+

This event consists of a single serialized map containing a property +change (string) which holds the name of current mode in use. The name +is the same as specified in config when creating a mode. The default +mode is simply named default. It contains a second property, pango_markup, which +defines whether pango markup shall be used for displaying this mode.

+

Example:

+
+
+
{
+  "change": "default",
+  "pango_markup": true
+}
+
+
+
+

4.6. window event

+

This event consists of a single serialized map containing a property +change (string) which indicates the type of the change

+
    +
  • +

    +new – the window has become managed by i3 +

    +
    • +
  • +

    +close – the window has closed +

    +
    • +
  • +

    +focus – the window has received input focus +

    +
    • +
  • +

    +title – the window’s title has changed +

    +
    • +
  • +

    +fullscreen_mode – the window has entered or exited fullscreen mode +

    +
    • +
  • +

    +move – the window has changed its position in the tree +

    +
    • +
  • +

    +floating – the window has transitioned to or from floating +

    +
    • +
  • +

    +urgent – the window has become urgent or lost its urgent status +

    +
    • +
  • +

    +mark – a mark has been added to or removed from the window +

    +
    • +
+

Additionally a container (object) field will be present, which consists +of the window’s parent container. Be aware that for the "new" event, the +container will hold the initial name of the newly reparented window (e.g. +if you run urxvt with a shell that changes the title, you will still at +this point get the window title as "urxvt").

+

Example:

+
+
+
{
+ "change": "new",
+ "container": {
+  "id": 35569536,
+  "type": "con",
+  ...
+ }
+}
+
+
+
+

4.7. barconfig_update event

+

This event consists of a single serialized map reporting on options from the +barconfig of the specified bar_id that were updated in i3. This event is the +same as a GET_BAR_CONFIG reply for the bar with the given id.

+
+
+

4.8. binding event

+

This event consists of a single serialized map reporting on the details of a +binding that ran a command because of user input. The change (string) field +indicates what sort of binding event was triggered (right now it will always be +"run" but may be expanded in the future).

+

The binding (object) field contains details about the binding that was run:

+
+
+command (string) +
+
+

+ The i3 command that is configured to run for this binding. +

+
+
+event_state_mask (array of strings) +
+
+

+ The group and modifier keys that were configured with this binding. +

+
+
+input_code (integer) +
+
+

+ If the binding was configured with bindcode, this will be the key code + that was given for the binding. If the binding is a mouse binding, it will be + the number of the mouse button that was pressed. Otherwise it will be 0. +

+
+
+symbol (string or null) +
+
+

+ If this is a keyboard binding that was configured with bindsym, this + field will contain the given symbol. Otherwise it will be null. +

+
+
+input_type (string) +
+
+

+ This will be "keyboard" or "mouse" depending on whether or not this was + a keyboard or a mouse binding. +

+
+
+

Example:

+
+
+
{
+ "change": "run",
+ "binding": {
+  "command": "nop",
+  "event_state_mask": [
+    "shift",
+    "ctrl"
+  ],
+  "input_code": 0,
+  "symbol": "t",
+  "input_type": "keyboard"
+ }
+}
+
+
+
+

4.9. shutdown event

+

This event is triggered when the connection to the ipc is about to shutdown +because of a user action such as a restart or exit command. The change +(string) field indicates why the ipc is shutting down. It can be either +"restart" or "exit".

+

Example:

+
+
+
{
+ "change": "restart"
+}
+
+
+
+

4.10. tick event

+

This event is triggered by a subscription to tick events or by a SEND_TICK +message.

+

Example (upon subscription):

+
+
+
{
+ "first": true,
+ "payload": ""
+}
+
+

Example (upon SEND_TICK with a payload of arbitrary string):

+
+
+
{
+ "first": false,
+ "payload": "arbitrary string"
+}
+
+
+
+
+
+

5. See also (existing libraries)

+
+

For some languages, libraries are available (so you don’t have to implement +all this on your own). This list names some (if you wrote one, please let me +know):

+
+
+C +
+
+
+
+
+C++ +
+
+
+
+
+Go +
+
+
+
+
+JavaScript +
+
+
+
+
+Lua +
+
+
+
+
+Perl +
+
+
+
+
+Python +
+
+
+
+
+Ruby +
+
+
+
+
+Rust +
+
+
+
+
+OCaml +
+
+
+
+
+
+
+
+

6. Appendix A: Detecting byte order in memory-safe languages

+
+

Some programming languages such as Go don’t offer a way to serialize data in the +native byte order of the machine they’re running on without resorting to tricks +involving the unsafe package.

+

The following technique can be used (and will not be broken by changes to i3) to +detect the byte order i3 is using:

+
    +
  1. +

    +The byte order dependent fields of an IPC message are message type and + payload length. +

    +
      +
    • +

      +The message type RUN_COMMAND (0) is the same in big and little endian, so + we can use it in either byte order to elicit a reply from i3. +

      +
      • +
    • +

      +The payload length 65536 + 256 (0x00 01 01 00) is the same in big and + little endian, and also small enough to not worry about memory allocations + of that size. We must use payloads of length 65536 + 256 in every message + we send, so that i3 will be able to read the entire message regardless of + the byte order it uses. +

      +
      • +
    +
    2. +
  2. +

    +Send a big endian encoded message of type SUBSCRIBE (2) with payload [] + followed by 65536 + 256 - 2 SPACE (ASCII 0x20) bytes. +

    +
      +
    • +

      +If i3 is running in big endian, this message is treated as a noop, + resulting in a SUBSCRIBE reply with payload {"success":true} +
      [A small payload is important: that way, we circumvent dealing + with UNIX domain socket buffer sizes, whose size depends on the + implementation/operating system. Exhausting such a buffer results in an i3 + deadlock unless you concurrently read and write, which — depending on the + programming language — makes the technique much more complicated.]
      . +

      +
      • +
    • +

      +If i3 is running in little endian, this message is read in its entirety due + to the byte order independent payload length, then + silently + discarded due to the unknown message type. +

      +
      • +
    +
    3. +
  3. +

    +Send a byte order independent message, i.e. type RUN_COMMAND (0) with + payload nop byte order detection. padding:, padded to 65536 + 256 bytes + with a (ASCII 0x61) bytes. i3 will reply to this message with a reply of + type COMMAND (0). +

    +
      +
    • +

      +The human-readable prefix is in there to not confuse readers of the i3 log. +

      +
      • +
    • +

      +This messages serves as a synchronization primitive so that we know whether + i3 discarded the SUBSCRIBE message or didn’t answer it yet. +

      +
      • +
    +
    4. +
  4. +

    +Receive a message header from i3, decoding the message type as big endian. +

    +
      +
    • +

      +If the message’s reply type is COMMAND (0), i3 is running in little + endian (because the SUBSCRIBE message was discarded). Decode the message + payload length as little endian, receive the message payload. +

      +
      • +
    • +

      +If the message’s reply type is anything else, i3 is running in big endian + (because our big endian encoded SUBSCRIBE message was answered). Decode + the message payload length in big endian, receive the message + payload. Then, receive the pending COMMAND message reply in big endian. +

      +
      • +
    +
    5. +
  5. +

    +From here on out, send/receive all messages using the detected byte order. +

    +
    6. +
+

Find an example implementation of this technique in +https://github.com/i3/go-i3/blob/master/byteorder.go