i3 - improved tiling WM

Reviews
Bugs

Implement the ipc 'binding' event

Patch status: merged

Patch by Tony Crisci

Long description:

The binding event will be triggered when a binding is run as a result of
some a user action. The binding event has the following properties:

change: (str) Currently this will only be "run" but may be expanded in
the future. Included for consistency with other events.

binding: (map) the serialized binding

The "binding" member will have these properties:

input_type: (str) either "keyboard" or "mouse"

input_code: (int) the xcb keycode of the keyboard binding if it was
provided or the mouse button if it is a mouse binding.

symbol: (str) the string representation of the input code

command: (str) the bound command

mods: (list of str) a list of the modifiers that were pressed as string
symbols

fixes #1210

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

b/docs/ipc

@@ -1,7 +1,7 @@
 IPC interface (interprocess communication)
 ==========================================
 Michael Stapelberg <michael@i3wm.org>
-February 2014
+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
@@ -638,6 +638,9 @@ window (3)::
 barconfig_update (4)::
     Sent when the hidden_state or mode field in the barconfig of any bar
     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:*
 --------------------------------------------------------------------
@@ -749,6 +752,47 @@ This event consists of a single serialized map reporting on options from the
 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)::
+	If this is a keyboard binding that was configured with +bindsym+, this
+	field will contain the given symbol.
+input_type (string)::
+	This will be +"keyboard"+ or +"mouse"+ depending on whether or not this was
+	a keyboard or a mouse binding.
+
+*Example:*
+---------------------------
+{
+ "change": "run",
+ "binding": {
+  "command": "nop",
+  "mods": [
+    "shift",
+    "ctrl"
+  ],
+  "input_code": 0,
+  "symbol": "t",
+  "input_type": "keyboard"
+ }
+}
+---------------------------
+
 == See also (existing libraries)
 
 [[libraries]]

b/include/i3/ipc.h

@@ -100,3 +100,6 @@ typedef struct i3_ipc_header {
 
 /** Bar config update will be triggered to update the bar config */
 #define I3_IPC_EVENT_BARCONFIG_UPDATE (I3_IPC_EVENT_MASK | 4)
+
+/** The binding event will be triggered when bindings run */
+#define I3_IPC_EVENT_BINDING (I3_IPC_EVENT_MASK | 5)

b/include/ipc.h

@@ -105,3 +105,8 @@ void ipc_send_window_event(const char *property, Con *con);
  * For the barconfig update events, we send the serialized barconfig.
  */
 void ipc_send_barconfig_update_event(Barconfig *barconfig);
+
+/**
+ * For the binding events, we send the serialized binding struct.
+ */
+void ipc_send_binding_event(const char *event_type, Binding *bind);

b/src/bindings.c

@@ -423,7 +423,7 @@ CommandResult *run_binding(Binding *bind, Con *con) {
         free(pageraction);
     }
 
-    /* TODO: emit event for running a binding */
+    ipc_send_binding_event("run", bind);
 
     return result;
 }

b/src/ipc.c

@@ -151,6 +151,57 @@ static void dump_rect(yajl_gen gen, const char *name, Rect r) {
     y(map_close);
 }
 
