From: Michael Stapelberg Date: Wed, 3 Oct 2012 22:00:35 +0000 (+0200) Subject: update ipc docs X-Git-Url: https://git.sur5r.net/?p=i3%2Fi3.github.io;a=commitdiff_plain;h=28ff16b683087e848dbc787f034d3d465a549938 update ipc docs --- diff --git a/_docs/ipc b/_docs/ipc index f8dfa78..6bdccd0 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -August 2012 +October 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 @@ -19,6 +19,13 @@ 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. +[WARNING] +.Use an existing library! +There are existing libraries for many languages. You can have a look at +<> or search the web if your language of choice is not mentioned. +Usually, it is not necessary to implement low-level communication with i3 +directly. + == Establishing a connection To establish a connection, simply open the IPC socket. The following code @@ -82,7 +89,7 @@ So, a typical message could look like this: Or, as a hexdump: ------------------------------------------------------------------------------ 00000000 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex| -00000010 69 74 0a |it.| +00000010 69 74 |it| ------------------------------------------------------------------------------ To generate and send such a message, you could use the following code in Perl: @@ -274,6 +281,8 @@ name (string):: border (string):: Can be either "normal", "none" or "1pixel", dependending on the container’s border style. +current_border_width (integer):: + Number of pixels of the border width. layout (string):: Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or "output". @@ -610,6 +619,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:* -------------------------------------------------------------------- @@ -651,7 +662,21 @@ This event consists of a single serialized map containing a property { "change": "unspecified" } --------------------------- -== See also +=== 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 (existing libraries) + +[[libraries]] For some languages, libraries are available (so you don’t have to implement all this on your own). This list names some (if you wrote one, please let me diff --git a/docs/ipc.html b/docs/ipc.html index 4b20c01..0459e52 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

IPC interface (interprocess communication)

Michael Stapelberg
<michael@i3wm.org>
-August 2012 +October 2012
Table of Contents
@@ -52,6 +52,18 @@ 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.

+
+ + + +
+
Warning
+		 +
Use an existing library!
There are existing libraries for many languages. You can have a look at +[libraries] or search the web if your language of choice is not mentioned. +Usually, it is not necessary to implement low-level communication with i3 +directly.
+
@@ -167,7 +179,7 @@ GET_VERSION (7) 
00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
-00000010  69 74 0a                                          |it.|
+00000010 69 74 |it|

To generate and send such a message, you could use the following code in Perl:

@@ -495,6 +507,14 @@ border (string)

+current_border_width (integer) +
+
+

+ Number of pixels of the border width. +

+
+
layout (string)
@@ -1059,6 +1079,14 @@ output (1) outputs, CRTCs or output properties).

+
+mode (2) +
+
+

+ Sent whenever i3 changes its binding mode. +

+

Example:

@@ -1101,12 +1129,24 @@ if ($is_event) { 
{ "change": "unspecified" }
+
+

4.5. 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" }
+
+
-

5. See also

+

5. See also (existing libraries)

-

For some languages, libraries are available (so you don’t have to implement +

For some languages, libraries are available (so you don’t have to implement all this on your own). This list names some (if you wrote one, please let me know):