git.sur5r.net Git - i3/i3.github.io/blob - _docs/ipc

   1 IPC interface (interprocess communication)
   2 ==========================================
   3 Michael Stapelberg <michael@i3wm.org>
   4 October 2014
   5
   6 This document describes how to interface with i3 from a separate process. This
   7 is useful for example to remote-control i3 (to write test cases for example) or
   8 to get various information like the current workspaces to implement an external
   9 workspace bar.
  10
  11 The method of choice for IPC in our case is a unix socket because it has very
  12 little overhead on both sides and is usually available without headaches in
  13 most languages. In the default configuration file, the ipc-socket gets created
  14 in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
  15 the PID of i3 and XXXXXX is a string of random characters from the portable
  16 filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
  17 calling +i3 --get-socketpath+.
  18
  19 All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
  20 X11 property, stored on the X11 root window.
  21
  22 [WARNING]
  23 .Use an existing library!
  24 There are existing libraries for many languages. You can have a look at
  25 <<libraries>> or search the web if your language of choice is not mentioned.
  26 Usually, it is not necessary to implement low-level communication with i3
  27 directly.
  28
  29 == Establishing a connection
  30
  31 To establish a connection, simply open the IPC socket. The following code
  32 snippet illustrates this in Perl:
  33
  34 -------------------------------------------------------------
  35 use IO::Socket::UNIX;
  36 chomp(my $path = qx(i3 --get-socketpath));
  37 my $sock = IO::Socket::UNIX->new(Peer => $path);
  38 -------------------------------------------------------------
  39
  40 == Sending messages to i3
  41
  42 To send a message to i3, you have to format in the binary message format which
  43 i3 expects. This format specifies a magic string in the beginning to ensure
  44 the integrity of messages (to prevent follow-up errors). Following the magic
  45 string comes the length of the payload of the message as 32-bit integer, and
  46 the type of the message as 32-bit integer (the integers are not converted, so
  47 they are in native byte order).
  48
  49 The magic string currently is "i3-ipc" and will only be changed when a change
  50 in the IPC API is done which breaks compatibility (we hope that we don’t need
  51 to do that).
  52
  53 Currently implemented message types are the following:
  54
  55 COMMAND (0)::
  56         The payload of the message is a command for i3 (like the commands you
  57         can bind to keys in the configuration file) and will be executed
  58         directly after receiving it.
  59 GET_WORKSPACES (1)::
  60         Gets the current workspaces. The reply will be a JSON-encoded list of
  61         workspaces (see the reply section).
  62 SUBSCRIBE (2)::
  63         Subscribes your connection to certain events. See <<events>> for a
  64         description of this message and the concept of events.
  65 GET_OUTPUTS (3)::
  66         Gets the current outputs. The reply will be a JSON-encoded list of outputs
  67         (see the reply section).
  68 GET_TREE (4)::
  69         Gets the layout tree. i3 uses a tree as data structure which includes
  70         every container. The reply will be the JSON-encoded tree (see the reply
  71         section).
  72 GET_MARKS (5)::
  73         Gets a list of marks (identifiers for containers to easily jump to them
  74         later). The reply will be a JSON-encoded list of window marks (see
  75         reply section).
  76 GET_BAR_CONFIG (6)::
  77         Gets the configuration (as JSON map) of the workspace bar with the
  78         given ID. If no ID is provided, an array with all configured bar IDs is
  79         returned instead.
  80 GET_VERSION (7)::
  81         Gets the version of i3. The reply will be a JSON-encoded dictionary
  82         with the major, minor, patch and human-readable version.
  83 GET_BINDING_MODES (8)::
  84         Gets a list of currently configured binding modes.
  85
  86 So, a typical message could look like this:
  87 --------------------------------------------------
  88 "i3-ipc" <message length> <message type> <payload>
  89 --------------------------------------------------
  90
  91 Or, as a hexdump:
  92 ------------------------------------------------------------------------------
  93 00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
  94 00000010  69 74                                             |it|
  95 ------------------------------------------------------------------------------
  96
  97 To generate and send such a message, you could use the following code in Perl:
  98 ------------------------------------------------------------
  99 sub format_ipc_command {
 100     my ($msg) = @_;
 101     my $len;
 102     # Get the real byte count (vs. amount of characters)
 103     { use bytes; $len = length($msg); }
 104     return "i3-ipc" . pack("LL", $len, 0) . $msg;
 105 }
 106
 107 $sock->write(format_ipc_command("exit"));
 108 ------------------------------------------------------------------------------
 109
 110 == Receiving replies from i3
 111
 112 Replies from i3 usually consist of a simple string (the length of the string
 113 is the message_length, so you can consider them length-prefixed) which in turn
 114 contain the JSON serialization of a data structure. For example, the
 115 GET_WORKSPACES message returns an array of workspaces (each workspace is a map
 116 with certain attributes).
 117
 118 === Reply format
 119
 120 The reply format is identical to the normal message format. There also is
 121 the magic string, then the message length, then the message type and the
 122 payload.
 123
 124 The following reply types are implemented:
 125
 126 COMMAND (0)::
 127         Confirmation/Error code for the COMMAND message.
 128 WORKSPACES (1)::
 129         Reply to the GET_WORKSPACES message.
 130 SUBSCRIBE (2)::
 131         Confirmation/Error code for the SUBSCRIBE message.
 132 OUTPUTS (3)::
 133         Reply to the GET_OUTPUTS message.
 134 TREE (4)::
 135         Reply to the GET_TREE message.
 136 MARKS (5)::
 137         Reply to the GET_MARKS message.
 138 BAR_CONFIG (6)::
 139         Reply to the GET_BAR_CONFIG message.
 140 VERSION (7)::
 141         Reply to the GET_VERSION message.
 142 BINDING_MODES (8)::
 143         Reply to the GET_BINDING_MODES message.
 144
 145 === COMMAND reply
 146
 147 The reply consists of a list of serialized maps for each command that was
 148 parsed. Each has the property +success (bool)+ and may also include a
 149 human-readable error message in the property +error (string)+.
 150
 151 *Example:*
 152 -------------------
 153 [{ "success": true }]
 154 -------------------
 155
 156 === WORKSPACES reply
 157
 158 The reply consists of a serialized list of workspaces. Each workspace has the
 159 following properties:
 160
 161 num (integer)::
 162         The logical number of the workspace. Corresponds to the command
 163         to switch to this workspace. For named workspaces, this will be -1.
 164 name (string)::
 165         The name of this workspace (by default num+1), as changed by the
 166         user. Encoded in UTF-8.
 167 visible (boolean)::
 168         Whether this workspace is currently visible on an output (multiple
 169         workspaces can be visible at the same time).
 170 focused (boolean)::
 171         Whether this workspace currently has the focus (only one workspace
 172         can have the focus at the same time).
 173 urgent (boolean)::
 174         Whether a window on this workspace has the "urgent" flag set.
 175 rect (map)::
 176         The rectangle of this workspace (equals the rect of the output it
 177         is on), consists of x, y, width, height.
 178 output (string)::
 179         The video output this workspace is on (LVDS1, VGA1, …).
 180
 181 *Example:*
 182 -------------------
 183 [
 184  {
 185   "num": 0,
 186   "name": "1",
 187   "visible": true,
 188   "focused": true,
 189   "urgent": false,
 190   "rect": {
 191    "x": 0,
 192    "y": 0,
 193    "width": 1280,
 194    "height": 800
 195   },
 196   "output": "LVDS1"
 197  },
 198  {
 199   "num": 1,
 200   "name": "2",
 201   "visible": false,
 202   "focused": false,
 203   "urgent": false,
 204   "rect": {
 205    "x": 0,
 206    "y": 0,
 207    "width": 1280,
 208    "height": 800
 209   },
 210   "output": "LVDS1"
 211  }
 212 ]
 213 -------------------
 214
 215 === SUBSCRIBE reply
 216
 217 The reply consists of a single serialized map. The only property is
 218 +success (bool)+, indicating whether the subscription was successful (the
 219 default) or whether a JSON parse error occurred.
 220
 221 *Example:*
 222 -------------------
 223 { "success": true }
 224 -------------------
 225
 226 === OUTPUTS reply
 227
 228 The reply consists of a serialized list of outputs. Each output has the
 229 following properties:
 230
 231 name (string)::
 232         The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8.
 233 active (boolean)::
 234         Whether this output is currently active (has a valid mode).
 235 current_workspace (string)::
 236         The name of the current workspace that is visible on this output. +null+ if
 237         the output is not active.
 238 rect (map)::
 239         The rectangle of this output (equals the rect of the output it
 240         is on), consists of x, y, width, height.
 241
 242 *Example:*
 243 -------------------
 244 [
 245  {
 246   "name": "LVDS1",
 247   "active": true,
 248   "current_workspace": "4",
 249   "rect": {
 250    "x": 0,
 251    "y": 0,
 252    "width": 1280,
 253    "height": 800
 254   }
 255  },
 256  {
 257   "name": "VGA1",
 258   "active": true,
 259   "current_workspace": "1",
 260   "rect": {
 261    "x": 1280,
 262    "y": 0,
 263    "width": 1280,
 264    "height": 1024
 265   },
 266  }
 267 ]
 268 -------------------
 269
 270 === TREE reply
 271
 272 The reply consists of a serialized tree. Each node in the tree (representing
 273 one container) has at least the properties listed below. While the nodes might
 274 have more properties, please do not use any properties which are not documented
 275 here. They are not yet finalized and will probably change!
 276
 277 id (integer)::
 278         The internal ID (actually a C pointer value) of this container. Do not
 279         make any assumptions about it. You can use it to (re-)identify and
 280         address containers when talking to i3.
 281 name (string)::
 282         The internal name of this container. For all containers which are part
 283         of the tree structure down to the workspace contents, this is set to a
 284         nice human-readable name of the container.
 285         For containers that have an X11 window, the content is the title
 286         (_NET_WM_NAME property) of that window.
 287         For all other containers, the content is not defined (yet).
 288 type (string)::
 289         Type of this container. Can be one of "root", "output", "con",
 290         "floating_con", "workspace" or "dockarea".
 291 border (string)::
 292         Can be either "normal", "none" or "pixel", depending on the
 293         container’s border style.
 294 current_border_width (integer)::
 295         Number of pixels of the border width.
 296 layout (string)::
 297         Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or
 298         "output".
 299         Other values might be possible in the future, should we add new
 300         layouts.
 301 orientation (string)::
 302         Can be either "none" (for non-split containers), "horizontal" or
 303         "vertical".
 304         THIS FIELD IS OBSOLETE. It is still present, but your code should not
 305         use it. Instead, rely on the layout field.
 306 percent (float)::
 307         The percentage which this container takes in its parent. A value of
 308         +null+ means that the percent property does not make sense for this
 309         container, for example for the root container.
 310 rect (map)::
 311         The absolute display coordinates for this container. Display
 312         coordinates means that when you have two 1600x1200 monitors on a single
 313         X11 Display (the standard way), the coordinates of the first window on
 314         the second monitor are +{ "x": 1600, "y": 0, "width": 1600, "height":
 315         1200 }+.
 316 window_rect (map)::
 317         The coordinates of the *actual client window* inside its container.
 318         These coordinates are relative to the container and do not include the
 319         window decoration (which is actually rendered on the parent container).
 320         So, when using the +default+ layout, you will have a 2 pixel border on
 321         each side, making the window_rect +{ "x": 2, "y": 0, "width": 632,
 322         "height": 366 }+ (for example).
 323 deco_rect (map)::
 324         The coordinates of the *window decoration* inside its container. These
 325         coordinates are relative to the container and do not include the actual
 326         client window.
 327 geometry (map)::
 328         The original geometry the window specified when i3 mapped it. Used when
 329         switching a window to floating mode, for example.
 330 window (integer)::
 331         The X11 window ID of the *actual client window* inside this container.
 332         This field is set to null for split containers or otherwise empty
 333         containers. This ID corresponds to what xwininfo(1) and other
 334         X11-related tools display (usually in hex).
 335 urgent (bool)::
 336         Whether this container (window or workspace) has the urgency hint set.
 337 focused (bool)::
 338         Whether this container is currently focused.
 339
 340 Please note that in the following example, I have left out some keys/values
 341 which are not relevant for the type of the node. Otherwise, the example would
 342 be by far too long (it already is quite long, despite showing only 1 window and
 343 one dock window).
 344
 345 It is useful to have an overview of the structure before taking a look at the
 346 JSON dump:
 347
 348 * root
 349 ** LVDS1
 350 *** topdock
 351 *** content
 352 **** workspace 1
 353 ***** window 1
 354 *** bottomdock
 355 **** dock window 1
 356 ** VGA1
 357
 358 *Example:*
 359 -----------------------
 360 {
 361  "id": 6875648,
 362  "name": "root",
 363  "rect": {
 364    "x": 0,
 365    "y": 0,
 366    "width": 1280,
 367    "height": 800
 368  },
 369  "nodes": [
 370
 371    {
 372     "id": 6878320,
 373     "name": "LVDS1",
 374     "layout": "output",
 375     "rect": {
 376       "x": 0,
 377       "y": 0,
 378       "width": 1280,
 379       "height": 800
 380     },
 381     "nodes": [
 382
 383       {
 384        "id": 6878784,
 385        "name": "topdock",
 386        "layout": "dockarea",
 387        "orientation": "vertical",
 388        "rect": {
 389          "x": 0,
 390          "y": 0,
 391          "width": 1280,
 392          "height": 0
 393        },
 394       },
 395
 396       {
 397        "id": 6879344,
 398        "name": "content",
 399        "rect": {
 400          "x": 0,
 401          "y": 0,
 402          "width": 1280,
 403          "height": 782
 404        },
 405        "nodes": [
 406
 407          {
 408           "id": 6880464,
 409           "name": "1",
 410           "orientation": "horizontal",
 411           "rect": {
 412             "x": 0,
 413             "y": 0,
 414             "width": 1280,
 415             "height": 782
 416           },
 417           "floating_nodes": [],
 418           "nodes": [
 419
 420             {
 421              "id": 6929968,
 422              "name": "#aa0000",
 423              "border": "normal",
 424              "percent": 1,
 425              "rect": {
 426                "x": 0,
 427                "y": 18,
 428                "width": 1280,
 429                "height": 782
 430              }
 431             }
 432
 433           ]
 434          }
 435
 436        ]
 437       },
 438
 439       {
 440        "id": 6880208,
 441        "name": "bottomdock",
 442        "layout": "dockarea",
 443        "orientation": "vertical",
 444        "rect": {
 445          "x": 0,
 446          "y": 782,
 447          "width": 1280,
 448          "height": 18
 449        },
 450        "nodes": [
 451
 452          {
 453           "id": 6931312,
 454           "name": "#00aa00",
 455           "percent": 1,
 456           "rect": {
 457             "x": 0,
 458             "y": 782,
 459             "width": 1280,
 460             "height": 18
 461           }
 462          }
 463
 464        ]
 465       }
 466     ]
 467    }
 468  ]
 469 }
 470 ------------------------
 471
 472 === MARKS reply
 473
 474 The reply consists of a single array of strings for each container that has a
 475 mark. A mark can only be set on one container, so the array is unique.
 476 The order of that array is undefined.
 477
 478 If no window has a mark the response will be the empty array [].
 479
 480 === BAR_CONFIG reply
 481
 482 This can be used by third-party workspace bars (especially i3bar, but others
 483 are free to implement compatible alternatives) to get the +bar+ block
 484 configuration from i3.
 485
 486 Depending on the input, the reply is either:
 487
 488 empty input::
 489         An array of configured bar IDs
 490 Bar ID::
 491         A JSON map containing the configuration for the specified bar.
 492
 493 Each bar configuration has the following properties:
 494
 495 id (string)::
 496         The ID for this bar. Included in case you request multiple
 497         configurations and want to differentiate the different replies.
 498 mode (string)::
 499         Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
 500         does not show unless a specific key is pressed).
 501 position (string)::
 502         Either +bottom+ or +top+ at the moment.
 503 status_command (string)::
 504         Command which will be run to generate a statusline. Each line on stdout
 505         of this command will be displayed in the bar. At the moment, no
 506         formatting is supported.
 507 font (string)::
 508         The font to use for text on the bar.
 509 workspace_buttons (boolean)::
 510         Display workspace buttons or not? Defaults to true.
 511 binding_mode_indicator (boolean)::
 512         Display the mode indicator or not? Defaults to true.
 513 verbose (boolean)::
 514         Should the bar enable verbose output for debugging? Defaults to false.
 515 colors (map)::
 516         Contains key/value pairs of colors. Each value is a color code in hex,
 517         formatted #rrggbb (like in HTML).
 518
 519 The following colors can be configured at the moment:
 520
 521 background::
 522         Background color of the bar.
 523 statusline::
 524         Text color to be used for the statusline.
 525 separator::
 526         Text color to be used for the separator.
 527 focused_background::
 528         Background color of the bar on the currently focused monitor output.
 529 focused_statusline::
 530         Text color to be used for the statusline on the currently focused
 531         monitor output.
 532 focused_separator::
 533         Text color to be used for the separator on the currently focused
 534         monitor output.
 535 focused_workspace_text/focused_workspace_bg/focused_workspace_border::
 536         Text/background/border color for a workspace button when the workspace
 537         has focus.
 538 active_workspace_text/active_workspace_bg/active_workspace_border::
 539         Text/background/border color for a workspace button when the workspace
 540         is active (visible) on some output, but the focus is on another one.
 541         You can only tell this apart from the focused workspace when you are
 542         using multiple monitors.
 543 inactive_workspace_text/inactive_workspace_bg/inactive_workspace_border::
 544         Text/background/border color for a workspace button when the workspace
 545         does not have focus and is not active (visible) on any output. This
 546         will be the case for most workspaces.
 547 urgent_workspace_text/urgent_workspace_bg/urgent_workspace_border::
 548         Text/background/border color for workspaces which contain at least one
 549         window with the urgency hint set.
 550 binding_mode_text/binding_mode_bg/binding_mode_border::
 551         Text/background/border color for the binding mode indicator.
 552
 553
 554 *Example of configured bars:*
 555 --------------
 556 ["bar-bxuqzf"]
 557 --------------
 558
 559 *Example of bar configuration:*
 560 --------------
 561 {
 562  "id": "bar-bxuqzf",
 563  "mode": "dock",
 564  "position": "bottom",
 565  "status_command": "i3status",
 566  "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
 567  "workspace_buttons": true,
 568  "binding_mode_indicator": true,
 569  "verbose": false,
 570  "colors": {
 571    "background": "#c0c0c0",
 572    "statusline": "#00ff00",
 573    "focused_workspace_text": "#ffffff",
 574    "focused_workspace_bg": "#000000"
 575  }
 576 }
 577 --------------
 578
 579 === VERSION reply
 580
 581 The reply consists of a single JSON dictionary with the following keys:
 582
 583 major (integer)::
 584         The major version of i3, such as +4+.
 585 minor (integer)::
 586         The minor version of i3, such as +2+. Changes in the IPC interface (new
 587         features) will only occur with new minor (or major) releases. However,
 588         bugfixes might be introduced in patch releases, too.
 589 patch (integer)::
 590         The patch version of i3, such as +1+ (when the complete version is
 591         +4.2.1+). For versions such as +4.2+, patch will be set to +0+.
 592 human_readable (string)::
 593         A human-readable version of i3 containing the precise git version,
 594         build date and branch name. When you need to display the i3 version to
 595         your users, use the human-readable version whenever possible (since
 596         this is what +i3 --version+ displays, too).
 597 loaded_config_file_name (string)::
 598         The current config path.
 599
 600 *Example:*
 601 -------------------
 602 {
 603    "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
 604    "loaded_config_file_name" : "/home/hwangcc23/.i3/config",
 605    "minor" : 2,
 606    "patch" : 0,
 607    "major" : 4
 608 }
 609 -------------------
 610
 611 === BINDING_MODES reply
 612
 613 The reply consists of an array of all currently configured binding modes.
 614
 615 *Example:*
 616 ---------------------
 617 ["default", "resize"]
 618 ---------------------
 619
 620 == Events
 621
 622 [[events]]
 623
 624 To get informed when certain things happen in i3, clients can subscribe to
 625 events. Events consist of a name (like "workspace") and an event reply type
 626 (like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format
 627 as replies to specific commands. However, the highest bit of the message type
 628 is set to 1 to indicate that this is an event reply instead of a normal reply.
 629
 630 Caveat: As soon as you subscribe to an event, it is not guaranteed any longer
 631 that the requests to i3 are processed in order. This means, the following
 632 situation can happen: You send a GET_WORKSPACES request but you receive a
 633 "workspace" event before receiving the reply to GET_WORKSPACES. If your
 634 program does not want to cope which such kinds of race conditions (an
 635 event based library may not have a problem here), I suggest you create a
 636 separate connection to receive events.
 637
 638 === Subscribing to events
 639
 640 By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
 641 you can register to an event.
 642
 643 *Example:*
 644 ---------------------------------
 645 type: SUBSCRIBE
 646 payload: [ "workspace", "output" ]
 647 ---------------------------------
 648
 649
 650 === Available events
 651
 652 The numbers in parenthesis is the event type (keep in mind that you need to
 653 strip the highest bit first).
 654
 655 workspace (0)::
 656         Sent when the user switches to a different workspace, when a new
 657         workspace is initialized or when a workspace is removed (because the
 658         last client vanished).
 659 output (1)::
 660         Sent when RandR issues a change notification (of either screens,
 661         outputs, CRTCs or output properties).
 662 mode (2)::
 663         Sent whenever i3 changes its binding mode.
 664 window (3)::
 665         Sent when a client's window is successfully reparented (that is when i3
 666         has finished fitting it into a container), when a window received input
 667         focus or when certain properties of the window have changed.
 668 barconfig_update (4)::
 669     Sent when the hidden_state or mode field in the barconfig of any bar
 670     instance was updated and when the config is reloaded.
 671 binding (5)::
 672         Sent when a configured command binding is triggered with the keyboard or
 673         mouse
 674
 675 *Example:*
 676 --------------------------------------------------------------------
 677 # the appropriate 4 bytes read from the socket are stored in $input
 678
 679 # unpack a 32-bit unsigned integer
 680 my $message_type = unpack("L", $input);
 681
 682 # check if the highest bit is 1
 683 my $is_event = (($message_type >> 31) == 1);
 684
 685 # use the other bits
 686 my $event_type = ($message_type & 0x7F);
 687
 688 if ($is_event) {
 689   say "Received event of type $event_type";
 690 }
 691 --------------------------------------------------------------------
 692
 693 === workspace event
 694
 695 This event consists of a single serialized map containing a property
 696 +change (string)+ which indicates the type of the change ("focus", "init",
 697 "empty", "urgent"). A +current (object)+ property will be present with the
 698 affected workspace whenever the type of event affects a workspace (otherwise,
 699 it will be +null).
 700
 701 When the change is "focus", an +old (object)+ property will be present with the
 702 previous workspace.  When the first switch occurs (when i3 focuses the
 703 workspace visible at the beginning) there is no previous workspace, and the
 704 +old+ property will be set to +null+.  Also note that if the previous is empty
 705 it will get destroyed when switching, but will still be present in the "old"
 706 property.
 707
 708 *Example:*
 709 ---------------------
 710 {
 711  "change": "focus",
 712  "current": {
 713   "id": 28489712,
 714   "type": "workspace",
 715   ...
 716  }
 717  "old": {
 718   "id": 28489715,
 719   "type": "workspace",
 720   ...
 721  }
 722 }
 723 ---------------------
 724
 725 === output event
 726
 727 This event consists of a single serialized map containing a property
 728 +change (string)+ which indicates the type of the change (currently only
 729 "unspecified").
 730
 731 *Example:*
 732 ---------------------------
 733 { "change": "unspecified" }
 734 ---------------------------
 735
 736 === mode event
 737
 738 This event consists of a single serialized map containing a property
 739 +change (string)+ which holds the name of current mode in use. The name
 740 is the same as specified in config when creating a mode. The default
 741 mode is simply named default. It contains a second property, +pango_markup+, which
 742 defines whether pango markup shall be used for displaying this mode.
 743
 744 *Example:*
 745 ---------------------------
 746 {
 747   "change": "default",
 748   "pango_markup": true
 749 }
 750 ---------------------------
 751
 752 === window event
 753
 754 This event consists of a single serialized map containing a property
 755 +change (string)+ which indicates the type of the change
 756
 757 * +new+ – the window has become managed by i3
 758 * +close+ – the window has closed
 759 * +focus+ – the window has received input focus
 760 * +title+ – the window's title has changed
 761 * +fullscreen_mode+ – the window has entered or exited fullscreen mode
 762 * +move+ – the window has changed its position in the tree
 763 * +floating+ – the window has transitioned to or from floating
 764 * +urgent+ – the window has become urgent or lost its urgent status
 765 * +mark+ – a mark has been added to or removed from the window
 766
 767 Additionally a +container (object)+ field will be present, which consists
 768 of the window's parent container. Be aware that for the "new" event, the
 769 container will hold the initial name of the newly reparented window (e.g.
 770 if you run urxvt with a shell that changes the title, you will still at
 771 this point get the window title as "urxvt").
 772
 773 *Example:*
 774 ---------------------------
 775 {
 776  "change": "new",
 777  "container": {
 778   "id": 35569536,
 779   "type": "con",
 780   ...
 781  }
 782 }
 783 ---------------------------
 784
 785 === barconfig_update event
 786
 787 This event consists of a single serialized map reporting on options from the
 788 barconfig of the specified bar_id that were updated in i3. This event is the
 789 same as a +GET_BAR_CONFIG+ reply for the bar with the given id.
 790
 791 === binding event
 792
 793 This event consists of a single serialized map reporting on the details of a
 794 binding that ran a command because of user input. The +change (sring)+ field
 795 indicates what sort of binding event was triggered (right now it will always be
 796 +"run"+ but may be expanded in the future).
 797
 798 The +binding (object)+ field contains details about the binding that was run:
 799
 800 command (string)::
 801         The i3 command that is configured to run for this binding.
 802 event_state_mask (array of strings)::
 803         The group and modifier keys that were configured with this binding.
 804 input_code (integer)::
 805         If the binding was configured with +bindcode+, this will be the key code
 806         that was given for the binding. If the binding is a mouse binding, it will be
 807         the number of the mouse button that was pressed. Otherwise it will be 0.
 808 symbol (string or null)::
 809         If this is a keyboard binding that was configured with +bindsym+, this
 810         field will contain the given symbol. Otherwise it will be +null+.
 811 input_type (string)::
 812         This will be +"keyboard"+ or +"mouse"+ depending on whether or not this was
 813         a keyboard or a mouse binding.
 814
 815 *Example:*
 816 ---------------------------
 817 {
 818  "change": "run",
 819  "binding": {
 820   "command": "nop",
 821   "event_state_mask": [
 822     "shift",
 823     "ctrl"
 824   ],
 825   "input_code": 0,
 826   "symbol": "t",
 827   "input_type": "keyboard"
 828  }
 829 }
 830 ---------------------------
 831
 832 == See also (existing libraries)
 833
 834 [[libraries]]
 835
 836 For some languages, libraries are available (so you don’t have to implement
 837 all this on your own). This list names some (if you wrote one, please let me
 838 know):
 839
 840 C::
 841         * i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
 842         * https://github.com/acrisci/i3ipc-glib
 843 C++::
 844         * https://github.com/drmgc/i3ipcpp
 845 Go::
 846         * https://github.com/proxypoke/i3ipc
 847 JavaScript::
 848         * https://github.com/acrisci/i3ipc-gjs
 849 Lua::
 850         * https://github.com/acrisci/i3ipc-lua
 851 Perl::
 852         * https://metacpan.org/module/AnyEvent::I3
 853 Python::
 854         * https://github.com/acrisci/i3ipc-python
 855         * https://github.com/whitelynx/i3ipc (not maintained)
 856         * https://github.com/ziberna/i3-py (not maintained)
 857 Ruby::
 858         * https://github.com/veelenga/i3ipc-ruby
 859         * https://github.com/badboy/i3-ipc (not maintained)
 860 Rust::
 861         * https://github.com/tmerr/i3ipc-rs