Updated basics notebook for pydata2014

examples/Interactive Widgets/Widget Basics.ipynb

@@ -1,13 +1,7 b''
 {
  "metadata": {
-  "cell_tags": [
-   [
-    "<None>",
-    null
-   ]
-  ],
   "name": "",
-  "signature": "sha256:5ac3a85c8bb2f9bb3cd63b524bbb626ab1531176b43a109d13f5d7794f805eee"
+  "signature": "sha256:d788f17db7e02e94777b4b8aa36e55b29fc1806059dbb8a1cc9de60cdbe58825"
  },
  "nbformat": 3,
  "nbformat_minor": 0,
@@ -18,179 +12,119 b''
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "To use IPython widgets in the notebook, the widget namespace needs to be imported."
+      "# Simple widget introduction\n",
+      "\n",
+      "## What are widgets?\n",
+      "<blockquote>Widgets are elements that exists in both the front-end and the back-end.</blockquote>\n",
+      "\n",
+      "You can use widgets to build interactive GUIs for your notebooks.  \n",
+      "You can also use widgets to synchronize stateful and stateless information between Python and JavaScript.\n",
+      "\n",
+      "## Using widgets  \n",
+      "To use the widget framework, you need to import the widgets from `IPython.html.widgets`."
      ]
     },
     {
      "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"
+      "from IPython.html.widgets import *"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 2
-    },
-    {
-     "cell_type": "heading",
-     "level": 1,
-     "metadata": {},
-     "source": [
-      "Basic Widgets"
-     ]
+     "prompt_number": 8
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "IPython comes with basic widgets that represent common interactive controls.  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",
-      "- SelectWidget\n",
-      "- HTMLWidget\n",
-      "- LatexWidget\n",
-      "- TextareaWidget\n",
-      "- TextWidget\n",
-      "- ButtonWidget\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",
-      "- ContainerWidget\n",
-      "- PopupWidget\n",
-      "- AccordionWidget\n",
-      "- TabWidget\n",
-      "\n",
-      "To see the complete list of widgets, one can execute the following"
+      "Widgets have their own display `repr` which allows them to be displayed using IPython's display framework.  Constructing and returning an `IntSliderWidget` automatically displays the widget (as seen below).  Widgets are displayed inside the `widget area`, which sits between the code cell and output.  You can hide all of the widgets in the `widget area` by clicking the grey *x* in the margin."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "[widget for widget in dir(widgets) if widget.endswith('Widget')]"
+      "IntSliderWidget()"
      ],
      "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",
-        " 'PopupWidget',\n",
-        " 'RadioButtonsWidget',\n",
-        " 'SelectWidget',\n",
-        " 'TabWidget',\n",
-        " 'TextWidget',\n",
-        " 'TextareaWidget',\n",
-        " 'ToggleButtonWidget',\n",
-        " 'ToggleButtonsWidget',\n",
-        " 'Widget']"
-       ]
-      }
-     ],
-     "prompt_number": 2
+     "outputs": [],
+     "prompt_number": 9
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "The basic widgets all have sensible default values.  Create a *FloatSliderWidget* without displaying it:"
+      "You can also explicitly display the widget using `display(...)`."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mywidget = widgets.FloatSliderWidget()"
+      "from IPython.display import display\n",
+      "w = IntSliderWidget()\n",
+      "display(w)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 3
+     "prompt_number": 10
     },
     {
      "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"
+      "If you display the same widget twice, the displayed instances in the front-end will remain in sync with each other."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "display(mywidget)"
+      "display(w)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 4
+     "prompt_number": 11
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "or"
+      "You can close a widget by calling its `close()` method."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mywidget"
+      "w.close()"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 5
+     "prompt_number": 12
     },
     {
      "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",
+      "## Why does displaying the same widget twice work?\n",
+      "Widgets are represented in the back-end by a single object.  Each time a widget is displayed, a new representation of that same object is created in the front-end.\n",
       "\n",
-      "Widgets are manipulated via special instance attributes (traitlets).  The names of these traitlets are listed in the widget's `keys` attribute (as seen below).  A few of these attributes are common to most widgets.  The basic attributes are `value`, `description`, `visible`, and `disabled`.  `_css` and `_view_name` are private attributes that exist in all widgets and should not be modified."
+      "## Widget properties\n",
+      "All of the IPython widgets share a similar naming scheme.  To read the value of a widget, you can query its `value` property."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mywidget.keys"
+      "w.value"
      ],
      "language": "python",
      "metadata": {},
