Merge pull request #42 from martinRenou/client_event

Add client_ready event

Author: martinRenou

docs/source/advanced.rst

@@ -0,0 +1,27 @@
+Advanced usage
+==============
+
+ipycanvas in Voilà
+------------------
+
+The ``Canvas`` is a stateless widget, in that the actual state of the ``Canvas`` (pixel colors, transformation state, etc) is not saved nor synchronized between the Python kernel and the client page. This means that whenever a new client connects to the kernel, it will get a blank canvas and you would need to replay all your drawings.
+
+This is an ipycanvas limitation, but it's also a way to keep it fast (not having to synchronize everything).
+
+This limitation results in ipycanvas not working with `Voilà <https://github.com/voila-dashboards/voila>`_ out of the box. Because the Voilà page connects to the kernel only when the entire Notebook has been executed, all the drawings may already have happened and the canvas end up being blank when it's created.
+
+A way to work around this is to perform your drawings in a callback that gets called when the client is ready to receive drawings, using the ``on_client_ready`` method:
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(size=(100, 50))
+
+    def perform_drawings():
+        canvas.font = '32px serif'
+        canvas.fill_text('Voilà!', 10, 32)
+
+    canvas.on_client_ready(perform_drawings)
+
+    canvas

docs/source/index.rst

@@ -30,6 +30,7 @@ You can try ipycanvas, without the need of installing anything on your computer,
     drawing_images
     canvas_state
     transformations
+    advanced
 
 .. toctree::
     :caption: API Reference

ipycanvas/canvas.py

@@ -10,7 +10,7 @@
 
 from traitlets import Enum, Float, Instance, List, Tuple, Unicode, observe
 
-from ipywidgets import Color, DOMWidget, widget_serialization
+from ipywidgets import CallbackDispatcher, Color, DOMWidget, widget_serialization
 
 from ._frontend import module_name, module_version
 
@@ -91,6 +91,8 @@ class Canvas(DOMWidget):
     #: (float) Specifies where to start a dash array on a line. Default is ``0.``.
     line_dash_offset = Float(0.)
 
+    _client_ready_callbacks = Instance(CallbackDispatcher, ())
+
     def __init__(self, *args, **kwargs):
         """Create a Canvas widget."""
         #: Whether commands should be cached or not
@@ -102,6 +104,8 @@ def __init__(self, *args, **kwargs):
         self.layout.width = str(self.size[0]) + 'px'
         self.layout.height = str(self.size[1]) + 'px'
 
+        self.on_msg(self._handle_frontend_event)
+
     # Rectangles methods
     def fill_rect(self, x, y, width, height=None):
         """Draw a filled rectangle of size ``(width, height)`` at the ``(x, y)`` position."""
@@ -396,6 +400,17 @@ def flush(self):
         self._commands_cache = []
         self._buffers_cache = []
 
+    # Events
+    def on_client_ready(self, callback, remove=False):
+        """Register a callback that will be called when a new client is ready to receive draw commands.
+
+        When a new client connects to the kernel he will get an empty Canvas (because the canvas is
+        almost stateless, the new client does not know what draw commands were previously sent). So
+        this function is useful for replaying your drawing whenever a new client connects and is
+        ready to receive draw commands.
+        """
+        self._client_ready_callbacks.register_callback(callback, remove=remove)
+
     def __setattr__(self, name, value):
         super(Canvas, self).__setattr__(name, value)
 
@@ -425,6 +440,10 @@ def _send_command(self, command, buffers=[]):
         else:
             self.send(command, buffers)
 
+    def _handle_frontend_event(self, _, content, buffers):
+        if content.get('event', '') == 'client_ready':
+            self._client_ready_callbacks()
+
 
 class MultiCanvas(DOMWidget):
     """Create a MultiCanvas widget with n_canvases Canvas widgets.
@@ -462,6 +481,16 @@ def _on_size_change(self, change):
         for canvas in self._canvases:
             canvas.size = change.new
 
+    def on_client_ready(self, callback, remove=False):
+        """Register a callback that will be called when a new client is ready to receive draw commands.
+
+        When a new client connects to the kernel he will get an empty Canvas (because the canvas is
+        almost stateless, the new client does not know what draw commands were previously sent). So
+        this function is useful for replaying your drawing whenever a new client connects and is
+        ready to receive draw commands.
+        """
+        self._canvases[-1]._client_ready_callbacks.register_callback(callback, remove=remove)
+
 
 @contextmanager
 def hold_canvas(canvas):

src/widget.ts

@@ -51,6 +51,8 @@ class CanvasModel extends DOMWidgetModel {
 
     this.on('change:size', this.resizeCanvas.bind(this));
     this.on('msg:custom', this.onCommand.bind(this));
+
+    this.send({ event: 'client_ready' }, {});
   }
 
   private onCommand(command: any, buffers: any) {