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);
X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc.html;h=1771a14660e37b92a924d4f8503fe96082c30cd7;hb=d5c09e7f9685ff3e10afb87d7f132105b2dc78ec;hp=a9acc23411d2871d7ca8bbeef82eb9279deac2d5;hpb=40fb06967900e76899bfa8e45cb4059c91cc6482;p=i3%2Fi3.github.io diff --git a/docs/ipc.html b/docs/ipc.html index a9acc23..1771a14 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -2,14 +2,15 @@ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+ - +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+