@@ -198,53 +132,44 b''
       {
        "metadata": {},
        "output_type": "pyout",
-       "prompt_number": 6,
+       "prompt_number": 31,
        "text": [
-        "['_view_name',\n",
-        " 'orientation',\n",
-        " 'min',\n",
-        " 'max',\n",
-        " '_css',\n",
-        " 'value',\n",
-        " 'disabled',\n",
-        " 'visible',\n",
-        " 'step',\n",
-        " 'description']"
+        "41"
        ]
       }
      ],
-     "prompt_number": 6
+     "prompt_number": 31
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "Changing a widget's attribute will automatically update that widget everywhere it is displayed in the notebook.  Here, the `value` attribute of `mywidget` is set.  The slider shown above updates automatically with the new value.  Syncing also works in the other direction - changing the value of the displayed widget will update the property's value."
+      "Similarly, to set a widget's value, you can set its `value` property."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mywidget.value = 25.0"
+      "w.value = 100"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 7
+     "prompt_number": 32
     },
     {
      "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)."
+      "In addition to `value`, most widgets share `keys`, `description`, `disabled`, and `visible`.  To see the entire list of synchronized, stateful properties, of any specific widget, you can query the `keys` property."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mywidget.value"
+      "w.keys"
      ],
      "language": "python",
      "metadata": {},
@@ -252,85 +177,110 b''
       {
        "metadata": {},
        "output_type": "pyout",
-       "prompt_number": 8,
+       "prompt_number": 33,
        "text": [
-        "25.0"
+        "['_view_name',\n",
+        " 'orientation',\n",
+        " 'msg_throttle',\n",
+        " 'min',\n",
+        " 'max',\n",
+        " '_css',\n",
+        " 'value',\n",
+        " 'readout',\n",
+        " 'disabled',\n",
+        " 'visible',\n",
+        " 'step',\n",
+        " 'description']"
        ]
       }
      ],
-     "prompt_number": 8
+     "prompt_number": 33
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "Widget values can also be set with kwargs during the construction of the widget (as seen below)."
+      "### Tip: Shorthand for setting the initial values of widget properties\n",
+      "While creating a widget, you can set some or all of the initial values of that widget by defining them as keyword arguments in the widget's constructor (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)"
+      "TextWidget(value='Hello World!', disabled=True)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 9
+     "prompt_number": 34
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "## Excercise\n",
+      "Create and display a `TextWidget`.  Change that widget's `value` and some of it's other properties.  Discover the other properties by querying the `keys` property of the instance."
+     ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
-     "input": [
-      "mysecondwidget.value"
-     ],
+     "input": [],
      "language": "python",
      "metadata": {},
-     "outputs": [
-      {
-       "metadata": {},
-       "output_type": "pyout",
-       "prompt_number": 10,
-       "text": [
-        "'Item A'"
-       ]
-      }
-     ],
-     "prompt_number": 10
+     "outputs": []
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
-      "Some widgets have special attributes. For example, text boxes and text areas can specify the `placeholder` attribute, which will set \"placeholder\" text to be displayed before the user has typed anything:"
+      "## Linking two similar widgets\n",
+      "If you need to display the same value two different ways, you'll have to use two different widgets.  Instead of attempting to manually synchronize the values of the two widgets, you can use the `traitlet` `link` function to link two properties together.  Below, the values of three widgets are linked together."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mytextwidget = widgets.TextWidget()\n",
-      "mytextwidget.placeholder = \"type something here\"\n",
-      "display(mytextwidget)"
+      "from IPython.utils.traitlets import link\n",
+      "a = FloatTextWidget()\n",
+      "b = FloatSliderWidget()\n",
+      "c = FloatProgressWidget()\n",
+      "display(a,b,c)\n",
+      "\n",
+      "\n",
+      "mylink = link((a, 'value'), (b, 'value'), (c, 'value'))"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 4
+     "prompt_number": 51
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "Unlinking the widgets is simple.  All you have to do is call `.unlink` on the link object."
+     ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
-      "mytextareawidget = widgets.TextareaWidget()\n",
-      "mytextareawidget.placeholder = \"your text here\"\n",
-      "display(mytextareawidget)"
+      "mylink.unlink()"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 5
+     "prompt_number": 52
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "[Next](Widget List.ipynb)"
+     ]
     }
    ],
    "metadata": {}