X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc;h=acb053213cd5a7743667aafa24fc1cff2a15f2a0;hb=1f2c9306a27cced83ad960e929bb9e9a163b7843;hp=e6c1bbdfb4f37661dd25abaa030ab51f2434ad87;hpb=f0aa52f674850578a89afad52afeb594e0d31e71;p=i3%2Fi3 diff --git a/docs/ipc b/docs/ipc index e6c1bbdf..acb05321 100644 --- a/docs/ipc +++ b/docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -March 2010 +December 2011 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 @@ -11,8 +11,10 @@ workspace bar. 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, the ipc-socket gets created -in +/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the -PID of i3. +in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is +the PID of i3 and XXXXXX is a string of random characters from the portable +filename character set (see mkdtemp(3)). You can get the socketpath from i3 by +calling +i3 --get-socketpath+. All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+ X11 property, stored on the X11 root window. @@ -24,7 +26,8 @@ snippet illustrates this in Perl: ------------------------------------------------------------- use IO::Socket::UNIX; -my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock'); +chomp(my $path = qx(i3 --get-socketpath)); +my $sock = IO::Socket::UNIX->new(Peer => $path); ------------------------------------------------------------- == Sending messages to i3 @@ -45,7 +48,7 @@ Currently implemented message types are the following: COMMAND (0):: 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. GET_WORKSPACES (1):: Gets the current workspaces. The reply will be a JSON-encoded list of workspaces (see the reply section). @@ -55,6 +58,22 @@ SUBSCRIBE (2):: GET_OUTPUTS (3):: Gets the current outputs. The reply will be a JSON-encoded list of outputs (see the reply section). +GET_TREE (4):: + 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). +GET_MARKS (5):: + 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). +GET_BAR_CONFIG (6):: + 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. +GET_LOG_MARKERS (7):: + Gets the SHM log markers for the current position, the last wrap, the + SHM segment name and segment size. This is necessary for tools like + i3-dump-log which want to display the SHM log. So, a typical message could look like this: -------------------------------------------------- @@ -98,12 +117,20 @@ The following reply types are implemented: COMMAND (0):: Confirmation/Error code for the COMMAND message. -GET_WORKSPACES (1):: +WORKSPACES (1):: Reply to the GET_WORKSPACES message. SUBSCRIBE (2):: Confirmation/Error code for the SUBSCRIBE message. -GET_OUTPUTS (3):: +OUTPUTS (3):: Reply to the GET_OUTPUTS message. +TREE (4):: + Reply to the GET_TREE message. +MARKS (5):: + Reply to the GET_MARKS message. +BAR_CONFIG (6):: + Reply to the GET_BAR_CONFIG message. +LOG_MARKERS (7):: + Reply to the GET_LOG_MARKERS message. === COMMAND reply @@ -115,7 +142,7 @@ property is +success (bool)+, but this will be expanded in future versions. { "success": true } ------------------- -=== GET_WORKSPACES reply +=== WORKSPACES reply The reply consists of a serialized list of workspaces. Each workspace has the following properties: @@ -229,6 +256,316 @@ rect (map):: ] ------------------- +=== TREE reply + +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! + +id (integer):: + 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. +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 all other containers, the content is not defined (yet). +border (string):: + Can be either "normal", "none" or "1pixel", dependending on the + container’s border style. +layout (string):: + Can be either "default", "stacked", "tabbed", "dockarea" or "output". + Other values might be possible in the future, should we add new + layouts. +orientation (string):: + Can be either "none" (for non-split containers), "horizontal" or + "vertical". +percent (float):: + 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. +rect (map):: + 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 }+. +window_rect (map):: + 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). +geometry (map):: + The original geometry the window specified when i3 mapped it. Used when + switching a window to floating mode, for example. +urgent (bool):: + Whether this container (window or workspace) has the urgency hint set. +focused (bool):: + 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 + } + } + + ] + } + ] + } + ] +} +------------------------ + +=== 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). + +If no window has a mark the response will be the empty array []. + +=== BAR_CONFIG reply + +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: + +empty input:: + An array of configured bar IDs +Bar ID:: + A JSON map containing the configuration for the specified bar. + +Each bar configuration has the following properties: + +id (string):: + The ID for this bar. Included in case you request multiple + configurations and want to differentiate the different replies. +mode (string):: + Either +dock+ (the bar sets the dock window type) or +hide+ (the bar + does not show unless a specific key is pressed). +position (string):: + Either +bottom+ or +top+ at the moment. +status_command (string):: + 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. +font (string):: + The font to use for text on the bar. +workspace_buttons (boolean):: + Display workspace buttons or not? Defaults to true. +verbose (boolean):: + Should the bar enable verbose output for debugging? Defaults to false. +colors (map):: + 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:: + Background color of the bar. +statusline:: + Text color to be used for the statusline. +focused_workspace_text/focused_workspace_bg:: + Text color/background color for a workspace button when the workspace + has focus. +active_workspace_text/active_workspace_bg:: + 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. +inactive_workspace_text/inactive_workspace_bg:: + 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. +urgent_workspace_text/urgent_workspace_bar:: + 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, + "verbose": false, + "colors": { + "background": "#c0c0c0", + "statusline": "#00ff00", + "focused_workspace_text": "#ffffff", + "focused_workspace_bg": "#000000" + } +} +-------------- + +=== LOG_MARKERS reply + +Gets the SHM log markers for the current position, the last wrap, the +SHM segment name and segment size. This is necessary for tools like +i3-dump-log which want to display the SHM log. + +The reply is a JSON map with the following entries: + +shmname (string):: + The name of the SHM segment, will be of the format +/i3-log-+. +size (integer):: + The size (in bytes) of the SHM segment. If this is 0, SHM logging is + disabled. +offset_next_write (integer):: + The offset in the SHM segment at which the next write will happen. + Tools should start printing lines from here, since the bytes following + this offset are the oldest log lines. However, the first line might be + garbled, so it makes sense to skip all bytes until the first \0. +offset_last_wrap (integer):: + The offset in the SHM segment at which the last wrap occured. i3 only + stores entire messages in the SHM log, so it might waste a few bytes at + the end to be more efficient. Tools should not print content after the + offset_last_wrap. + +*Example*: +----------------------------- +{ + "offset_next_write":132839, + "offset_last_wrap":26214400, + "shmname":"/i3-log-3392", + "size":26214400 +} +----------------------------- + == Events [[events]]