"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
<head>\r
-<link rel="icon" type="image/png" href="/favicon.png">\r
+<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.7" />\r
+<meta name="generator" content="AsciiDoc 8.6.9" />\r
<title>i3: IPC interface (interprocess communication)</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<script type="text/javascript">\r
/*<![CDATA[*/\r
-window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); asciidoc.toc(2);}, false);\r
/*]]>*/\r
</script>\r
<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
<ul id="nav">\r
<li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
<li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="https://faq.i3wm.org/">FAQ</a></li>\r
<li><a href="/contact">Contact</a></li>\r
- <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
</ul>\r
<br style="clear: both">\r
<div id="content">\r
<h1>IPC interface (interprocess communication)</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
-<span id="revdate">October 2012</span>\r
+<span id="revdate">October 2014</span>\r
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>\r
<div class="sect2">\r
<h3 id="_command_reply">3.2. COMMAND reply</h3>\r
-<div class="paragraph"><p>The reply consists of a single serialized map. At the moment, the only\r
-property is <tt>success (bool)</tt>, but this will be expanded in future versions.</p></div>\r
+<div class="paragraph"><p>The reply consists of a list of serialized maps for each command that was\r
+parsed. Each has the property <tt>success (bool)</tt> and may also include a\r
+human-readable error message in the property <tt>error (string)</tt>.</p></div>\r
<div class="paragraph"><p><strong>Example:</strong></p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>{ "success": true }</tt></pre>\r
+<pre><tt>[{ "success": true }]</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
<dd>\r
<p>\r
The logical number of the workspace. Corresponds to the command\r
- to switch to this workspace.\r
+ to switch to this workspace. For named workspaces, this will be -1.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-current_workspace (integer)\r
+current_workspace (string)\r
</dt>\r
<dd>\r
<p>\r
- The current workspace which is visible on this output. <tt>null</tt> if the\r
- output is not active.\r
+ The name of the current workspace that is visible on this output. <tt>null</tt> if\r
+ the output is not active.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
{\r
"name": "LVDS1",\r
"active": true,\r
- "current_workspace": 4,\r
+ "current_workspace": "4",\r
"rect": {\r
"x": 0,\r
"y": 0,\r
{\r
"name": "VGA1",\r
"active": true,\r
- "current_workspace": 1,\r
+ "current_workspace": "1",\r
"rect": {\r
"x": 1280,\r
"y": 0,\r
The internal name of this container. For all containers which are part\r
of the tree structure down to the workspace contents, this is set to a\r
nice human-readable name of the container.\r
+ For containers that have an X11 window, the content is the title\r
+ (_NET_WM_NAME property) of that window.\r
For all other containers, the content is not defined (yet).\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+type (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Type of this container. Can be one of "root", "output", "con",\r
+ "floating_con", "workspace" or "dockarea".\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
border (string)\r
</dt>\r
<dd>\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+deco_rect (map)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The coordinates of the <strong>window decoration</strong> inside its container. These\r
+ coordinates are relative to the container and do not include the actual\r
+ client window.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
geometry (map)\r
</dt>\r
<dd>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>type: SUBSCRIBE\r
-payload: [ "workspace", "focus" ]</tt></pre>\r
+payload: [ "workspace", "output" ]</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
<dd>\r
<p>\r
Sent when a client’s window is successfully reparented (that is when i3\r
- has finished fitting it into a container).\r
+ has finished fitting it into a container), when a window received input\r
+ focus or when certain properties of the window have changed.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
<dd>\r
<p>\r
Sent when the hidden_state or mode field in the barconfig of any bar\r
- instance was updated.\r
+ instance was updated and when the config is reloaded.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+binding (5)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Sent when a configured command binding is triggered with the keyboard or\r
+ mouse\r
</p>\r
</dd>\r
</dl></div>\r
<h3 id="_workspace_event">4.3. workspace event</h3>\r
<div class="paragraph"><p>This event consists of a single serialized map containing a property\r
<tt>change (string)</tt> which indicates the type of the change ("focus", "init",\r
-"empty", "urgent").</p></div>\r
-<div class="paragraph"><p>Moreover, when the change is "focus", an <tt>old (object)</tt> and a <tt>current\r
-(object)</tt> properties will be present with the previous and current\r
-workspace respectively. When the first switch occurs (when i3 focuses\r
-the workspace visible at the beginning) there is no previous\r
-workspace, and the <tt>old</tt> property will be set to <tt>null</tt>. Also note\r
-that if the previous is empty it will get destroyed when switching,\r
-but will still be present in the "old" property.</p></div>\r
+"empty", "urgent"). A <tt>current (object)</tt> property will be present with the\r
+affected workspace whenever the type of event affects a workspace (otherwise,\r
+it will be +null).</p></div>\r
+<div class="paragraph"><p>When the change is "focus", an <tt>old (object)</tt> property will be present with the\r
+previous workspace. When the first switch occurs (when i3 focuses the\r
+workspace visible at the beginning) there is no previous workspace, and the\r
+<tt>old</tt> property will be set to <tt>null</tt>. Also note that if the previous is empty\r
+it will get destroyed when switching, but will still be present in the "old"\r
+property.</p></div>\r
<div class="paragraph"><p><strong>Example:</strong></p></div>\r
<div class="listingblock">\r
<div class="content">\r
"change": "focus",\r
"current": {\r
"id": 28489712,\r
- "type":4,\r
+ "type": "workspace",\r
...\r
}\r
"old": {\r
"id": 28489715,\r
- "type": 4,\r
+ "type": "workspace",\r
...\r
}\r
}</tt></pre>\r
<div class="sect2">\r
<h3 id="_window_event">4.6. window event</h3>\r
<div class="paragraph"><p>This event consists of a single serialized map containing a property\r
-<tt>change (string)</tt> which currently can indicate only that a new window\r
-has been successfully reparented (the value will be "new").</p></div>\r
+<tt>change (string)</tt> which indicates the type of the change</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+<tt>new</tt> - the window has become managed by i3\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>close</tt> - the window has closed\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>focus</tt> - the window has received input focus\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>title</tt> - the window’s title has changed\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>fullscreen_mode</tt> - the window has entered or exited fullscreen mode\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>move</tt> - the window has changed its position in the tree\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>floating</tt> - the window has transitioned to or from floating\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>urgent</tt> - the window has become urgent or lost its urgent status\r
+</p>\r
+</li>\r
+</ul></div>\r
<div class="paragraph"><p>Additionally a <tt>container (object)</tt> field will be present, which consists\r
-of the window’s parent container. Be aware that the container will hold\r
-the initial name of the newly reparented window (e.g. if you run urxvt\r
-with a shell that changes the title, you will still at this point get the\r
-window title as "urxvt").</p></div>\r
+of the window’s parent container. Be aware that for the "new" event, the\r
+container will hold the initial name of the newly reparented window (e.g.\r
+if you run urxvt with a shell that changes the title, you will still at\r
+this point get the window title as "urxvt").</p></div>\r
<div class="paragraph"><p><strong>Example:</strong></p></div>\r
<div class="listingblock">\r
<div class="content">\r
"change": "new",\r
"container": {\r
"id": 35569536,\r
- "type": 2,\r
+ "type": "con",\r
...\r
}\r
}</tt></pre>\r
<div class="sect2">\r
<h3 id="_barconfig_update_event">4.7. barconfig_update event</h3>\r
<div class="paragraph"><p>This event consists of a single serialized map reporting on options from the\r
-barconfig of the specified bar_id that were updated in i3. The map always\r
-consists of a property <tt>id (string)</tt>, which specifies to which bar instance the\r
-sent config update belongs, a property <tt>hidden_state (string)</tt>, which indicates\r
-the hidden_state of an i3bar instance, and a property <tt>mode (string)</tt>, which\r
-corresponds to the current mode.</p></div>\r
+barconfig of the specified bar_id that were updated in i3. This event is the\r
+same as a <tt>GET_BAR_CONFIG</tt> reply for the bar with the given id.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_binding_event">4.8. binding event</h3>\r
+<div class="paragraph"><p>This event consists of a single serialized map reporting on the details of a\r
+binding that ran a command because of user input. The <tt>change (sring)</tt> field\r
+indicates what sort of binding event was triggered (right now it will always be\r
+<tt>"run"</tt> but may be expanded in the future).</p></div>\r
+<div class="paragraph"><p>The <tt>binding (object)</tt> field contains details about the binding that was run:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+command (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The i3 command that is configured to run for this binding.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+mods (array of strings)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The modifier keys that were configured with this binding.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+input_code (integer)\r
+</dt>\r
+<dd>\r
+<p>\r
+ If the binding was configured with <tt>bindcode</tt>, this will be the key code\r
+ that was given for the binding. If the binding is a mouse binding, it will be\r
+ the number of the mouse button that was pressed. Otherwise it will be 0.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+symbol (string or null)\r
+</dt>\r
+<dd>\r
+<p>\r
+ If this is a keyboard binding that was configured with <tt>bindsym</tt>, this\r
+ field will contain the given symbol. Otherwise it will be <tt>null</tt>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+input_type (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ This will be <tt>"keyboard"</tt> or <tt>"mouse"</tt> depending on whether or not this was\r
+ a keyboard or a mouse binding.\r
+</p>\r
+</dd>\r
+</dl></div>\r
<div class="paragraph"><p><strong>Example:</strong></p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>{\r
- "id": "bar-0",\r
- "hidden_state": "hide"\r
- "mode": "hide"\r
+ "change": "run",\r
+ "binding": {\r
+ "command": "nop",\r
+ "mods": [\r
+ "shift",\r
+ "ctrl"\r
+ ],\r
+ "input_code": 0,\r
+ "symbol": "t",\r
+ "input_type": "keyboard"\r
+ }\r
}</tt></pre>\r
</div></div>\r
</div>\r
C\r
</dt>\r
<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
<p>\r
- i3 includes a headerfile <tt>i3/ipc.h</tt> which provides you all constants.\r
- However, there is no library yet.\r
+i3 includes a headerfile <tt>i3/ipc.h</tt> which provides you all constants.\r
</p>\r
+</li>\r
+<li>\r
+<p>\r
+<a href="https://github.com/acrisci/i3ipc-glib">https://github.com/acrisci/i3ipc-glib</a>\r
+</p>\r
+</li>\r
+</ul></div>\r
</dd>\r
<dt class="hdlist1">\r
-Ruby\r
+Go\r
</dt>\r
<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
<p>\r
- <a href="http://github.com/badboy/i3-ipc">http://github.com/badboy/i3-ipc</a>\r
+<a href="https://github.com/proxypoke/i3ipc">https://github.com/proxypoke/i3ipc</a>\r
</p>\r
+</li>\r
+</ul></div>\r
+</dd>\r
+<dt class="hdlist1">\r
+JavaScript\r
+</dt>\r
+<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+<a href="https://github.com/acrisci/i3ipc-gjs">https://github.com/acrisci/i3ipc-gjs</a>\r
+</p>\r
+</li>\r
+</ul></div>\r
+</dd>\r
+<dt class="hdlist1">\r
+Lua\r
+</dt>\r
+<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+<a href="https://github.com/acrisci/i3ipc-lua">https://github.com/acrisci/i3ipc-lua</a>\r
+</p>\r
+</li>\r
+</ul></div>\r
</dd>\r
<dt class="hdlist1">\r
Perl\r
</dt>\r
<dd>\r
+<div class="ulist"><ul>\r
+<li>\r
<p>\r
-
<a href="https://metacpan.org/module/AnyEvent::I3">https://metacpan.org/module/AnyEvent::I3</a>
\r+<a href="https://metacpan.org/module/AnyEvent::I3">https://metacpan.org/module/AnyEvent::I3</a>\r
</p>\r
+</li>\r
+</ul></div>\r
</dd>\r
<dt class="hdlist1">\r
Python\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
-<a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a>\r
+<a href="https://github.com/acrisci/i3ipc-python">https://github.com/acrisci/i3ipc-python</a>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<a href="https://github.com/whitelynx/i3ipc">https://github.com/whitelynx/i3ipc</a> (not maintained)\r
</p>\r
</li>\r
<li>\r
<p>\r
-<a href="https://github.com/ziberna/i3-py">https://github.com/ziberna/i3-py</a> (includes higher-level features)\r
+<a href="https://github.com/ziberna/i3-py">https://github.com/ziberna/i3-py</a> (not maintained)\r
</p>\r
</li>\r
</ul></div>\r
</dd>\r
<dt class="hdlist1">\r
-Go\r
+Ruby\r
</dt>\r
<dd>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
-<a href="https://github.com/proxypoke/i3ipc">https://github.com/proxypoke/i3ipc</a>\r
+<a href="http://github.com/badboy/i3-ipc">http://github.com/badboy/i3-ipc</a>\r
</p>\r
</li>\r
</ul></div>\r
projects / i3 / i3.github.io / blobdiff