X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc;h=ff7c8aaeb0f185299520dc5f271460060a8d13be;hb=ac19772efb7eb43c6d90336e3cb635815582ebab;hp=99bc5852c3e8fd2864b1fe6bb489554e3ffbc412;hpb=78e99440f6ff144bb6842f3fb33c1f65faadc4df;p=i3%2Fi3 diff --git a/docs/ipc b/docs/ipc index 99bc5852..ff7c8aae 100644 --- a/docs/ipc +++ b/docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -October 2012 +October 2014 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 @@ -140,12 +140,13 @@ VERSION (7):: === COMMAND reply -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 }] ------------------- === WORKSPACES reply @@ -155,7 +156,7 @@ following properties: num (integer):: The logical number of the workspace. Corresponds to the command - to switch to this workspace. + to switch to this workspace. For named workspaces, this will be -1. name (string):: The name of this workspace (by default num+1), as changed by the user. Encoded in UTF-8. @@ -227,9 +228,9 @@ name (string):: The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8. active (boolean):: Whether this output is currently active (has a valid mode). -current_workspace (integer):: - The current workspace which is visible on this output. +null+ if the - output is not active. +current_workspace (string):: + The name of the current workspace that is visible on this output. +null+ if + the output is not active. rect (map):: The rectangle of this output (equals the rect of the output it is on), consists of x, y, width, height. @@ -240,7 +241,7 @@ rect (map):: { "name": "LVDS1", "active": true, - "current_workspace": 4, + "current_workspace": "4", "rect": { "x": 0, "y": 0, @@ -251,7 +252,7 @@ rect (map):: { "name": "VGA1", "active": true, - "current_workspace": 1, + "current_workspace": "1", "rect": { "x": 1280, "y": 0, @@ -277,7 +278,12 @@ 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 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 (string):: + Type of this container. Can be one of "root", "output", "con", + "floating_con", "workspace" or "dockarea". border (string):: Can be either "normal", "none" or "1pixel", dependending on the container’s border style. @@ -310,6 +316,10 @@ window_rect (map):: 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). +deco_rect (map):: + The coordinates of the *window decoration* inside its container. These + coordinates are relative to the container and do not include the actual + client window. geometry (map):: The original geometry the window specified when i3 mapped it. Used when switching a window to floating mode, for example. @@ -458,9 +468,8 @@ JSON dump: === 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). +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 []. @@ -495,6 +504,8 @@ font (string):: The font to use for text on the bar. workspace_buttons (boolean):: Display workspace buttons or not? Defaults to true. +binding_mode_indicator (boolean):: + Display the mode indicator or not? Defaults to true. verbose (boolean):: Should the bar enable verbose output for debugging? Defaults to false. colors (map):: @@ -540,6 +551,7 @@ urgent_workspace_text/urgent_workspace_bar:: "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", @@ -605,7 +617,7 @@ you can register to an event. *Example:* --------------------------------- type: SUBSCRIBE -payload: [ "workspace", "focus" ] +payload: [ "workspace", "output" ] --------------------------------- @@ -625,10 +637,14 @@ mode (2):: Sent whenever i3 changes its binding mode. window (3):: Sent when a client's window is successfully reparented (that is when i3 - has finished fitting it into a container). + has finished fitting it into a container), when a window received input + focus or when certain properties of the window have changed. barconfig_update (4):: Sent when the hidden_state or mode field in the barconfig of any bar - instance was updated. + instance was updated and when the config is reloaded. +binding (5):: + Sent when a configured command binding is triggered with the keyboard or + mouse *Example:* -------------------------------------------------------------------- @@ -652,15 +668,16 @@ if ($is_event) { This event consists of a single serialized map containing a property +change (string)+ which indicates the type of the change ("focus", "init", -"empty", "urgent"). +"empty", "urgent"). A +current (object)+ property will be present with the +affected workspace whenever the type of event affects a workspace (otherwise, +it will be +null). -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. +When the change is "focus", an +old (object)+ property will be present with the +previous workspace. 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:* --------------------- @@ -668,12 +685,12 @@ but will still be present in the "old" property. "change": "focus", "current": { "id": 28489712, - "type":4, + "type": "workspace", ... } "old": { "id": 28489715, - "type": 4, + "type": "workspace", ... } } @@ -705,14 +722,22 @@ mode is simply named default. === window event This event consists of a single serialized map containing a property -+change (string)+ which currently can indicate only that a new window -has been successfully reparented (the value will be "new"). ++change (string)+ which indicates the type of the change + +* +new+ - the window has become managed by i3 +* +close+ - the window has closed +* +focus+ - the window has received input focus +* +title+ - the window's title has changed +* +fullscreen_mode+ - the window has entered or exited fullscreen mode +* +move+ - the window has changed its position in the tree +* +floating+ - the window has transitioned to or from floating +* +urgent+ - the window has become urgent or lost its urgent status Additionally a +container (object)+ field will be present, which consists -of the window's parent container. Be aware that 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"). +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:* --------------------------- @@ -720,7 +745,7 @@ window title as "urxvt"). "change": "new", "container": { "id": 35569536, - "type": 2, + "type": "con", ... } } @@ -729,18 +754,47 @@ window title as "urxvt"). === barconfig_update event This event consists of a single serialized map reporting on options from the -barconfig of the specified bar_id that were updated in i3. The map always -consists of a property +id (string)+, which specifies to which bar instance the -sent config update belongs, a property +hidden_state (string)+, which indicates -the hidden_state of an i3bar instance, and a property +mode (string)+, which -corresponds to the current mode. +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. + +=== binding event + +This event consists of a single serialized map reporting on the details of a +binding that ran a command because of user input. The +change (sring)+ field +indicates what sort of binding event was triggered (right now it will always be ++"run"+ but may be expanded in the future). + +The +binding (object)+ field contains details about the binding that was run: + +command (string):: + The i3 command that is configured to run for this binding. +mods (array of strings):: + The modifier keys that were configured with this binding. +input_code (integer):: + If the binding was configured with +bindcode+, this will be the key code + that was given for the binding. If the binding is a mouse binding, it will be + the number of the mouse button that was pressed. Otherwise it will be 0. +symbol (string or null):: + If this is a keyboard binding that was configured with +bindsym+, this + field will contain the given symbol. Otherwise it will be +null+. +input_type (string):: + This will be +"keyboard"+ or +"mouse"+ depending on whether or not this was + a keyboard or a mouse binding. *Example:* --------------------------- { - "id": "bar-0", - "hidden_state": "hide" - "mode": "hide" + "change": "run", + "binding": { + "command": "nop", + "mods": [ + "shift", + "ctrl" + ], + "input_code": 0, + "symbol": "t", + "input_type": "keyboard" + } } --------------------------- @@ -753,14 +807,19 @@ all this on your own). This list names some (if you wrote one, please let me know): C:: - i3 includes a headerfile +i3/ipc.h+ which provides you all constants. - However, there is no library yet. -Ruby:: - http://github.com/badboy/i3-ipc -Perl:: - https://metacpan.org/module/AnyEvent::I3 -Python:: - * https://github.com/whitelynx/i3ipc - * https://github.com/ziberna/i3-py (includes higher-level features) + * i3 includes a headerfile +i3/ipc.h+ which provides you all constants. + * 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