Merge pull request #66 from martinRenou/touch_events

Implement touch events

Author: martinRenou

docs/source/events.rst

@@ -22,6 +22,22 @@ Those methods take a callback function as single argument, this callback functio
 
     canvas.on_mouse_down(handle_mouse_down)
 
+Built-in touch events
+---------------------
+
+The following built-in touch events are supported: ``touch_start``, ``touch_end``, ``touch_move`` and ``touch_cancel``. You can define Python callback functions that will be called whenever those touch events occur, using the ``on_touch_start``, ``on_touch_end``, ``on_touch_move`` and ``on_touch_cancel`` methods.
+
+Those methods take a callback function as single argument, this callback function must take one positional argument which is the list of tuples representing the ``(x, y)`` pixel coordinates where the fingers are located on the canvas.
+
+.. code:: Python
+
+    def handle_touch_move(fingers_locations):
+        # Draw circles where fingers are located
+        for finger_location in fingers_locations:
+            canvas.fill_arc(finger_location[0], finger_location[1], 6, 0, 2 * pi)
+
+    canvas.on_touch_move(handle_touch_move)
+
 .. note::
     Please open an issue or a Pull Request if you want more events to be supported by ipycanvas
 

ipycanvas/canvas.py

@@ -158,11 +158,17 @@ class Canvas(CanvasBase):
     line_dash_offset = Float(0.)
 
     _client_ready_callbacks = Instance(CallbackDispatcher, ())
+
     _mouse_move_callbacks = Instance(CallbackDispatcher, ())
     _mouse_down_callbacks = Instance(CallbackDispatcher, ())
     _mouse_up_callbacks = Instance(CallbackDispatcher, ())
     _mouse_out_callbacks = Instance(CallbackDispatcher, ())
 
+    _touch_start_callbacks = Instance(CallbackDispatcher, ())
+    _touch_end_callbacks = Instance(CallbackDispatcher, ())
+    _touch_move_callbacks = Instance(CallbackDispatcher, ())
+    _touch_cancel_callbacks = Instance(CallbackDispatcher, ())
+
     def __init__(self, *args, **kwargs):
         """Create a Canvas widget."""
         #: Whether commands should be cached or not
@@ -494,21 +500,37 @@ def on_client_ready(self, callback, remove=False):
         self._client_ready_callbacks.register_callback(callback, remove=remove)
 
     def on_mouse_move(self, callback, remove=False):
-        """Register a callback that will be called on mouse mouse_move."""
+        """Register a callback that will be called on mouse move."""
         self._mouse_move_callbacks.register_callback(callback, remove=remove)
 
     def on_mouse_down(self, callback, remove=False):
-        """Register a callback that will be called on mouse mouse_down."""
+        """Register a callback that will be called on mouse click down."""
         self._mouse_down_callbacks.register_callback(callback, remove=remove)
 
     def on_mouse_up(self, callback, remove=False):
-        """Register a callback that will be called on mouse mouse_up."""
+        """Register a callback that will be called on mouse click up."""
         self._mouse_up_callbacks.register_callback(callback, remove=remove)
 
     def on_mouse_out(self, callback, remove=False):
-        """Register a callback that will be called on mouse mouse_out."""
+        """Register a callback that will be called on mouse out of the canvas."""
         self._mouse_out_callbacks.register_callback(callback, remove=remove)
 
+    def on_touch_start(self, callback, remove=False):
+        """Register a callback that will be called on touch start (new finger on the screen)."""
+        self._touch_start_callbacks.register_callback(callback, remove=remove)
+
+    def on_touch_end(self, callback, remove=False):
+        """Register a callback that will be called on touch end (a finger is not touching the screen anymore)."""
+        self._touch_end_callbacks.register_callback(callback, remove=remove)
+
+    def on_touch_move(self, callback, remove=False):
+        """Register a callback that will be called on touch move (finger moving on the screen)."""
+        self._touch_move_callbacks.register_callback(callback, remove=remove)
+
+    def on_touch_cancel(self, callback, remove=False):
+        """Register a callback that will be called on touch cancel."""
+        self._touch_cancel_callbacks.register_callback(callback, remove=remove)
+
     def __setattr__(self, name, value):
         super(Canvas, self).__setattr__(name, value)
 
@@ -542,6 +564,7 @@ def _send_command(self, command, buffers=[]):
     def _handle_frontend_event(self, _, content, buffers):
         if content.get('event', '') == 'client_ready':
             self._client_ready_callbacks()
