i3 - improved tiling WM

IPC: Custom 'event' command documentation

Patch status: needinfo

Patch by Paul Grove

To apply this patch, use:
curl http://cr.i3wm.org/patch/275/raw.patch | git am

b/docs/ipc

14 
@@ -631,6 +631,9 @@ window (3)::
15 
 barconfig_update (4)::
16 
     Sent when the hidden_state or mode field in the barconfig of any bar
17 
     instance was updated.
18 
+custom (5)::
19 
+	Sent when triggered by the i3 +event+ command.  Custom events can be
20 
+	subscribed to under any name but always use the the same event type (5)
21
22 
 *Example:*
23 
 --------------------------------------------------------------------
24 
@@ -746,6 +749,22 @@ corresponds to the current mode.
25 
 }
26 
 ---------------------------
27
28 
+=== custom event
29 
+
30 
+This event is the result of an issued +event+ command usualy bound to a
31 
+keybinding.  The event names are custom and variable, but the message type
32 
+will allways be the same, because of this the name of the triggered event
33 
+is included along with the payload. See the i3 userguide for more information
34 
+on the +event+ command.
35 
+
36 
+*Example:*
37 
+---------------------------
38 
+{
39 
+    "event": "test",
40 
+    "payload": "Hello World"
41 
+}
42 
+---------------------------
43 
+
44 
 == See also (existing libraries)
45
46 
 [[libraries]]

b/docs/userguide

51 
@@ -1915,6 +1915,33 @@ bindsym $mod+b bar mode hide bar-1
52 
 bindsym $mod+Shift+b bar mode invisible bar-1
53 
 ------------------------------------------------
54
55 
+=== custom event
56 
+
57 
+The +event+ command is an advanced feature to pass messages to connected IPC
58 
+clients.  This allows scripters to run services that respond to commands
59 
+processed by i3.
60 
+
61 
+*Syntax*:
62 
+---------------
63 
+event <event_name> <event_data>
64 
+---------------
65 
+
66 
+<event_name> is required and can be any single word.
67 
+<event_data> is required and can be any valid string.
68 
+
69 
+Any IPC clients subscribed to the event matching <event_name> will receive an
70 
+event with a JSON blob containing the event_name and event_data sent. e.g.
71 
+
72 
+*Example*:
73 
+---------------
74 
+# If bound to a key press
75 
+bindsym $mod+y event test "Hello World"
76 
+
77 
+# The following JSON will be received by all connect IPC clients subscribed
78 
+# to the test event when $mod+y is pressed:
79 
+{"event": "test", "Hello World"}
80 
+---------------
81 
+
82 
 [[multi_monitor]]
83
84 
 == Multiple monitors