examples/widgets/Part 1 - Basics.ipynb

{
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[Index](index.ipynb)\n",
      "\n",
      "To use IPython widgets in the notebook, the widget namespace needs to be imported."
     ]
    },
    {
     "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": [
      "Basic Widgets"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The IPython notebook comes preloaded with basic widgets that represent common data types.  These widgets are\n",
      "\n",
      "- CheckBoxWidget\n",
      "- ToggleButtonWidget\n",
      "- FloatSliderWidget\n",
      "- BoundedFloatTextWidget\n",
      "- FloatProgressWidget\n",
      "- FloatTextWidget\n",
      "- ImageWidget\n",
      "- IntSliderWidget\n",
      "- BoundedIntTextWidget\n",
      "- IntProgressWidget\n",
      "- IntTextWidget\n",
      "- ToggleButtonsWidget\n",
      "- RadioButtonsWidget\n",
      "- DropdownWidget\n",
      "- ListBoxWidget\n",
      "- HTMLWidget\n",
      "- LatexWidget\n",
      "- TextAreaWidget\n",
      "- TextBoxWidget\n",
      "\n",
      "A few special widgets are also included, that can be used to capture events and change how other widgets are displayed.  These widgets are\n",
      "\n",
      "- ButtonWidget\n",
      "- ContainerWidget\n",
      "- PopupWidget\n",
      "- AccordionWidget\n",
      "- TabWidget\n",
      "\n",
      "To see the complete list of widgets, one can execute the following"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "[widget for widget in dir(widgets) if widget.endswith('Widget')]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 2,
       "text": [
        "['AccordionWidget',\n",
        " 'BoundedFloatTextWidget',\n",
        " 'BoundedIntTextWidget',\n",
        " 'ButtonWidget',\n",
        " 'CheckBoxWidget',\n",
        " 'ContainerWidget',\n",
        " 'DOMWidget',\n",
        " 'DropdownWidget',\n",
        " 'FloatProgressWidget',\n",
        " 'FloatSliderWidget',\n",
        " 'FloatTextWidget',\n",
        " 'HTMLWidget',\n",
        " 'ImageWidget',\n",
        " 'IntProgressWidget',\n",
        " 'IntSliderWidget',\n",
        " 'IntTextWidget',\n",
        " 'LatexWidget',\n",
        " 'ListBoxWidget',\n",
        " 'PopupWidget',\n",
        " 'RadioButtonsWidget',\n",
        " 'TabWidget',\n",
        " 'TextAreaWidget',\n",
        " 'TextBoxWidget',\n",
        " 'ToggleButtonWidget',\n",
        " 'ToggleButtonsWidget',\n",
        " 'Widget']"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The basic widgets can all be constructed without arguments.  The following creates a *FloatSliderWidget* without displaying it"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mywidget = widgets.FloatSliderWidget()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Constructing a widget does not display it on the page.  To display a widget, the widget must be passed to the IPython `display(object)` method or must be returned as the last item in the cell.  `mywidget` is displayed by"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "display(mywidget)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "or"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mywidget"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It's important to realize that widgets are not the same as output, even though they are displayed with `display`.  Widgets are drawn in a special widget area.  That area is marked with a close button which allows you to collapse the widgets.  Widgets cannot be interleaved with output.  Doing so would break the ability to make simple animations using `clear_output`.\n",
      "\n",
      "Widgets are manipulated via special instance properties (traitlets).  The names of these instance properties are listed in the widget's `keys` property (as seen below).  A few of these properties are common to most, if not all, widgets.  The common properties are `value`, `description`, `visible`, and `disabled`.  `_css` and `_view_name` are internal properties that exist in all widgets and should not be modified."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mywidget.keys"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 6,
       "text": [
        "['_view_name',\n",
        " 'description',\n",
        " 'min',\n",
        " 'orientation',\n",
        " 'max',\n",
        " '_css',\n",
        " 'value',\n",
        " 'disabled',\n",
        " 'visible',\n",
        " 'step']"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Changing a widget's property value will automatically update that widget everywhere it is displayed in the notebook.  Here the value of `mywidget` is set.  The slider shown above (after inputs 4 and 5) updates automatically to the new value.  In reverse, changing the value of the displayed widget will update the property's value."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mywidget.value = 25.0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "After changing the widget's value in the notebook by hand to 0.0 (sliding the bar to the far left)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mywidget.value"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 8,
       "text": [
        "0.0"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Widget property values can also be set with kwargs during the construction of the widget (as seen below)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mysecondwidget = widgets.RadioButtonsWidget(values=[\"Item A\", \"Item B\", \"Item C\"], value=\"Item A\")\n",
      "display(mysecondwidget)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mysecondwidget.value"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 10,
       "text": [
        "'Item A'"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In [Part 2](Part 2 - Events.ipynb) of this [series](index.ipynb), you will learn about widget events."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}