examples/Interactive Widgets/Widget Events.ipynb

{
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "celltoolbar": "Slideshow",
  "name": "",
  "signature": "sha256:43e4910dd01111e1206f4f7940a201d6d5e69485df79de96e0ad927eb0046226"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Styling.ipynb)"
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Widget Events"
     ]
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Special events"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from __future__ import print_function"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The `ButtonWidget` is not 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 function to be called when the button is clicked.  The doc string of the `on_click` can be seen below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from IPython.html import widgets\n",
      "print(widgets.ButtonWidget.on_click.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 3,
     "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",
     "collapsed": false,
     "input": [
      "from IPython.display import display\n",
      "button = widgets.ButtonWidget(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)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "on_sumbit"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The **`TextWidget`** also has a special **`on_submit` event**.  The `on_submit` event **fires when the user hits return**."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "text = widgets.TextWidget()\n",
      "display(text)\n",
      "\n",
      "def handle_submit(sender):\n",
      "    print(text.value)\n",
      "\n",
      "text.on_submit(handle_submit)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "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",
     "collapsed": false,
     "input": [
      "print(widgets.Widget.on_trait_change.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 3,
     "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 IntSliderWiget's value as it is changed can be seen below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "int_range = widgets.IntSliderWidget()\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')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Styling.ipynb)"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}