+static void dump_binding(yajl_gen gen, Binding *bind) {
+    y(map_open);
+    ystr("input_code");
+    y(integer, bind->keycode);
+
+    ystr("input_type");
+    ystr((const char*)(bind->input_type == B_KEYBOARD ? "keyboard" : "mouse"));
+
+    ystr("symbol");
+    ystr(bind->symbol);
+
+    ystr("command");
+    ystr(bind->command);
+
+    ystr("mods");
+    y(array_open);
+    for (int i = 0; i < 8; i++) {
+        if (bind->mods & (1 << i)) {
+            switch (1 << i) {
+                case XCB_MOD_MASK_SHIFT:
+                    ystr("shift");
+                    break;
+                case XCB_MOD_MASK_LOCK:
+                    ystr("lock");
+                    break;
+                case XCB_MOD_MASK_CONTROL:
+                    ystr("ctrl");
+                    break;
+                case XCB_MOD_MASK_1:
+                    ystr("Mod1");
+                    break;
+                case XCB_MOD_MASK_2:
+                    ystr("Mod2");
+                    break;
+                case XCB_MOD_MASK_3:
+                    ystr("Mod3");
+                    break;
+                case XCB_MOD_MASK_4:
+                    ystr("Mod4");
+                    break;
+                case XCB_MOD_MASK_5:
+                    ystr("Mod5");
+                    break;
+            }
+        }
+    }
+    y(array_close);
+
+    y(map_close);
+}
+
 void dump_node(yajl_gen gen, struct Con *con, bool inplace_restart) {
     y(map_open);
     ystr("id");
@@ -1146,3 +1197,33 @@ void ipc_send_barconfig_update_event(Barconfig *barconfig) {
     y(free);
     setlocale(LC_NUMERIC, "");
 }
+
+/*
+ * For the binding events, we send the serialized binding struct.
+ */
+void ipc_send_binding_event(const char *event_type, Binding *bind) {
+    DLOG("Issue IPC binding %s event (sym = %s, code = %d)\n", event_type, bind->symbol, bind->keycode);
+
+    setlocale(LC_NUMERIC, "C");
+
+    yajl_gen gen = ygenalloc();
+
+    y(map_open);
+
+    ystr("change");
+    ystr(event_type);
+
+    ystr("binding");
+    dump_binding(gen, bind);
+
+    y(map_close);
+
+    const unsigned char *payload;
+    ylength length;
+    y(get_buf, &payload, &length);
+
+    ipc_send_event("binding", I3_IPC_EVENT_BINDING, (const char *)payload);
+
+    y(free);
+    setlocale(LC_NUMERIC, "");
+}

b/testcases/t/238-ipc-binding-event.t

@@ -0,0 +1,86 @@
+#!perl
+# vim:ts=4:sw=4:expandtab
+#
+# Please read the following documents before working on tests:
+# • http://build.i3wm.org/docs/testsuite.html
+#   (or docs/testsuite)
+#
+# • http://build.i3wm.org/docs/lib-i3test.html
+#   (alternatively: perldoc ./testcases/lib/i3test.pm)
+#
+# • http://build.i3wm.org/docs/ipc.html
+#   (or docs/ipc)
+#
+# • http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf
+#   (unless you are already familiar with Perl)
+#
+# Test that the binding event works properly
+# Ticket: #1210
+use i3test i3_autostart => 0;
+
+my $keysym = 't';
+my $command = 'nop';
+my @mods = ('Shift', 'Ctrl');
+my $binding_symbol = join("+", @mods) . "+$keysym";
+
+my $config = <<EOT;
+# i3 config file (v4)
+font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+
+bindsym $binding_symbol $command
+EOT
+
+SKIP: {
+    qx(which xdotool 2> /dev/null);
+
+    skip 'xdotool is required to test the binding event. `[apt-get install|pacman -S] xdotool`', 1 if $?;
+
+    my $pid = launch_with_config($config);
+
+    my $i3 = i3(get_socket_path());
+    $i3->connect->recv;
+
+    my $cv = AE::cv;
+    my $timer = AE::timer 0.5, 0, sub { $cv->send(0); };
+
+    $i3->subscribe({
+            binding => sub {
+                $cv->send(shift);
+            }
+        })->recv;
+
+    qx(xdotool key $binding_symbol);
+
+    my $e = $cv->recv;
+
+    does_i3_live;
+
+    diag "Event:\n", Dumper($e);
+
+    ok($e,
+        'the binding event should emit when user input triggers an i3 binding event');
+
+    is($e->{change}, 'run',
+        'the `change` field should indicate this binding has run');
+
+    ok($e->{binding},
+        'the `binding` field should be a hash that contains information about the binding');
+
+    is($e->{binding}->{input_type}, 'keyboard',
+        'the input_type field should be the input type of the binding (keyboard or mouse)');
+
+    note 'the `mods` field should contain the symbols for the modifiers of the binding';
+    foreach (@mods) {
+        ok(grep(/$_/i, @{$e->{binding}->{mods}}), "`mods` contains the modifier $_");
+    }
+
+    is($e->{binding}->{command}, $command,
+        'the `command` field should contain the command the binding ran');
+
+    is($e->{binding}->{input_code}, 0,
+        'the input_code should be the specified code if the key was bound with bindcode, and otherwise zero');
+
+    exit_gracefully($pid);
+
+}
+done_testing;

124	@@ -105,3 +105,8 @@ void ipc_send_window_event(const char property, Con con);
125	* For the barconfig update events, we send the serialized barconfig.
126	*/
127	void ipc_send_barconfig_update_event(Barconfig *barconfig);
128	+
129	+/**
130	+ * For the binding events, we send the serialized binding struct.
131	+ */
132	+void ipc_send_binding_event(const char event_type, Binding bind);

137	@@ -423,7 +423,7 @@ CommandResult run_binding(Binding bind, Con *con) {
138	free(pageraction);
139	}
140
141	- /* TODO: emit event for running a binding */
142	+ ipc_send_binding_event("run", bind);
143
144	return result;
145	}

