examples/Interactive Widgets/Widget Events.ipynb

{
 "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": [
    "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Styling.ipynb)"
   ]
  }
 ],
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "kernelspec": {
   "codemirror_mode": {
    "name": "python",
    "version": 2
   },
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "signature": "sha256:05a3e92089b37f68e3134587ffef6ef73830e5f8b3c515ba24640d7c803820c3"
 },
 "nbformat": 4,
 "nbformat_minor": 0
}