+
         if content.get('event', '') == 'mouse_move':
             self._mouse_move_callbacks(content['x'], content['y'])
         if content.get('event', '') == 'mouse_down':
@@ -551,6 +574,15 @@ def _handle_frontend_event(self, _, content, buffers):
         if content.get('event', '') == 'mouse_out':
             self._mouse_out_callbacks(content['x'], content['y'])
 
+        if content.get('event', '') == 'touch_start':
+            self._touch_start_callbacks([(touch['x'], touch['y']) for touch in content['touches']])
+        if content.get('event', '') == 'touch_end':
+            self._touch_end_callbacks([(touch['x'], touch['y']) for touch in content['touches']])
+        if content.get('event', '') == 'touch_move':
+            self._touch_move_callbacks([(touch['x'], touch['y']) for touch in content['touches']])
+        if content.get('event', '') == 'touch_cancel':
+            self._touch_cancel_callbacks([(touch['x'], touch['y']) for touch in content['touches']])
+
 
 class MultiCanvas(CanvasBase):
     """Create a MultiCanvas widget with n_canvases Canvas widgets.

src/widget.ts

@@ -343,6 +343,10 @@ class CanvasView extends DOMWidgetView {
     this.canvas.addEventListener('mousedown', { handleEvent: this.onMouseDown.bind(this) });
     this.canvas.addEventListener('mouseup', { handleEvent: this.onMouseUp.bind(this) });
     this.canvas.addEventListener('mouseout', { handleEvent: this.onMouseOut.bind(this) });
+    this.canvas.addEventListener('touchstart', { handleEvent: this.onTouchStart.bind(this) });
+    this.canvas.addEventListener('touchend', { handleEvent: this.onTouchEnd.bind(this) });
+    this.canvas.addEventListener('touchmove', { handleEvent: this.onTouchMove.bind(this) });
+    this.canvas.addEventListener('touchcancel', { handleEvent: this.onTouchCancel.bind(this) });
 
     this.updateCanvas();
   }
@@ -363,23 +367,43 @@ class CanvasView extends DOMWidgetView {
     this.canvas.setAttribute('height', size[1]);
   }
 
-  private onMouseDown(event: MouseEvent) {
-    this.model.send({ event: 'mouse_down', ...this.getMouseCoordinate(event) }, {});
+  private onMouseMove(event: MouseEvent) {
+    this.model.send({ event: 'mouse_move', ...this.getCoordinates(event) }, {});
   }
 
-  private onMouseMove(event: MouseEvent) {
-    this.model.send({ event: 'mouse_move', ...this.getMouseCoordinate(event) }, {});
+  private onMouseDown(event: MouseEvent) {
+    this.model.send({ event: 'mouse_down', ...this.getCoordinates(event) }, {});
   }
 
   private onMouseUp(event: MouseEvent) {
-    this.model.send({ event: 'mouse_up', ...this.getMouseCoordinate(event) }, {});
+    this.model.send({ event: 'mouse_up', ...this.getCoordinates(event) }, {});
   }
 
   private onMouseOut(event: MouseEvent) {
-    this.model.send({ event: 'mouse_out', ...this.getMouseCoordinate(event) }, {});
+    this.model.send({ event: 'mouse_out', ...this.getCoordinates(event) }, {});
+  }
+
+  private onTouchStart(event: TouchEvent) {
+    const touches: Touch[] = Array.from(event.touches);
+    this.model.send({ event: 'touch_start', touches: touches.map(this.getCoordinates.bind(this)) }, {});
+  }
+
+  private onTouchEnd(event: TouchEvent) {
+    const touches: Touch[] = Array.from(event.touches);
+    this.model.send({ event: 'touch_end', touches: touches.map(this.getCoordinates.bind(this)) }, {});
+  }
+
+  private onTouchMove(event: TouchEvent) {
+    const touches: Touch[] = Array.from(event.touches);
+    this.model.send({ event: 'touch_move', touches: touches.map(this.getCoordinates.bind(this)) }, {});
+  }
+
+  private onTouchCancel(event: TouchEvent) {
+    const touches: Touch[] = Array.from(event.touches);
+    this.model.send({ event: 'touch_cancel', touches: touches.map(this.getCoordinates.bind(this)) }, {});
   }
 
-  private getMouseCoordinate(event: MouseEvent) {
+  private getCoordinates(event: MouseEvent | Touch) {
     const rect = this.canvas.getBoundingClientRect();
     const x = event.clientX - rect.left;
     const y = event.clientY - rect.top;