##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Remove init_widget_js, use require.js for everything...
Remove init_widget_js, use require.js for everything Updated examples Fixed bug with message throttling
Jonathan Frederic - - Load All Authors

File last commit:

r14342:90efa5b8
r14342:90efa5b8
Show More
Part 1 - Basics.ipynb
322 lines | 9.7 KiB | text/plain | TextLexer
/ examples / widgets / Part 1 - Basics.ipynb
History | Annotation | Raw |Copy content |Copy permalink

To use IPython widgets in the notebook, the widget namespace and display function need to be imported.

In [1]:
from IPython.html import widgets # Widget definitions
from IPython.display import display # Used to display widgets in the notebook

Basic Widgets

The IPython notebook comes preloaded with basic widgets that represent common data types. These widgets are

  • BoolWidget : boolean
  • FloatRangeWidget : bounded float
  • FloatWidget : unbounded float
  • IntRangeWidget : bounded integer
  • IntWidget : unbounded integer
  • SelectionWidget : enumeration
  • StringWidget : string

A few special widgets are also included, that can be used to capture events and change how other widgets are displayed. These widgets are

  • ButtonWidget
  • ContainerWidget
  • MulticontainerWidget

To see the complete list of widgets, one can execute the following

In [2]:
[widget for widget in dir(widgets) if widget.endswith('Widget')]
Out[2]:
['BoolWidget',
 'ButtonWidget',
 'ContainerWidget',
 'FloatRangeWidget',
 'FloatWidget',
 'IntRangeWidget',
 'IntWidget',
 'MulticontainerWidget',
 'SelectionWidget',
 'StringWidget',
 'Widget']

The basic widgets can all be constructed without arguments. The following creates a FloatRangeWidget without displaying it

In [3]:
mywidget = widgets.FloatRangeWidget()

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. mywidget is displayed by

In [4]:
display(mywidget)

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.

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, _add_class, and _remove_class are internal properties that exist in all widgets and should not be modified.

In [5]:
mywidget.keys
Out[5]:
['visible',
 '_css',
 '_add_class',
 '_remove_class',
 'value',
 'step',
 'max',
 'min',
 'disabled',
 'orientation',
 'description']

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 input 4) updates automatically to the new value. In reverse, changing the value of the displayed widget will update the property's value.

In [6]:
mywidget.value = 25.0

After changing the widget's value in the notebook by hand to 0.0 (sliding the bar to the far left).

In [7]:
mywidget.value
Out[7]:
0.0

Widget property values can also be set with kwargs during the construction of the widget (as seen below).

In [8]:
mysecondwidget = widgets.SelectionWidget(values=["Item A", "Item B", "Item C"], value="Nothing Selected")
display(mysecondwidget)

Views

The data types that most of the widgets represent can be displayed more than one way. A view is a visual representation of a widget in the notebook. In the example in the section above, the default view for the FloatRangeWidget is used. The default view is set in the widgets default_view_name instance property (as seen below).

In [9]:
mywidget.default_view_name
Out[9]:
u'FloatSliderView'

When a widget is displayed using display(...), the default_view_name is used to determine what view type should be used to display the widget. View names are case sensitive. Sometimes the default view isn't the best view to represent a piece of data. To change what view is used, either the default_view_name can be changed or the view_name kwarg of display can be set. This also can be used to display one widget multiple ways in one output (as seen below).

In [10]:
display(mywidget)
display(mywidget, view_name="FloatTextView")

Some views work with multiple different widget types and some views only work with one. The complete list of views and supported widgets is below. The default views are italicized.

Widget Name View Names
BoolWidget CheckboxView
ToggleButtonView
ButtonWidget ButtonView
ContainerWidget ContainerView
FloatRangeWidget FloatSliderView
FloatTextView
ProgressView
FloatWidget FloatTextView
IntRangeWidget IntSliderView
IntTextView
ProgressView
IntWidget IntTextView
MulticontainerWidget AccordionView
TabView
SelectionWidget ToggleButtonsView
RadioButtonsView
DropdownView
StringWidget LabelView
TextAreaView
TextBoxView