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);
The method of choice for IPC in our case is a unix socket because it has very little overhead on both sides and is usually available without headaches in -most languages. In the default configuration file, no ipc-socket path is -specified and thus no socket is created. The standard path (which i3-msg and -i3-input use) is ~/.i3/ipc.sock.
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. |
+
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);
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. + directly after receiving it.
+ Gets the layout tree. i3 uses a tree as data structure which includes + every container. The reply will be the JSON-encoded tree (see the reply + section). +
++ Gets a list of marks (identifiers for containers to easily jump to them + later). The reply will be a JSON-encoded list of window marks (see + reply section). +
++ Gets the configuration (as JSON map) of the workspace bar with the + given ID. If no ID is provided, an array with all configured bar IDs is + returned instead. +
++ Gets the version of i3. The reply will be a JSON-encoded dictionary + with the major, minor, patch and human-readable version. +
+So, a typical message could look like this:
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:
@@ -179,27 +236,60 @@ SUBSCRIBE (2)
Reply to the GET_OUTPUTS message.
+ Reply to the GET_TREE message. +
++ Reply to the GET_MARKS message. +
++ Reply to the GET_BAR_CONFIG message. +
++ Reply to the GET_VERSION message. +
+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 }]
The reply consists of a serialized list of workspaces. Each workspace has the following properties:
The reply consists of a serialized list of outputs. Each output has the following properties:
- 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.
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!
+ 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. +
++ 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 of this container. Can be one of "root", "output", "con", + "floating_con", "workspace" or "dockarea". +
++ Can be either "normal", "none" or "1pixel", dependending on the + containerâs border style. +
++ Number of pixels of the border width. +
++ Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or + "output". + Other values might be possible in the future, should we add new + layouts. +
++ 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. +
++ 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. +
++ 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 }. +
++ 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). +
++ The original geometry the window specified when i3 mapped it. Used when + switching a window to floating mode, for example. +
++ 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). +
++ Whether this container (window or workspace) has the urgency hint set. +
++ Whether this container is currently focused. +
+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
+ }
+ }
+
+ ]
+ }
+ ]
+ }
+ ]
+}
+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 [].
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:
+ An array of configured bar IDs +
++ A JSON map containing the configuration for the specified bar. +
+Each bar configuration has the following properties:
+ The ID for this bar. Included in case you request multiple + configurations and want to differentiate the different replies. +
++ Either dock (the bar sets the dock window type) or hide (the bar + does not show unless a specific key is pressed). +
++ Either bottom or top at the moment. +
++ 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. +
++ The font to use for text on the bar. +
++ Display workspace buttons or not? Defaults to true. +
++ Display the mode indicator or not? Defaults to true. +
++ Should the bar enable verbose output for debugging? Defaults to false. +
++ 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 color of the bar. +
++ Text color to be used for the statusline. +
++ Text color to be used for the separator. +
++ Text color/background color for a workspace button when the workspace + has focus. +
++ Text color/background 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. +
++ Text color/background 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. +
++ Text color/background color for workspaces which contain at least one + window with the urgency hint set. +
+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"
+ }
+}
+The reply consists of a single JSON dictionary with the following keys:
+ The major version of i3, such as 4. +
++ 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. +
++ 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. +
++ 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). +
+Example:
{
+ "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
+ "minor" : 2,
+ "patch" : 0,
+ "major" : 4
+}
++ Sent whenever i3 changes its binding mode. +
++ 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. +
++ Sent when the hidden_state or mode field in the barconfig of any bar + instance was updated and when the config is reloaded. +
+Example:
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.
Example:
{ "change": "focus" }
+{
+ "change": "focus",
+ "current": {
+ "id": 28489712,
+ "type": "workspace",
+ ...
+ }
+ "old": {
+ "id": 28489715,
+ "type": "workspace",
+ ...
+ }
+}
{ "change": "unspecified" }
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.
Example:
{ "change": "default" }
+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",
+ ...
+ }
+}
+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.
For some languages, libraries are available (so you donât have to implement +
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):
i3 includes a headerfile i3/ipc.h which provides you all constants. - However, there is no library yet. -
-- http://github.com/thepub/i3ipc
+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 +Python:: + * 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+