X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc;h=2716f180dc4fd4bdd3a1cc8b1fe61bcb4543fc0d;hb=b741c492120bde20a289dc7a044d10c429f84a32;hp=acb053213cd5a7743667aafa24fc1cff2a15f2a0;hpb=fc27c19761b47fa449514395f7ea2a21654f515d;p=i3%2Fi3 diff --git a/docs/ipc b/docs/ipc index acb05321..2716f180 100644 --- a/docs/ipc +++ b/docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== -Michael Stapelberg -December 2011 +Michael Stapelberg +August 2012 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 @@ -70,10 +70,9 @@ 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. +GET_VERSION (7):: + 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: -------------------------------------------------- @@ -129,8 +128,8 @@ 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. +VERSION (7):: + Reply to the GET_VERSION message. === COMMAND reply @@ -212,7 +211,7 @@ default) or whether a JSON parse error occurred. { "success": true } ------------------- -=== GET_OUTPUTS reply +=== OUTPUTS reply The reply consists of a serialized list of outputs. Each output has the following properties: @@ -276,12 +275,15 @@ 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". + Can be either "splith", "splitv", "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". + THIS FIELD IS OBSOLETE. It is still present, but your code should not + use it. Instead, rely on the layout field. 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 @@ -302,6 +304,11 @@ window_rect (map):: geometry (map):: The original geometry the window specified when i3 mapped it. Used when switching a window to floating mode, for example. +window (integer):: + 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). urgent (bool):: Whether this container (window or workspace) has the urgency hint set. focused (bool):: @@ -532,39 +539,34 @@ urgent_workspace_text/urgent_workspace_bar:: } -------------- -=== 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*: ------------------------------ +=== VERSION reply + +The reply consists of a single JSON dictionary with the following keys: + +major (integer):: + The major version of i3, such as +4+. +minor (integer):: + 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. +patch (integer):: + 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+. +human_readable (string):: + 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:* +------------------- { - "offset_next_write":132839, - "offset_last_wrap":26214400, - "shmname":"/i3-log-3392", - "size":26214400 + "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")", + "minor" : 2, + "patch" : 0, + "major" : 4 } ------------------------------ +------------------- == Events @@ -608,6 +610,8 @@ workspace (0):: output (1):: Sent when RandR issues a change notification (of either screens, outputs, CRTCs or output properties). +mode (2):: + Sent whenever i3 changes its binding mode. *Example:* -------------------------------------------------------------------- @@ -649,6 +653,18 @@ This event consists of a single serialized map containing a property { "change": "unspecified" } --------------------------- +=== mode event + +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" } +--------------------------- + == See also For some languages, libraries are available (so you don’t have to implement @@ -661,6 +677,7 @@ C:: Ruby:: http://github.com/badboy/i3-ipc Perl:: - http://search.cpan.org/search?query=AnyEvent::I3 + https://metacpan.org/module/AnyEvent::I3 Python:: - http://github.com/thepub/i3ipc + * https://github.com/whitelynx/i3ipc + * https://github.com/ziberna/i3-py (includes higher-level features)