Merge pull request #6454 from jasongrout/links

Javascript link

IPython/html/static/widgets/js/widget_link.js

@@ -0,0 +1,86 b''
+// Copyright (c) IPython Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+define([
+    "widgets/js/widget",
+    "jquery",
+], function(widget, $){
+    var LinkModel = widget.WidgetModel.extend({
+        initialize: function() {
+            this.on("change:widgets", function(model, value, options) {
+                this.update_bindings(model.previous("widgets") || [], value);
+                this.update_value(this.get("widgets")[0]);
+            }, this);
+            this.once("destroy", function(model, collection, options) {
+                this.update_bindings(this.get("widgets"), []);
+            }, this);
+        },
+        update_bindings: function(oldlist, newlist) {
+            var that = this;
+            _.each(oldlist, function(elt) {elt[0].off("change:" + elt[1], null, that);});
+            _.each(newlist, function(elt) {elt[0].on("change:" + elt[1],
+                                                     function(model, value, options) {
+                                                         that.update_value(elt);
+                                                     }, that);
+                                           // TODO: register for any destruction handlers
+                                           // to take an item out of the list
+                                          });
+        },
+        update_value: function(elt) {
+            if (this.updating) {return;}
+            var model = elt[0];
+            var attr = elt[1];
+            var new_value = model.get(attr);
+            this.updating = true;
+            _.each(_.without(this.get("widgets"), elt),
+                   function(element, index, list) {
+                       if (element[0]) {
+                           element[0].set(element[1], new_value);
+                           element[0].save_changes();
+                       }
+                   }, this);
+            this.updating = false;
+        },
+    });
+
+    var DirectionalLinkModel = widget.WidgetModel.extend({
+        initialize: function() {
+            this.on("change", this.update_bindings, this);
+            this.once("destroy", function() {
+                if (this.source) {
+                    this.source[0].off("change:" + this.source[1], null, this);
+                }
+            }, this);
+        },
+        update_bindings: function() {
+            if (this.source) {
+                this.source[0].off("change:" + this.source[1], null, this);
+            }
+            this.source = this.get("source");
+            if (this.source) {
+                this.source[0].on("change:" + this.source[1], function() { this.update_value(this.source); }, this);
+                this.update_value(this.source);
+            }
+        },
+        update_value: function(elt) {
+            if (this.updating) {return;}
+            var model = elt[0];
+            var attr = elt[1];
+            var new_value = model.get(attr);
+            this.updating = true;
+            _.each(this.get("targets"),
+                   function(element, index, list) {
+                       if (element[0]) {
+                           element[0].set(element[1], new_value);
+                           element[0].save_changes();
+                       }
+                   }, this);
+            this.updating = false;
+        },
+    });
+
+    return {
+        "LinkModel": LinkModel,
+        "DirectionalLinkModel": DirectionalLinkModel,
+    }
+});

IPython/html/widgets/widget_link.py

@@ -0,0 +1,61 b''
+"""Link and DirectionalLink classes.
+
+Propagate changes between widgets on the javascript side
+"""
+#-----------------------------------------------------------------------------
+# Copyright (c) 2014, the IPython Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+from .widget import Widget
+from IPython.utils.traitlets import Unicode, Tuple, Any
+
+#-----------------------------------------------------------------------------
+# Classes
+#-----------------------------------------------------------------------------
+
+
+class Link(Widget):
+    """Link Widget"""
+    _model_name = Unicode('LinkModel', sync=True)
+    widgets = Tuple(sync=True, allow_none=False)
+
+    def __init__(self, widgets=(), **kwargs):
+        kwargs['widgets'] = widgets
+        super(Link, self).__init__(**kwargs)
+
+    # for compatibility with traitlet links
+    def unlink(self):
+        self.close()
+
+
+def link(*args):
+    return Link(widgets=args)
+
+
+class DirectionalLink(Widget):
+    """Directional Link Widget"""
+    _model_name = Unicode('DirectionalLinkModel', sync=True)
+    targets = Any(sync=True)
+    source = Tuple(sync=True)
+
+    # Does not quite behave like other widgets but reproduces
+    # the behavior of IPython.utils.traitlets.directional_link
+    def __init__(self, source, targets=(), **kwargs):
+        kwargs['source'] = source
+        kwargs['targets'] = targets
+        super(DirectionalLink, self).__init__(**kwargs)
+
+    # for compatibility with traitlet links
+    def unlink(self):
+        self.close()
+
+
+def dlink(source, *targets):
+    return DirectionalLink(source, targets)

