Updated example notebook

examples/Interactive Widgets/Widget Events.ipynb

@@ -221,6 +221,150
      "outputs": []
     },
     {
+     "cell_type": "heading",
+     "level": 1,
+     "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": "heading",
+     "level": 2,
+     "metadata": {},
+     "source": [
+      "Linking traitlets attributes from the server side"
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "from IPython.utils import traitlets"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "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)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "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)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "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",
+     "collapsed": false,
+     "input": [
+      "# l.unlink()"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "heading",
+     "level": 2,
+     "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",
+     "collapsed": false,
+     "input": [
+      "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)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "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)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "Function `widgets.link` returns a `Link` widget. The link can be broken by calling the `close` method."
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "# l.close()"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": []
+    },
+    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
@@ -231,4 +375,4
    "metadata": {}
   }
  ]
-}
  No newline at end of file
+}