examples/widgets/Part 3 - Placement.ipynb

{
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "\n",
      "\n",
      "\n",
      "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": [
      "Parent/Child Relationships"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "To display widget A inside widget B, widget A must be a child of widget B.  With IPython widgets, the widgets are instances that live in the back-end (usally Python).  There can be multiple views displayed in the front-end that represent one widget in the backend.  Each view can be displayed at a different time, or even displayed two or more times in the same output.   Because of this, the parent of a widget can only be set before the widget has been displayed.\n",
      "\n",
      "Every widget has a `parent` property.  This property can be set via a kwarg in the widget's constructor or after construction, but before display.  Calling display on an object with children automatically displays those children too (as seen below)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "\n",
      "floatrange = widgets.FloatRangeWidget() # You can set the parent in the constructor,\n",
      "\n",
      "string = widgets.StringWidget(value='hi')\n",
      "container = widgets.ContainerWidget(children=[floatrange, string])\n",
      "\n",
      "display(container) # Displays the `container` and all of it's children."
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Children can also be added to parents after the parent has been displayed.  If the children are added after the parent has already been displayed, the children must be displayed themselves.\n",
      "\n",
      "In the example below, the IntRangeWidget is never rendered since display was called on the parent before the parent/child relationship was established."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "intrange = widgets.IntRangeWidget() # Never gets displayed.\n",
      "container = widgets.MulticontainerWidget(children=[intrange])\n",
      "\n",
      "display(container)\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Calling display on the child fixes the problem."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "container = widgets.MulticontainerWidget()\n",
      "display(container)\n",
      "\n",
      "intrange = widgets.IntRangeWidget(parent=container)\n",
      "display(intrange) # This line is needed since the `container` has already been displayed."
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Changing Child Views"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The view used to display a widget must defined by the time the widget is displayed.  If children widgets are to be displayed along with the parent in one call, their `view_name`s can't be set since all of the widgets are sharing the same display call.  Instead, their `default_view_name`s must be set (as seen below)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "\n",
      "floatrange = widgets.FloatRangeWidget()\n",
      "floatrange.default_view_name = \"FloatTextView\" # It can be set as a property.\n",
      "\n",
      "string = widgets.StringWidget(default_view_name = \"TextAreaView\") # It can also be set in the constructor.\n",
      "container = widgets.MulticontainerWidget(children=[floatrange, string])\n",
      "display(container)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "However, if the children are displayed after the parent, their `view_name` can also be set like normal.  Both methods will work.  The code below produces the same output as the code above."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "container = widgets.MulticontainerWidget()\n",
      "display(container)\n",
      "\n",
      "floatrange = widgets.FloatRangeWidget()\n",
      "floatrange.parent=container\n",
      "display(floatrange, view_name = \"FloatTextView\") # view_name can be set during display.\n",
      "\n",
      "string = widgets.StringWidget()\n",
      "string.parent = container\n",
      "string.default_view_name = \"TextAreaView\" # Setting default_view_name still works.\n",
      "display(string)\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Visibility"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Sometimes it's necessary to hide/show widget views in place, without ruining the order that they have been displayed on the page.  Using the `display` method, the views are always added to the end of their respective containers.  Instead the `visibility` property of widgets can be used to hide/show widgets that have already been displayed (as seen below)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "string = widgets.StringWidget(value=\"Hello World!\")\n",
      "display(string, view_name=\"HTMLView\") "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "string.visible=False"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "string.visible=True"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In the example below, a form is rendered which conditionally displays widgets depending on the state of other widgets.  Try toggling the student checkbox."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "form = widgets.ContainerWidget()\n",
      "first = widgets.StringWidget(description=\"First Name:\")\n",
      "last = widgets.StringWidget(description=\"Last Name:\")\n",
      "\n",
      "student = widgets.BoolWidget(description=\"Student:\", value=False)\n",
      "form.children=[first, last, student]\n",
      "display(form)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "form = widgets.ContainerWidget()\n",
      "first = widgets.StringWidget(description=\"First Name:\")\n",
      "last = widgets.StringWidget(description=\"Last Name:\")\n",
      "\n",
      "student = widgets.BoolWidget(description=\"Student:\", value=False)\n",
      "school_info = widgets.ContainerWidget(visible=False, children=[\n",
      "    widgets.StringWidget(description=\"School:\"),\n",
      "    widgets.IntRangeWidget(description=\"Grade:\", min=0, max=12, default_view_name='IntTextView')\n",
      "    ])\n",
      "\n",
      "pet = widgets.StringWidget(description=\"Pet's Name:\")\n",
      "form.children = [first, last, student, school_info, pet]\n",
      "display(form)\n",
      "\n",
      "def on_student_toggle(name, value):\n",
      "    print value\n",
      "    if value:\n",
      "        school_info.visible = True\n",
      "    else:\n",
      "        school_info.visible = False\n",
      "student.on_trait_change(on_student_toggle, 'value')\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "True\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "False\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "True\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "False\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "True\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "False\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}