IPython/html/static/services/kernels/comm.js

@@ -1,217 +1,217 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
 ], function(IPython, $, utils) {
     "use strict";
 
     //-----------------------------------------------------------------------
     // CommManager class
     //-----------------------------------------------------------------------
     
     var CommManager = function (kernel) {
         this.comms = {};
         this.targets = {};
         if (kernel !== undefined) {
             this.init_kernel(kernel);
         }
     };
     
     CommManager.prototype.init_kernel = function (kernel) {
         /**
          * connect the kernel, and register message handlers
          */
         this.kernel = kernel;
         var msg_types = ['comm_open', 'comm_msg', 'comm_close'];
         for (var i = 0; i < msg_types.length; i++) {
             var msg_type = msg_types[i];
             kernel.register_iopub_handler(msg_type, $.proxy(this[msg_type], this));
         }
     };
     
     CommManager.prototype.new_comm = function (target_name, data, callbacks, metadata) {
         /**
          * Create a new Comm, register it, and open its Kernel-side counterpart
          * Mimics the auto-registration in `Comm.__init__` in the IPython Comm
          */
         var comm = new Comm(target_name);
         this.register_comm(comm);
         comm.open(data, callbacks, metadata);
         return comm;
     };
     
     CommManager.prototype.register_target = function (target_name, f) {
         /**
          * Register a target function for a given target name
          */
         this.targets[target_name] = f;
     };
     
     CommManager.prototype.unregister_target = function (target_name, f) {
         /**
          * Unregister a target function for a given target name
          */
         delete this.targets[target_name];
     };
     
     CommManager.prototype.register_comm = function (comm) {
         /**
          * Register a comm in the mapping
          */
         this.comms[comm.comm_id] = Promise.resolve(comm);
         comm.kernel = this.kernel;
         return comm.comm_id;
     };
     
     CommManager.prototype.unregister_comm = function (comm) {
         /**
          * Remove a comm from the mapping
          */
         delete this.comms[comm.comm_id];
     };
     
     // comm message handlers
     
     CommManager.prototype.comm_open = function (msg) {
         var content = msg.content;
         var that = this;
         var comm_id = content.comm_id;
 
         this.comms[comm_id] = utils.load_class(content.target_name, content.target_module, 
             this.targets).then(function(target) {
                 var comm = new Comm(content.target_name, comm_id);
                 comm.kernel = that.kernel;
                 try {
                     var response = target(comm, msg);
                 } catch (e) {
                     comm.close();
                     that.unregister_comm(comm);
                     var wrapped_error = new utils.WrappedError("Exception opening new comm", e);
                     console.error(wrapped_error);
                     return Promise.reject(wrapped_error);
                 }
                 // Regardless of the target return value, we need to
                 // then return the comm
                 return Promise.resolve(response).then(function() {return comm;});
             }, utils.reject('Could not open comm', true));
         return this.comms[comm_id];
     };
     
     CommManager.prototype.comm_close = function(msg) {
         var content = msg.content;
         if (this.comms[content.comm_id] === undefined) {
             console.error('Comm promise not found for comm id ' + content.comm_id);
             return;
         }
-
+        var that = this;
         this.comms[content.comm_id] = this.comms[content.comm_id].then(function(comm) {
-            this.unregister_comm(comm);
+            that.unregister_comm(comm);
             try {
                 comm.handle_close(msg);
             } catch (e) {
                 console.log("Exception closing comm: ", e, e.stack, msg);
             }
             // don't return a comm, so that further .then() functions
             // get an undefined comm input
         });
     };
     
     CommManager.prototype.comm_msg = function(msg) {
         var content = msg.content;
         if (this.comms[content.comm_id] === undefined) {
             console.error('Comm promise not found for comm id ' + content.comm_id);
             return;
         }
 
         this.comms[content.comm_id] = this.comms[content.comm_id].then(function(comm) {
             try {
                 comm.handle_msg(msg);
             } catch (e) {
                 console.log("Exception handling comm msg: ", e, e.stack, msg);
             }
             return comm;
         });
     };
     
     //-----------------------------------------------------------------------
     // Comm base class
     //-----------------------------------------------------------------------
     
     var Comm = function (target_name, comm_id) {
         this.target_name = target_name;
         this.comm_id = comm_id || utils.uuid();
         this._msg_callback = this._close_callback = null;
     };
     
     // methods for sending messages
     Comm.prototype.open = function (data, callbacks, metadata) {
         var content = {
             comm_id : this.comm_id,
             target_name : this.target_name,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_open", content, callbacks, metadata);
     };
     
     Comm.prototype.send = function (data, callbacks, metadata, buffers) {
         var content = {
             comm_id : this.comm_id,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_msg", content, callbacks, metadata, buffers);
     };
     
     Comm.prototype.close = function (data, callbacks, metadata) {
         var content = {
             comm_id : this.comm_id,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_close", content, callbacks, metadata);
     };
     
     // methods for registering callbacks for incoming messages
     Comm.prototype._register_callback = function (key, callback) {
         this['_' + key + '_callback'] = callback;
     };
     
     Comm.prototype.on_msg = function (callback) {
         this._register_callback('msg', callback);
     };
     
     Comm.prototype.on_close = function (callback) {
         this._register_callback('close', callback);
     };
     
     // methods for handling incoming messages
     
     Comm.prototype._callback = function (key, msg) {
         var callback = this['_' + key + '_callback'];
         if (callback) {
             try {
                 callback(msg);
             } catch (e) {
                 console.log("Exception in Comm callback", e, e.stack, msg);
             }
         }
     };
     
     Comm.prototype.handle_msg = function (msg) {
         this._callback('msg', msg);
     };
     
     Comm.prototype.handle_close = function (msg) {
         this._callback('close', msg);
     };
     
     // For backwards compatability.
     IPython.CommManager = CommManager;
     IPython.Comm = Comm;
 
     return {
         'CommManager': CommManager,
         'Comm': Comm
     };
 });

IPython/html/static/widgets/js/init.js

@@ -1,28 +1,34 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/manager",
+    "widgets/js/widget_link",
     "widgets/js/widget_bool",
     "widgets/js/widget_button",
     "widgets/js/widget_box",
     "widgets/js/widget_float",
     "widgets/js/widget_image",
     "widgets/js/widget_int",
     "widgets/js/widget_output",
     "widgets/js/widget_selection",
     "widgets/js/widget_selectioncontainer",
     "widgets/js/widget_string",
-], function(widgetmanager) { 
+], function(widgetmanager, linkModels) {
+    for (var target_name in linkModels) {
+        if (linkModels.hasOwnProperty(target_name)) {
+            widgetmanager.WidgetManager.register_widget_model(target_name, linkModels[target_name]);
+        }
+    }
 
     // Register all of the loaded views with the widget manager.
-    for (var i = 1; i < arguments.length; i++) {
+    for (var i = 2; i < arguments.length; i++) {
         for (var target_name in arguments[i]) {
             if (arguments[i].hasOwnProperty(target_name)) {
                 widgetmanager.WidgetManager.register_widget_view(target_name, arguments[i][target_name]);
             }
         }
     }
 
     return {'WidgetManager': widgetmanager.WidgetManager}; 
 });

IPython/html/widgets/__init__.py

@@ -1,29 +1,30 b''
 from .widget import Widget, DOMWidget, CallbackDispatcher, register
 
 from .widget_bool import Checkbox, ToggleButton
 from .widget_button import Button
 from .widget_box import Box, Popup, FlexBox, HBox, VBox
 from .widget_float import FloatText, BoundedFloatText, FloatSlider, FloatProgress, FloatRangeSlider
 from .widget_image import Image
 from .widget_int import IntText, BoundedIntText, IntSlider, IntProgress, IntRangeSlider
 from .widget_output import Output
 from .widget_selection import RadioButtons, ToggleButtons, Dropdown, Select
 from .widget_selectioncontainer import Tab, Accordion
 from .widget_string import HTML, Latex, Text, Textarea
 from .interaction import interact, interactive, fixed, interact_manual
+from .widget_link import Link, link, DirectionalLink, dlink
 
 # Deprecated classes
 from .widget_bool import CheckboxWidget, ToggleButtonWidget
 from .widget_button import ButtonWidget
 from .widget_box import ContainerWidget, PopupWidget
 from .widget_float import FloatTextWidget, BoundedFloatTextWidget, FloatSliderWidget, FloatProgressWidget
 from .widget_image import ImageWidget
 from .widget_int import IntTextWidget, BoundedIntTextWidget, IntSliderWidget, IntProgressWidget
 from .widget_selection import RadioButtonsWidget, ToggleButtonsWidget, DropdownWidget, SelectWidget
 from .widget_selectioncontainer import TabWidget, AccordionWidget
 from .widget_string import HTMLWidget, LatexWidget, TextWidget, TextareaWidget
 
 # Warn on import
 from IPython.utils.warn import warn
 warn("""The widget API is still considered experimental and 
     may change by the next major release of IPython.""")

examples/Interactive Widgets/Widget Events.ipynb

@@ -1,228 +1,383 b''
 {
  "cells": [
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Styling.ipynb)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
      "slide_type": "slide"
     }
    },
    "source": [
     "# Widget Events"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Special events"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "from __future__ import print_function"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The `Button` is not used to represent a data type.  Instead the button widget is used to **handle mouse clicks**.  The **`on_click` method** of the `Button` can be used to register function to be called when the button is clicked.  The doc string of the `on_click` can be seen below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "from IPython.html import widgets\n",
     "print(widgets.Button.on_click.__doc__)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
      "slide_type": "slide"
     }
    },
    "source": [
     "### Example"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Since button clicks are **stateless**, they are **transmitted from the front-end to the back-end using custom messages**.  By using the `on_click` method, a button that prints a message when it has been clicked is shown below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "from IPython.display import display\n",
     "button = widgets.Button(description=\"Click Me!\")\n",
     "display(button)\n",
     "\n",
     "def on_button_clicked(b):\n",
     "    print(\"Button clicked.\")\n",
     "\n",
     "button.on_click(on_button_clicked)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
      "slide_type": "slide"
     }
    },
    "source": [
     "### on_sumbit"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The **`Text`** also has a special **`on_submit` event**.  The `on_submit` event **fires when the user hits return**."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "text = widgets.Text()\n",
     "display(text)\n",
     "\n",
     "def handle_submit(sender):\n",
     "    print(text.value)\n",
     "\n",
     "text.on_submit(handle_submit)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
      "slide_type": "slide"
     }
    },
    "source": [
     "## Traitlet events"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "**Widget properties are IPython traitlets** and **traitlets are eventful**.  To handle  changes, the **`on_trait_change` method** of the widget can be used to **register a callback**.  The doc string for `on_trait_change` can be seen below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "print(widgets.Widget.on_trait_change.__doc__)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {
     "slideshow": {
      "slide_type": "slide"
     }
    },
    "source": [
     "### Signatures"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Mentioned in the doc string, the callback registered can have **4 possible signatures**:\n",
     "\n",
     "- callback()\n",
     "- callback(trait_name)\n",
     "- callback(trait_name, new_value)\n",
     "- callback(trait_name, old_value, new_value)\n",
     "\n",
     "Using this method, an example of how to output an `IntSlider`'s value as it is changed can be seen below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "int_range = widgets.IntSlider()\n",
     "display(int_range)\n",
     "\n",
     "def on_value_change(name, value):\n",
     "    print(value)\n",
     "\n",
     "int_range.on_trait_change(on_value_change, 'value')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "# Linking Widgets"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Often, you may want to simply link widget attributes together. Synchronization of attributes can be done in a simpler way than by using bare traitlets events. \n",
+    "\n",
+    "The first method is to use the `link` and `directional_link` functions from the `traitlets` module. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Linking traitlets attributes from the server side"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from IPython.utils import traitlets"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "caption = widgets.Latex(value = 'The values of slider1, slider2 and slider3 are synchronized')\n",
+    "sliders1, slider2, slider3 = widgets.IntSlider(description='Slider 1'),\\\n",
+    "                             widgets.IntSlider(description='Slider 2'),\\\n",
+    "                             widgets.IntSlider(description='Slider 3')\n",
+    "l = traitlets.link((sliders1, 'value'), (slider2, 'value'), (slider3, 'value'))\n",
+    "display(caption, sliders1, slider2, slider3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "caption = widgets.Latex(value = 'Changes in source values are reflected in target1 and target2')\n",
+    "source, target1, target2 = widgets.IntSlider(description='Source'),\\\n",
+    "                           widgets.IntSlider(description='Target 1'),\\\n",
+    "                           widgets.IntSlider(description='Target 2')\n",
+    "traitlets.dlink((source, 'value'), (target1, 'value'), (target2, 'value'))\n",
+    "display(caption, source, target1, target2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Function `traitlets.link` returns a `Link` object. The link can be broken by calling the `unlink` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "# l.unlink()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Linking widgets attributes from the client side"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When synchronizing traitlets attributes, you may experience a lag because of the latency dues to the rountrip to the server side. You can also directly link widgets attributes, either in a unidirectional or a bidirectional fashion using the link widgets. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "caption = widgets.Latex(value = 'The values of range1, range2 and range3 are synchronized')\n",
+    "range1, range2, range3 = widgets.IntSlider(description='Range 1'),\\\n",
+    "                         widgets.IntSlider(description='Range 2'),\\\n",
+    "                         widgets.IntSlider(description='Range 3')\n",
+    "l = widgets.link((range1, 'value'), (range2, 'value'), (range3, 'value'))\n",
+    "display(caption, range1, range2, range3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "caption = widgets.Latex(value = 'Changes in source_range values are reflected in target_range1 and target_range2')\n",
+    "source_range, target_range1, target_range2 = widgets.IntSlider(description='Source range'),\\\n",
+    "                                             widgets.IntSlider(description='Target range 1'),\\\n",
+    "                                             widgets.IntSlider(description='Target range 2')\n",
+    "widgets.dlink((source_range, 'value'), (target_range1, 'value'), (target_range2, 'value'))\n",
+    "display(caption, source_range, target_range1, target_range2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Function `widgets.link` returns a `Link` widget. The link can be broken by calling the `unlink` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "# l.unlink()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Styling.ipynb)"
    ]
   }
  ],
  "metadata": {
   "cell_tags": [
    [
     "<None>",
     null
    ]
   ],
   "kernelspec": {
+   "display_name": "Python 2",
+   "name": "python2"
+  },
+  "language_info": {
    "codemirror_mode": {
-    "name": "python",
+    "name": "ipython",
     "version": 2
    },
-   "display_name": "Python 2",
-   "language": "python",
-   "name": "python2"
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.8"
   },
-  "signature": "sha256:05a3e92089b37f68e3134587ffef6ef73830e5f8b3c515ba24640d7c803820c3"
+  "signature": "sha256:b6eadc174d0d9c1907518d9f37760eb3dca3aec0ef1f3746e6f0537a36e99919"
  },
  "nbformat": 4,
  "nbformat_minor": 0
 }
  No newline at end of file