Updated events example to reflect changes to button.

examples/widgets/Part 2 - Events.ipynb

@@ -1,242 +1,269 b''
 {
  "metadata": {
   "cell_tags": [
    [
     "<None>",
     null
    ]
   ],
   "name": ""
  },
  "nbformat": 3,
  "nbformat_minor": 0,
  "worksheets": [
   {
    "cells": [
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "from IPython.html import widgets # Widget definitions\n",
       "from IPython.display import display # Used to display widgets in the notebook"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 1
     },
     {
      "cell_type": "heading",
      "level": 1,
      "metadata": {},
      "source": [
       "Traitlet Events"
      ]
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "The widget properties are IPython traitlets.  Traitlets are eventful.  To handle property value changes, the `on_trait_change` method of the widget can be used to register an event handling callback.  The doc string for `on_trait_change` can be seen below.  Both the `name` and `remove` properties are optional."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "print(widgets.Widget.on_trait_change.__doc__)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "output_type": "stream",
        "stream": "stdout",
        "text": [
         "Setup a handler to be called when a trait changes.\n",
         "\n",
         "        This is used to setup dynamic notifications of trait changes.\n",
         "\n",
         "        Static handlers can be created by creating methods on a HasTraits\n",
         "        subclass with the naming convention '_[traitname]_changed'.  Thus,\n",
         "        to create static handler for the trait 'a', create the method\n",
         "        _a_changed(self, name, old, new) (fewer arguments can be used, see\n",
         "        below).\n",
         "\n",
         "        Parameters\n",
         "        ----------\n",
         "        handler : callable\n",
         "            A callable that is called when a trait changes.  Its\n",
         "            signature can be handler(), handler(name), handler(name, new)\n",
         "            or handler(name, old, new).\n",
         "        name : list, str, None\n",
         "            If None, the handler will apply to all traits.  If a list\n",
         "            of str, handler will apply to all names in the list.  If a\n",
         "            str, the handler will apply just to that name.\n",
         "        remove : bool\n",
         "            If False (the default), then install the handler.  If True\n",
         "            then unintall it.\n",
         "        \n"
        ]
       }
      ],
      "prompt_number": 2
     },
     {
      "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",
       "An example of how to output an IntRangeWiget's value as it is changed can be seen below."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "intrange = widgets.IntRangeWidget()\n",
       "display(intrange)\n",
       "\n",
       "def on_value_change(name, value):\n",
       "    print value\n",
       "\n",
       "intrange.on_trait_change(on_value_change, 'value')"
      ],
      "language": "python",
      "metadata": {},
-     "outputs": [],
+     "outputs": [
+      {
+       "output_type": "stream",
+       "stream": "stdout",
+       "text": [
+        "25\n"
+       ]
+      },
+      {
+       "output_type": "stream",
+       "stream": "stdout",
+       "text": [
+        "73\n"
+       ]
+      },
+      {
+       "output_type": "stream",
+       "stream": "stdout",
+       "text": [
+        "99\n"
+       ]
+      }
+     ],
      "prompt_number": 3
     },
     {
      "cell_type": "heading",
      "level": 1,
      "metadata": {},
      "source": [
       "Specialized Events"
      ]
     },
     {
      "cell_type": "heading",
      "level": 2,
      "metadata": {},
      "source": [
       "Button On Click Event"
      ]
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "The `ButtonWidget` is a special widget, like the `ContainerWidget` and `MulticontainerWidget`, that isn't used to represent a data type.  Instead the button widget is used to handle mouse clicks.  The `on_click` method of the `ButtonWidget` can be used to register a click even handler.  The doc string of the `on_click` can be seen below."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "print(widgets.ButtonWidget.on_click.__doc__)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "output_type": "stream",
        "stream": "stdout",
        "text": [
         "Register a callback to execute when the button is clicked.  The\n",
         "        callback can either accept no parameters or one sender parameter:\n",
         "        - callback()\n",
         "        - callback(sender)\n",
         "        If the callback has a sender parameter, the ButtonWidget instance that\n",
         "        called the callback will be passed into the method as the sender.\n",
         "\n",
         "        Parameters\n",
         "        ----------\n",
         "        remove : bool (optional)\n",
         "            Set to true to remove the callback from the list of callbacks.\n"
        ]
       }
      ],
      "prompt_number": 4
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "Button clicks are tracked by the `clicks` property of the button widget.  By using the `on_click` method and the `clicks` property, a button that outputs how many times it has been clicked is shown below."
+      "Button clicks 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",
      "collapsed": false,
      "input": [
       "button = widgets.ButtonWidget(description=\"Click Me!\")\n",
       "display(button)\n",
       "\n",
       "def on_button_clicked(sender):\n",
-      "    print(\"Button clicked %d times.\" % sender.clicks)\n",
+      "    print(\"Button clicked.\")\n",
       "\n",
       "button.on_click(on_button_clicked)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "output_type": "stream",
        "stream": "stdout",
        "text": [
-        "Button clicked 1 times.\n"
+        "Button clicked.\n"
        ]
       },
       {
        "output_type": "stream",
        "stream": "stdout",
        "text": [
-        "Button clicked 2 times.\n"
+        "Button clicked.\n"
        ]
       },
       {
        "output_type": "stream",
        "stream": "stdout",
        "text": [
-        "Button clicked 3 times.\n"
+        "Button clicked.\n"
        ]
       }
      ],
      "prompt_number": 5
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "Event handlers can also be used to create widgets.  In the example below, clicking a button spawns another button with a description equal to how many times the parent button had been clicked at the time."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "def show_button(sender=None):\n",
       "    button = widgets.ButtonWidget()\n",
-      "    button.description = \"%d\" % (sender.clicks if sender is not None else 0)\n",
+      "    button.clicks = 0\n",
+      "    if sender is None:\n",
+      "        button.description = \"0\"\n",
+      "    else:\n",
+      "        sender.clicks += 1\n",
+      "        button.description = \"%d\" % sender.clicks\n",
       "    display(button)\n",
       "    button.on_click(show_button)\n",
       "show_button()\n",
       "    "
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 6
     }
    ],
    "metadata": {}
   }
  ]
 }
  No newline at end of file