IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael@i3wm.org>
-October 2012
+February 2014
This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
=== 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 }]
-------------------
=== WORKSPACES reply
The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8.
active (boolean)::
Whether this output is currently active (has a valid mode).
-current_workspace (integer)::
- The current workspace which is visible on this output. +null+ if the
- output is not active.
+current_workspace (string)::
+ The name of the current workspace that is visible on this output. +null+ if
+ the output is not active.
rect (map)::
The rectangle of this output (equals the rect of the output it
is on), consists of x, y, width, height.
{
"name": "LVDS1",
"active": true,
- "current_workspace": 4,
+ "current_workspace": "4",
"rect": {
"x": 0,
"y": 0,
{
"name": "VGA1",
"active": true,
- "current_workspace": 1,
+ "current_workspace": "1",
"rect": {
"x": 1280,
"y": 0,
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).
+type (string)::
+ Type of this container. Can be one of "root", "output", "con",
+ "floating_con", "workspace" or "dockarea".
border (string)::
Can be either "normal", "none" or "1pixel", dependending on the
container’s border style.
=== MARKS reply
The reply consists of a single array of strings for each container that has a
-mark. The order of that array is undefined. If more than one container has the
-same mark, it will be represented multiple times in the reply (the array
-contents are not unique).
+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 [].
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)::
Background color of the bar.
statusline::
Text color to be used for the statusline.
+separator::
+ Text color to be used for the separator.
focused_workspace_text/focused_workspace_bg::
Text color/background color for a workspace button when the workspace
has focus.
"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",
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.
*Example:*
--------------------------------------------------------------------
+change (string)+ which indicates the type of the change ("focus", "init",
"empty", "urgent").
+Moreover, when the change is "focus", an +old (object)+ and a +current
+(object)+ properties will be present with the previous and current
+workspace respectively. 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" }
+{
+ "change": "focus",
+ "current": {
+ "id": 28489712,
+ "type": "workspace",
+ ...
+ }
+ "old": {
+ "id": 28489715,
+ "type": "workspace",
+ ...
+ }
+}
---------------------
=== output event
{ "change": "default" }
---------------------------
+=== 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
+* +focus+ - the window has received input focus
+* +title+ - the window's title has changed
+* +fullscreen_mode+ - the window has entered or exited fullscreen mode
+
+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",
+ ...
+ }
+}
+---------------------------
+
+=== 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.
+
== See also (existing libraries)
[[libraries]]
C::
i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
- However, there is no library yet.
-Ruby::
- http://github.com/badboy/i3-ipc
+
+ https://github.com/acrisci/i3ipc-glib
+Go::
+ * https://github.com/proxypoke/i3ipc
+JavaScript::
+ * https://github.com/acrisci/i3ipc-gjs
+Lua::
+ * https:/github.com/acrisci/i3ipc-lua
Perl::
- https://metacpan.org/module/AnyEvent::I3
+ * https://metacpan.org/module/AnyEvent::I3
Python::
- * https://github.com/whitelynx/i3ipc
- * https://github.com/ziberna/i3-py (includes higher-level features)
+ * https://github.com/acrisci/i3ipc-python
+ * https://github.com/whitelynx/i3ipc (not maintained)
+ * https://github.com/ziberna/i3-py (not maintained)
+Ruby::
+ http://github.com/badboy/i3-ipc
projects / i3 / i3.github.io / blobdiff