150	@@ -151,6 +151,57 @@ static void dump_rect(yajl_gen gen, const char *name, Rect r) {
151	y(map_close);
152	}
153
154	+static void dump_binding(yajl_gen gen, Binding *bind) {
155	+ y(map_open);
156	+ ystr("input_code");
157	+ y(integer, bind->keycode);
158	+
159	+ ystr("input_type");
160	+ ystr((const char*)(bind->input_type == B_KEYBOARD ? "keyboard" : "mouse"));
161	+
162	+ ystr("symbol");
163	+ ystr(bind->symbol);
164	+
165	+ ystr("command");
166	+ ystr(bind->command);
167	+
168	+ ystr("mods");
169	+ y(array_open);
170	+ for (int i = 0; i < 8; i++) {
171	+ if (bind->mods & (1 << i)) {
172	+ switch (1 << i) {
173	+ case XCB_MOD_MASK_SHIFT:
174	+ ystr("shift");
175	+ break;
176	+ case XCB_MOD_MASK_LOCK:
177	+ ystr("lock");
178	+ break;
179	+ case XCB_MOD_MASK_CONTROL:
180	+ ystr("ctrl");
181	+ break;
182	+ case XCB_MOD_MASK_1:
183	+ ystr("Mod1");
184	+ break;
185	+ case XCB_MOD_MASK_2:
186	+ ystr("Mod2");
187	+ break;
188	+ case XCB_MOD_MASK_3:
189	+ ystr("Mod3");
190	+ break;
191	+ case XCB_MOD_MASK_4:
192	+ ystr("Mod4");
193	+ break;
194	+ case XCB_MOD_MASK_5:
195	+ ystr("Mod5");
196	+ break;
197	+ }
198	+ }
199	+ }
200	+ y(array_close);
201	+
202	+ y(map_close);
203	+}
204	+
205	void dump_node(yajl_gen gen, struct Con *con, bool inplace_restart) {
206	y(map_open);
207	ystr("id");
208	@@ -1146,3 +1197,33 @@ void ipc_send_barconfig_update_event(Barconfig *barconfig) {
209	y(free);
210	setlocale(LC_NUMERIC, "");
211	}
212	+
213	+/*
214	+ * For the binding events, we send the serialized binding struct.
215	+ */
216	+void ipc_send_binding_event(const char event_type, Binding bind) {
217	+ DLOG("Issue IPC binding %s event (sym = %s, code = %d)\n", event_type, bind->symbol, bind->keycode);
218	+
219	+ setlocale(LC_NUMERIC, "C");
220	+
221	+ yajl_gen gen = ygenalloc();
222	+
223	+ y(map_open);
224	+
225	+ ystr("change");
226	+ ystr(event_type);
227	+
228	+ ystr("binding");
229	+ dump_binding(gen, bind);
230	+
231	+ y(map_close);
232	+
233	+ const unsigned char *payload;
234	+ ylength length;
235	+ y(get_buf, &payload, &length);
236	+
237	+ ipc_send_event("binding", I3_IPC_EVENT_BINDING, (const char *)payload);
238	+
239	+ y(free);
240	+ setlocale(LC_NUMERIC, "");
241	+}

247	@@ -0,0 +1,86 @@
248	+#!perl
249	+# vim:ts=4:sw=4:expandtab
250	+#
251	+# Please read the following documents before working on tests:
252	+# • http://build.i3wm.org/docs/testsuite.html
253	+# (or docs/testsuite)
254	+#
255	+# • http://build.i3wm.org/docs/lib-i3test.html
256	+# (alternatively: perldoc ./testcases/lib/i3test.pm)
257	+#
258	+# • http://build.i3wm.org/docs/ipc.html
259	+# (or docs/ipc)
260	+#
261	+# • http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf
262	+# (unless you are already familiar with Perl)
263	+#
264	+# Test that the binding event works properly
265	+# Ticket: #1210
266	+use i3test i3_autostart => 0;
267	+
268	+my $keysym = 't';
269	+my $command = 'nop';
270	+my @mods = ('Shift', 'Ctrl');
271	+my $binding_symbol = join("+", @mods) . "+$keysym";
272	+
273	+my $config = <<EOT;
274	+# i3 config file (v4)
275	+font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
276	+
277	+bindsym $binding_symbol $command
278	+EOT
279	+
280	+SKIP: {
281	+ qx(which xdotool 2> /dev/null);
282	+
283	+ skip 'xdotool is required to test the binding event. `[apt-get install\|pacman -S] xdotool`', 1 if $?;
284	+
285	+ my $pid = launch_with_config($config);
286	+
287	+ my $i3 = i3(get_socket_path());
288	+ $i3->connect->recv;
289	+
290	+ my $cv = AE::cv;
291	+ my $timer = AE::timer 0.5, 0, sub { $cv->send(0); };
292	+
293	+ $i3->subscribe({
294	+ binding => sub {
295	+ $cv->send(shift);
296	+ }
297	+ })->recv;
298	+
299	+ qx(xdotool key $binding_symbol);
300	+
301	+ my $e = $cv->recv;
302	+
303	+ does_i3_live;
304	+
305	+ diag "Event:\n", Dumper($e);
306	+
307	+ ok($e,
308	+ 'the binding event should emit when user input triggers an i3 binding event');
309	+
310	+ is($e->{change}, 'run',
311	+ 'the `change` field should indicate this binding has run');
312	+
313	+ ok($e->{binding},
314	+ 'the `binding` field should be a hash that contains information about the binding');
315	+
316	+ is($e->{binding}->{input_type}, 'keyboard',
317	+ 'the input_type field should be the input type of the binding (keyboard or mouse)');
318	+
319	+ note 'the `mods` field should contain the symbols for the modifiers of the binding';
320	+ foreach (@mods) {
321	+ ok(grep(/$_/i, @{$e->{binding}->{mods}}), "`mods` contains the modifier $_");
322	+ }
323	+
324	+ is($e->{binding}->{command}, $command,
325	+ 'the `command` field should contain the command the binding ran');
326	+
327	+ is($e->{binding}->{input_code}, 0,
328	+ 'the input_code should be the specified code if the key was bound with bindcode, and otherwise zero');
329	+
330	+ exit_gracefully($pid);
331	+
332	+}
333	+done_testing;

42	@@ -1,7 +1,7 @@
43	IPC interface (interprocess communication)
44	==========================================
45	Michael Stapelberg <michael@i3wm.org>
46	-February 2014
47	+October 2014
48
49	This document describes how to interface with i3 from a separate process. This
50	is useful for example to remote-control i3 (to write test cases for example) or
51	@@ -638,6 +638,9 @@ window (3)::
52	barconfig_update (4)::
53	Sent when the hidden_state or mode field in the barconfig of any bar
54	instance was updated and when the config is reloaded.
55	+binding (5)::
56	+ Sent when a configured command binding is triggered with the keyboard or
57	+ mouse
58
59	Example:
60	--------------------------------------------------------------------
61	@@ -749,6 +752,47 @@ This event consists of a single serialized map reporting on options from the
62	barconfig of the specified bar_id that were updated in i3. This event is the
63	same as a +GET_BAR_CONFIG+ reply for the bar with the given id.
64
65	+=== binding event
66	+
67	+This event consists of a single serialized map reporting on the details of a
68	+binding that ran a command because of user input. The +change (sring)+ field
69	+indicates what sort of binding event was triggered (right now it will always be
70	++"run"+ but may be expanded in the future).
71	+
72	+The +binding (object)+ field contains details about the binding that was run:
73	+
74	+command (string)::
75	+ The i3 command that is configured to run for this binding.
76	+mods (array of strings)::
77	+ The modifier keys that were configured with this binding.
78	+input_code (integer)::
79	+ If the binding was configured with +bindcode+, this will be the key code
80	+ that was given for the binding. If the binding is a mouse binding, it will be
81	+ the number of the mouse button that was pressed. Otherwise it will be 0.
82	+symbol (string)::
83	+ If this is a keyboard binding that was configured with +bindsym+, this
84	+ field will contain the given symbol.
85	+input_type (string)::
86	+ This will be +"keyboard"+ or +"mouse"+ depending on whether or not this was
87	+ a keyboard or a mouse binding.
88	+
89	+Example:
90	+---------------------------
91	+{
92	+ "change": "run",
93	+ "binding": {
94	+ "command": "nop",
95	+ "mods": [
96	+ "shift",
97	+ "ctrl"
98	+ ],
99	+ "input_code": 0,
100	+ "symbol": "t",
101	+ "input_type": "keyboard"
102	+ }
103	+}
104	+---------------------------
105	+
106	== See also (existing libraries)
107
108	[[libraries]]

113	@@ -100,3 +100,6 @@ typedef struct i3_ipc_header {
114
115	/** Bar config update will be triggered to update the bar config */
116	#define I3_IPC_EVENT_BARCONFIG_UPDATE (I3_IPC_EVENT_MASK \| 4)
117	+
118	+/** The binding event will be triggered when bindings run */
119	+#define I3_IPC_EVENT_BINDING (I3_IPC_EVENT_MASK \| 5)