@@ -31,7 +32,7 @@ document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); a
IPC interface (interprocess communication)
Michael Stapelberg <michael@i3wm.org>
-October 2012
+October 2014
Table of Contents
@@ -279,12 +280,13 @@ VERSION (7)
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 }]
@@ -298,7 +300,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.
- 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.
@@ -447,7 +449,7 @@ rect (map)
{
"name": "LVDS1",
"active": true,
- "current_workspace": 4,
+ "current_workspace": "4",
"rect": {
"x": 0,
"y": 0,
@@ -458,7 +460,7 @@ rect (map)
{
"name": "VGA1",
"active": true,
- "current_workspace": 1,
+ "current_workspace": "1",
"rect": {
"x": 1280,
"y": 0,
@@ -494,10 +496,21 @@ name (string)
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)
@@ -572,6 +585,16 @@ window_rect (map)
+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)
@@ -1068,7 +1091,7 @@ you can register to an event.
Sent when a client’s window is successfully reparented (that is when i3
- has finished fitting it into a container).
+ has finished fitting it into a container), when a window received input
+ focus or when certain properties of the window have changed.
@@ -1118,7 +1142,16 @@ barconfig_update (4)
Sent when the hidden_state or mode field in the barconfig of any bar
- instance was updated.
+ instance was updated and when the config is reloaded.
+
+
+
+binding (5)
+
+
+
+ Sent when a configured command binding is triggered with the keyboard or
+ mouse
@@ -1145,14 +1178,15 @@ if ($is_event) {
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").
-
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.
+"empty", "urgent"). 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:
@@ -1160,12 +1194,12 @@ but will still be present in the "old" property.
This event consists of a single serialized map containing a property
-change (string) which currently can indicate only that a new window
-has been successfully reparented (the value will be "new").
+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
+
+
+
Additionally a container (object) field will be present, which consists
-of the window’s parent container. Be aware that 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").
+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").
This event consists of a single serialized map reporting on options from the
-barconfig of the specified bar_id that were updated in i3. The map always
-consists of a property id (string), which specifies to which bar instance the
-sent config update belongs, a property hidden_state (string), which indicates
-the hidden_state of an i3bar instance, and a property mode (string), which
-corresponds to the current mode.
+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 (sring) 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.
+
+
+
+mods (array of strings)
+
+
+
+ The 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.
+
- i3 includes a headerfile i3/ipc.h which provides you all constants.
- However, there is no library yet.
+i3 includes a headerfile i3/ipc.h which provides you all constants.