X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=docs%2Fipc;h=4a2b1df91ed27ca7dd5565b9809b89345265bf7a;hb=04fa40d3e5e11be98a89d5d97c395f95a6d08e37;hp=e4f1e80c48f76a1f5ef984a5af9d9dff6d6f959f;hpb=2314f107784196d8fc7ee500645dbdf548f91386;p=i3%2Fi3 diff --git a/docs/ipc b/docs/ipc index e4f1e80c..4a2b1df9 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, @@ -315,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. @@ -612,7 +617,7 @@ you can register to an event. *Example:* --------------------------------- type: SUBSCRIBE -payload: [ "workspace", "focus" ] +payload: [ "workspace", "output" ] --------------------------------- @@ -632,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:* -------------------------------------------------------------------- @@ -712,14 +721,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:* --------------------------- @@ -736,18 +753,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" + } } --------------------------- @@ -760,14 +806,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