X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=_docs%2Fipc;h=61a85c0a7a70ca91b98f80c3e57beacb27f8034b;hb=fdb8f31619e2335615f85f04a1b2b10dfb68f42b;hp=7e71326022606aa2b4d1abf93d4d77d3c448fe1a;hpb=f5c8fffeb1fdab2e9fc2bf1f65ccad46dc7f5ff7;p=i3%2Fi3.github.io diff --git a/_docs/ipc b/_docs/ipc index 7e71326..61a85c0 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -March 2010 +October 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 @@ -59,6 +62,14 @@ 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. So, a typical message could look like this: -------------------------------------------------- @@ -110,6 +121,10 @@ GET_OUTPUTS (3):: Reply to the GET_OUTPUTS message. GET_TREE (4):: Reply to the GET_TREE message. +GET_MARKS (5):: + Reply to the GET_MARKS message. +GET_BAR_CONFIG (6):: + Reply to the GET_BAR_CONFIG message. === COMMAND reply @@ -418,6 +433,98 @@ JSON dump: } ------------------------ +=== GET_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 []. + +=== GET_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" + } +} +-------------- == Events