registering core widgets

IPython/html/widgets/__init__.py

@@ -1,23 +1,23
-from .widget import Widget, DOMWidget, CallbackDispatcher
+from .widget import Widget, DOMWidget, CallbackDispatcher, register
 
 from .widget_bool import Checkbox, ToggleButton
 from .widget_button import Button
 from .widget_box import Box, Popup, FlexBox, HBox, VBox
 from .widget_float import FloatText, BoundedFloatText, FloatSlider, FloatProgress, FloatRangeSlider
 from .widget_image import Image
 from .widget_int import IntText, BoundedIntText, IntSlider, IntProgress, IntRangeSlider
 from .widget_selection import RadioButtons, ToggleButtons, Dropdown, Select
 from .widget_selectioncontainer import Tab, Accordion
 from .widget_string import HTML, Latex, Text, Textarea
 from .interaction import interact, interactive, fixed, interact_manual
 
 # Deprecated classes
 from .widget_bool import CheckboxWidget, ToggleButtonWidget
 from .widget_button import ButtonWidget
 from .widget_box import ContainerWidget, PopupWidget
 from .widget_float import FloatTextWidget, BoundedFloatTextWidget, FloatSliderWidget, FloatProgressWidget
 from .widget_image import ImageWidget
 from .widget_int import IntTextWidget, BoundedIntTextWidget, IntSliderWidget, IntProgressWidget
 from .widget_selection import RadioButtonsWidget, ToggleButtonsWidget, DropdownWidget, SelectWidget
 from .widget_selectioncontainer import TabWidget, AccordionWidget
 from .widget_string import HTMLWidget, LatexWidget, TextWidget, TextareaWidget

IPython/html/widgets/widget.py

@@ -1,476 +1,476
 """Base Widget class.  Allows user to create widgets in the back-end that render
 in the IPython notebook front-end.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from contextlib import contextmanager
 import collections
 
 from IPython.core.getipython import get_ipython
 from IPython.kernel.comm import Comm
 from IPython.config import LoggingConfigurable
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import Unicode, Dict, Instance, Bool, List, \
     CaselessStrEnum, Tuple, CUnicode, Int, Set
 from IPython.utils.py3compat import string_types
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class CallbackDispatcher(LoggingConfigurable):
     """A structure for registering and running callbacks"""
     callbacks = List()
     
     def __call__(self, *args, **kwargs):
         """Call all of the registered callbacks."""
         value = None
         for callback in self.callbacks:
             try:
                 local_value = callback(*args, **kwargs)
             except Exception as e:
                 ip = get_ipython()
                 if ip is None:
                     self.log.warn("Exception in callback %s: %s", callback, e, exc_info=True)
                 else:
                     ip.showtraceback()
             else:
                 value = local_value if local_value is not None else value
         return value
 
     def register_callback(self, callback, remove=False):
         """(Un)Register a callback
 
         Parameters
         ----------
         callback: method handle
             Method to be registered or unregistered.
         remove=False: bool
             Whether to unregister the callback."""
         
         # (Un)Register the callback.
         if remove and callback in self.callbacks:
             self.callbacks.remove(callback)
         elif not remove and callback not in self.callbacks:
             self.callbacks.append(callback)
 
 def _show_traceback(method):
     """decorator for showing tracebacks in IPython"""
     def m(self, *args, **kwargs):
         try:
             return(method(self, *args, **kwargs))
         except Exception as e:
             ip = get_ipython()
             if ip is None:
                 self.log.warn("Exception in widget method %s: %s", method, e, exc_info=True)
             else:
                 ip.showtraceback()
     return m
 
 
 def register(key=None):
     def wrap(widget):
-        l = key if key is not None else widget._model_name.default_value
+        l = key if key is not None else widget._view_name.default_value
         Widget.widget_types[l] = widget
         return widget
     return wrap
 
 
 class Widget(LoggingConfigurable):
     #-------------------------------------------------------------------------
     # Class attributes
     #-------------------------------------------------------------------------
     _widget_construction_callback = None
     widgets = {}
     widget_types = {}
 
     @staticmethod
     def on_widget_constructed(callback):
         """Registers a callback to be called when a widget is constructed.
 
         The callback must have the following signature:
         callback(widget)"""
         Widget._widget_construction_callback = callback
 
     @staticmethod
     def _call_widget_constructed(widget):
         """Static method, called when a widget is constructed."""
         if Widget._widget_construction_callback is not None and callable(Widget._widget_construction_callback):
             Widget._widget_construction_callback(widget)
 
     @staticmethod
     def handle_comm_opened(comm, msg):
         """Static method, called when a widget is constructed."""
         widget_class = import_item(msg['content']['data']['widget_class'])
         widget = widget_class(comm=comm)
 
 
     #-------------------------------------------------------------------------
     # Traits
     #-------------------------------------------------------------------------
     _model_module = Unicode(None, allow_none=True, help="""A requirejs module name
         in which to find _model_name. If empty, look in the global registry.""")
     _model_name = Unicode('WidgetModel', help="""Name of the backbone model 
         registered in the front-end to create and sync this widget with.""")
     _view_module = Unicode(help="""A requirejs module in which to find _view_name.
         If empty, look in the global registry.""", sync=True)
     _view_name = Unicode(None, allow_none=True, help="""Default view registered in the front-end
         to use to represent the widget.""", sync=True)
     comm = Instance('IPython.kernel.comm.Comm')
     
     msg_throttle = Int(3, sync=True, help="""Maximum number of msgs the 
         front-end can send before receiving an idle msg from the back-end.""")
     
     version = Int(0, sync=True, help="""Widget's version""")
     keys = List()
     def _keys_default(self):
         return [name for name in self.traits(sync=True)]
     
     _property_lock = Tuple((None, None))
     _send_state_lock = Int(0)
     _states_to_send = Set(allow_none=False)
     _display_callbacks = Instance(CallbackDispatcher, ())
     _msg_callbacks = Instance(CallbackDispatcher, ())
     
     #-------------------------------------------------------------------------
     # (Con/de)structor
     #-------------------------------------------------------------------------
     def __init__(self, **kwargs):
         """Public constructor"""
         self._model_id = kwargs.pop('model_id', None)
         super(Widget, self).__init__(**kwargs)
 
         Widget._call_widget_constructed(self)
         self.open()
 
     def __del__(self):
         """Object disposal"""
         self.close()
 
     #-------------------------------------------------------------------------
     # Properties
     #-------------------------------------------------------------------------
 
     def open(self):
         """Open a comm to the frontend if one isn't already open."""
         if self.comm is None:
             args = dict(target_name='ipython.widget',
                         data={'model_name': self._model_name,
                               'model_module': self._model_module})
             if self._model_id is not None:
                 args['comm_id'] = self._model_id
             self.comm = Comm(**args)
 
     def _comm_changed(self, name, new):
         """Called when the comm is changed."""
         self.comm = new
         self._model_id = self.model_id
         
         self.comm.on_msg(self._handle_msg)
         Widget.widgets[self.model_id] = self
         
         # first update
         self.send_state()
 
     @property
     def model_id(self):
         """Gets the model id of this widget.
 
         If a Comm doesn't exist yet, a Comm will be created automagically."""
         return self.comm.comm_id
 
     #-------------------------------------------------------------------------
     # Methods
     #-------------------------------------------------------------------------
 
     def close(self):
         """Close method.
 
         Closes the underlying comm.
         When the comm is closed, all of the widget views are automatically
         removed from the front-end."""
         if self.comm is not None:
             Widget.widgets.pop(self.model_id, None)
             self.comm.close()
             self.comm = None
     
     def send_state(self, key=None):
         """Sends the widget state, or a piece of it, to the front-end.
 
         Parameters
         ----------
         key : unicode, or iterable (optional)
             A single property's name or iterable of property names to sync with the front-end.
         """
         self._send({
             "method" : "update",
             "state"  : self.get_state(key=key)
         })
 
     def get_state(self, key=None):
         """Gets the widget state, or a piece of it.
 
         Parameters
         ----------
         key : unicode or iterable (optional)
             A single property's name or iterable of property names to get.
         """
         if key is None:
             keys = self.keys
         elif isinstance(key, string_types):
             keys = [key]
         elif isinstance(key, collections.Iterable):
             keys = key
         else:
             raise ValueError("key must be a string, an iterable of keys, or None")
         state = {}
         for k in keys:
             f = self.trait_metadata(k, 'to_json', self._trait_to_json)
             value = getattr(self, k)
             state[k] = f(value)
         return state
 
     def set_state(self, sync_data):
         """Called when a state is received from the front-end."""
         for name in self.keys:
             if name in sync_data:
                 json_value = sync_data[name]
                 from_json = self.trait_metadata(name, 'from_json', self._trait_from_json)
                 with self._lock_property(name, json_value):
                     setattr(self, name, from_json(json_value))
     
     def send(self, content):
         """Sends a custom msg to the widget model in the front-end.
 
         Parameters
         ----------
         content : dict
             Content of the message to send.
         """
         self._send({"method": "custom", "content": content})
 
     def on_msg(self, callback, remove=False):
         """(Un)Register a custom msg receive callback.
 
         Parameters
         ----------
         callback: callable
             callback will be passed two arguments when a message arrives::
             
                 callback(widget, content)
             
         remove: bool
             True if the callback should be unregistered."""
         self._msg_callbacks.register_callback(callback, remove=remove)
 
     def on_displayed(self, callback, remove=False):
         """(Un)Register a widget displayed callback.
 
         Parameters
         ----------
         callback: method handler
             Must have a signature of::
             
                 callback(widget, **kwargs)
             
             kwargs from display are passed through without modification.
         remove: bool
             True if the callback should be unregistered."""
         self._display_callbacks.register_callback(callback, remove=remove)
 
     #-------------------------------------------------------------------------
     # Support methods
     #-------------------------------------------------------------------------
     @contextmanager
     def _lock_property(self, key, value):
         """Lock a property-value pair.
 
         The value should be the JSON state of the property.
 
         NOTE: This, in addition to the single lock for all state changes, is 
         flawed.  In the future we may want to look into buffering state changes 
         back to the front-end."""
         self._property_lock = (key, value)
         try:
             yield
         finally:
             self._property_lock = (None, None)
 
     @contextmanager
     def hold_sync(self):
         """Hold syncing any state until the context manager is released"""
         # We increment a value so that this can be nested.  Syncing will happen when
         # all levels have been released.
         self._send_state_lock += 1
         try:
             yield
         finally:
             self._send_state_lock -=1
             if self._send_state_lock == 0:
                 self.send_state(self._states_to_send)
                 self._states_to_send.clear()
 
     def _should_send_property(self, key, value):
         """Check the property lock (property_lock)"""
         to_json = self.trait_metadata(key, 'to_json', self._trait_to_json)
         if (key == self._property_lock[0]
             and to_json(value) == self._property_lock[1]):
             return False
         elif self._send_state_lock > 0:
             self._states_to_send.add(key)
             return False
         else:
             return True
     
     # Event handlers
     @_show_traceback
     def _handle_msg(self, msg):
         """Called when a msg is received from the front-end"""
         data = msg['content']['data']
         method = data['method']
         if not method in ['backbone', 'custom']:
             self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
 
         # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one.
         if method == 'backbone' and 'sync_data' in data:
             sync_data = data['sync_data']
             self.set_state(sync_data) # handles all methods
 
         # Handle a custom msg from the front-end
         elif method == 'custom':
             if 'content' in data:
                 self._handle_custom_msg(data['content'])
 
     def _handle_custom_msg(self, content):
         """Called when a custom msg is received."""
         self._msg_callbacks(self, content)
 
     def _notify_trait(self, name, old_value, new_value):
         """Called when a property has been changed."""
         # Trigger default traitlet callback machinery.  This allows any user
         # registered validation to be processed prior to allowing the widget
         # machinery to handle the state.
         LoggingConfigurable._notify_trait(self, name, old_value, new_value)
 
         # Send the state after the user registered callbacks for trait changes
         # have all fired (allows for user to validate values).
         if self.comm is not None and name in self.keys:
         # Make sure this isn't information that the front-end just sent us.
             if self._should_send_property(name, new_value):
                 # Send new state to front-end
                 self.send_state(key=name)
 
     def _handle_displayed(self, **kwargs):
         """Called when a view has been displayed for this widget instance"""
         self._display_callbacks(self, **kwargs)
 
     def _trait_to_json(self, x):
         """Convert a trait value to json
 
         Traverse lists/tuples and dicts and serialize their values as well.
         Replace any widgets with their model_id
         """
         if isinstance(x, dict):
             return {k: self._trait_to_json(v) for k, v in x.items()}
         elif isinstance(x, (list, tuple)):
             return [self._trait_to_json(v) for v in x]
         elif isinstance(x, Widget):
             return "IPY_MODEL_" + x.model_id
         else:
             return x # Value must be JSON-able
 
     def _trait_from_json(self, x):
         """Convert json values to objects
 
         Replace any strings representing valid model id values to Widget references.
         """
         if isinstance(x, dict):
             return {k: self._trait_from_json(v) for k, v in x.items()}
         elif isinstance(x, (list, tuple)):
             return [self._trait_from_json(v) for v in x]
         elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
             # we want to support having child widgets at any level in a hierarchy
             # trusting that a widget UUID will not appear out in the wild
             return Widget.widgets[x[10:]]
         else:
             return x
 
     def _ipython_display_(self, **kwargs):
         """Called when `IPython.display.display` is called on the widget."""
         # Show view.
         if self._view_name is not None:
             self._send({"method": "display"})
             self._handle_displayed(**kwargs)
 
     def _send(self, msg):
         """Sends a message to the model in the front-end."""
         self.comm.send(msg)
 
 
 class DOMWidget(Widget):
     visible = Bool(True, help="Whether the widget is visible.", sync=True)
     _css = Tuple(sync=True, help="CSS property list: (selector, key, value)")
     _dom_classes = Tuple(sync=True, help="DOM classes applied to widget.$el.")
     
     width = CUnicode(sync=True)
     height = CUnicode(sync=True)
     padding = CUnicode(sync=True)
     margin = CUnicode(sync=True)
 
     color = Unicode(sync=True)
     background_color = Unicode(sync=True)
     border_color = Unicode(sync=True)
 
     border_width = CUnicode(sync=True)
     border_radius = CUnicode(sync=True)
     border_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_border-style.asp
         'none', 
         'hidden', 
         'dotted', 
         'dashed', 
         'solid', 
         'double', 
         'groove', 
         'ridge', 
         'inset', 
         'outset', 
         'initial', 
         'inherit', ''],
         default_value='', sync=True)
 
     font_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_font-style.asp
         'normal', 
         'italic', 
         'oblique', 
         'initial', 
         'inherit', ''], 
         default_value='', sync=True)
     font_weight = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_weight.asp
         'normal', 
         'bold', 
         'bolder', 
         'lighter',
         'initial', 
         'inherit', ''] + [str(100 * (i+1)) for i in range(9)], 
         default_value='', sync=True)
     font_size = CUnicode(sync=True)
     font_family = Unicode(sync=True)
 
     def __init__(self, *pargs, **kwargs):
         super(DOMWidget, self).__init__(*pargs, **kwargs)
 
         def _validate_border(name, old, new):
             if new is not None and new != '':
                 if name != 'border_width' and not self.border_width:
                     self.border_width = 1
                 if name != 'border_style' and self.border_style == '':
                     self.border_style = 'solid'
         self.on_trait_change(_validate_border, ['border_width', 'border_style', 'border_color'])

IPython/html/widgets/widget_bool.py

@@ -1,48 +1,51
 """Bool class.  
 
 Represents a boolean using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, Bool, CaselessStrEnum
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
+@register()
 class _Bool(DOMWidget):
     """A base class for creating widgets that represent booleans."""
     value = Bool(False, help="Bool value", sync=True)
     description = Unicode('', help="Description of the boolean (label).", sync=True)
     disabled = Bool(False, help="Enable or disable user changes.", sync=True)
 
 
+@register()
 class Checkbox(_Bool):
     """Displays a boolean `value`."""
     _view_name = Unicode('CheckboxView', sync=True)
 
 
+@register()
 class ToggleButton(_Bool):
     """Displays a boolean `value`."""
     
     _view_name = Unicode('ToggleButtonView', sync=True)
 
     button_style = CaselessStrEnum(
         values=['primary', 'success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the button.""")
 
 
 # Remove in IPython 4.0
 CheckboxWidget = DeprecatedClass(Checkbox, 'CheckboxWidget')
 ToggleButtonWidget = DeprecatedClass(ToggleButton, 'ToggleButtonWidget')

IPython/html/widgets/widget_box.py

@@ -1,88 +1,91
 """Box class.  
 
 Represents a container that can be used to group other widgets.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, Tuple, TraitError, Int, CaselessStrEnum
 from IPython.utils.warn import DeprecatedClass
 
+@register()
 class Box(DOMWidget):
     """Displays multiple widgets in a group."""
     _view_name = Unicode('BoxView', sync=True)
 
     # Child widgets in the container.
     # Using a tuple here to force reassignment to update the list.
     # When a proper notifying-list trait exists, that is what should be used here.
     children = Tuple(sync=True, allow_none=False)
     
     _overflow_values = ['visible', 'hidden', 'scroll', 'auto', 'initial', 'inherit', '']
     overflow_x = CaselessStrEnum(
         values=_overflow_values, 
         default_value='', allow_none=False, sync=True, help="""Specifies what
         happens to content that is too large for the rendered region.""")
     overflow_y = CaselessStrEnum(
         values=_overflow_values, 
         default_value='', allow_none=False, sync=True, help="""Specifies what
         happens to content that is too large for the rendered region.""")
 
     box_style = CaselessStrEnum(
         values=['success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the box.""")
 
     def __init__(self, children = (), **kwargs):
         kwargs['children'] = children
         super(Box, self).__init__(**kwargs)
         self.on_displayed(Box._fire_children_displayed)
 
     def _fire_children_displayed(self):
         for child in self.children:
             child._handle_displayed()
 
 
+@register()
 class Popup(Box):
     """Displays multiple widgets in an in page popup div."""
     _view_name = Unicode('PopupView', sync=True)
     
     description = Unicode(sync=True)
     button_text = Unicode(sync=True)
 
 
+@register()
 class FlexBox(Box):
     """Displays multiple widgets using the flexible box model."""
     _view_name = Unicode('FlexBoxView', sync=True)
     orientation = CaselessStrEnum(values=['vertical', 'horizontal'], default_value='vertical', sync=True)
     flex = Int(0, sync=True, help="""Specify the flexible-ness of the model.""")
     def _flex_changed(self, name, old, new):
         new = min(max(0, new), 2)
         if self.flex != new:
             self.flex = new
 
     _locations = ['start', 'center', 'end', 'baseline', 'stretch']
     pack = CaselessStrEnum(
         values=_locations, 
         default_value='start', allow_none=False, sync=True)
     align = CaselessStrEnum(
         values=_locations, 
         default_value='start', allow_none=False, sync=True)
 
 
 def VBox(*pargs, **kwargs):
     """Displays multiple widgets vertically using the flexible box model."""
     kwargs['orientation'] = 'vertical'
     return FlexBox(*pargs, **kwargs)
 
 def HBox(*pargs, **kwargs):
     """Displays multiple widgets horizontally using the flexible box model."""
     kwargs['orientation'] = 'horizontal'
     return FlexBox(*pargs, **kwargs)
 
 
 # Remove in IPython 4.0
 ContainerWidget = DeprecatedClass(Box, 'ContainerWidget')
 PopupWidget = DeprecatedClass(Popup, 'PopupWidget')
 

IPython/html/widgets/widget_button.py

@@ -1,71 +1,72
 """Button class.  
 
 Represents a button in the frontend using a widget.  Allows user to listen for
 click events on the button and trigger backend code when the clicks are fired.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget import DOMWidget, CallbackDispatcher
+from .widget import DOMWidget, CallbackDispatcher, register
 from IPython.utils.traitlets import Unicode, Bool, CaselessStrEnum
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
+@register()
 class Button(DOMWidget):
     """Button widget.
 
     This widget has an `on_click` method that allows you to listen for the 
     user clicking on the button.  The click event itself is stateless."""
     _view_name = Unicode('ButtonView', sync=True)
 
     # Keys
     description = Unicode('', help="Button label.", sync=True)
     tooltip = Unicode(help="Tooltip caption of the button.", sync=True)
     disabled = Bool(False, help="Enable or disable user changes.", sync=True)
 
     button_style = CaselessStrEnum(
         values=['primary', 'success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the button.""")
     
     def __init__(self, **kwargs):
         """Constructor"""
         super(Button, self).__init__(**kwargs)
         self._click_handlers = CallbackDispatcher()
         self.on_msg(self._handle_button_msg)
 
     def on_click(self, callback, remove=False):
         """Register a callback to execute when the button is clicked.
 
         The callback will be called with one argument,
         the clicked button widget instance.
 
         Parameters
         ----------
         remove : bool (optional)
             Set to true to remove the callback from the list of callbacks."""
         self._click_handlers.register_callback(callback, remove=remove)
 
     def _handle_button_msg(self, _, content):
         """Handle a msg from the front-end.
 
         Parameters
         ----------
         content: dict
             Content of the msg."""
         if content.get('event', '') == 'click':
             self._click_handlers(self)
 
 
 # Remove in IPython 4.0
 ButtonWidget = DeprecatedClass(Button, 'ButtonWidget')

IPython/html/widgets/widget_float.py

@@ -1,179 +1,184
 """Float class.  
 
 Represents an unbounded float using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, CFloat, Bool, CaselessStrEnum, Tuple
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class _Float(DOMWidget):
     value = CFloat(0.0, help="Float value", sync=True) 
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
 
 
 class _BoundedFloat(_Float):
     max = CFloat(100.0, help="Max value", sync=True)
     min = CFloat(0.0, help="Min value", sync=True)
     step = CFloat(0.1, help="Minimum step that the value can take (ignored by some views)", sync=True)
 
     def __init__(self, *pargs, **kwargs):
         """Constructor"""
         DOMWidget.__init__(self, *pargs, **kwargs)
         self._validate('value', None, self.value)
         self.on_trait_change(self._validate, ['value', 'min', 'max'])
 
     def _validate(self, name, old, new):
         """Validate value, max, min."""
         if self.min > new or new > self.max:
             self.value = min(max(new, self.min), self.max)
 
 
+@register()
 class FloatText(_Float):
     _view_name = Unicode('FloatTextView', sync=True)
 
 
+@register()
 class BoundedFloatText(_BoundedFloat):
     _view_name = Unicode('FloatTextView', sync=True)
 
 
+@register()
 class FloatSlider(_BoundedFloat):
     _view_name = Unicode('FloatSliderView', sync=True)
     orientation = CaselessStrEnum(values=['horizontal', 'vertical'], 
         default_value='horizontal', 
         help="Vertical or horizontal.", allow_none=False, sync=True)
     _range = Bool(False, help="Display a range selector", sync=True)
     readout = Bool(True, help="Display the current value of the slider next to it.", sync=True)
     slider_color = Unicode(sync=True)
 
 
+@register()
 class FloatProgress(_BoundedFloat):
     _view_name = Unicode('ProgressView', sync=True)
 
     bar_style = CaselessStrEnum(
         values=['success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the progess bar.""")
 
 class _FloatRange(_Float):
     value = Tuple(CFloat, CFloat, default_value=(0.0, 1.0), help="Tuple of (lower, upper) bounds", sync=True)
     lower = CFloat(0.0, help="Lower bound", sync=False)
     upper = CFloat(1.0, help="Upper bound", sync=False)
     
     def __init__(self, *pargs, **kwargs):
         value_given = 'value' in kwargs
         lower_given = 'lower' in kwargs
         upper_given = 'upper' in kwargs
         if value_given and (lower_given or upper_given):
             raise ValueError("Cannot specify both 'value' and 'lower'/'upper' for range widget")
         if lower_given != upper_given:
             raise ValueError("Must specify both 'lower' and 'upper' for range widget")
         
         DOMWidget.__init__(self, *pargs, **kwargs)
         
         # ensure the traits match, preferring whichever (if any) was given in kwargs
         if value_given:
             self.lower, self.upper = self.value
         else:
             self.value = (self.lower, self.upper)
         
         self.on_trait_change(self._validate, ['value', 'upper', 'lower'])
     
     def _validate(self, name, old, new):
         if name == 'value':
             self.lower, self.upper = min(new), max(new)
         elif name == 'lower':
             self.value = (new, self.value[1])
         elif name == 'upper':
             self.value = (self.value[0], new)
 
 class _BoundedFloatRange(_FloatRange):
     step = CFloat(1.0, help="Minimum step that the value can take (ignored by some views)", sync=True)
     max = CFloat(100.0, help="Max value", sync=True)
     min = CFloat(0.0, help="Min value", sync=True)
     
     def __init__(self, *pargs, **kwargs):
         any_value_given = 'value' in kwargs or 'upper' in kwargs or 'lower' in kwargs
         _FloatRange.__init__(self, *pargs, **kwargs)
         
         # ensure a minimal amount of sanity
         if self.min > self.max:
             raise ValueError("min must be <= max")
         
         if any_value_given:
             # if a value was given, clamp it within (min, max)
             self._validate("value", None, self.value)
         else:
             # otherwise, set it to 25-75% to avoid the handles overlapping
             self.value = (0.75*self.min + 0.25*self.max,
                           0.25*self.min + 0.75*self.max)
         # callback already set for 'value', 'lower', 'upper'
         self.on_trait_change(self._validate, ['min', 'max'])
 
 
     def _validate(self, name, old, new):
         if name == "min":
             if new > self.max:
                 raise ValueError("setting min > max")
             self.min = new
         elif name == "max":
             if new < self.min:
                 raise ValueError("setting max < min")
             self.max = new
         
         low, high = self.value
         if name == "value":
             low, high = min(new), max(new)
         elif name == "upper":
             if new < self.lower:
                 raise ValueError("setting upper < lower")
             high = new
         elif name == "lower":
             if new > self.upper:
                 raise ValueError("setting lower > upper")
             low = new
         
         low = max(self.min, min(low, self.max))
         high = min(self.max, max(high, self.min))
         
         # determine the order in which we should update the
         # lower, upper traits to avoid a temporary inverted overlap
         lower_first = high < self.lower
         
         self.value = (low, high)
         if lower_first:
             self.lower = low
             self.upper = high
         else:
             self.upper = high
             self.lower = low
 
 
+@register()
 class FloatRangeSlider(_BoundedFloatRange):
     _view_name = Unicode('FloatSliderView', sync=True)
     orientation = CaselessStrEnum(values=['horizontal', 'vertical'], 
         default_value='horizontal', allow_none=False, 
         help="Vertical or horizontal.", sync=True)
     _range = Bool(True, help="Display a range selector", sync=True)
     readout = Bool(True, help="Display the current value of the slider next to it.", sync=True)
     slider_color = Unicode(sync=True)
 
 # Remove in IPython 4.0
 FloatTextWidget = DeprecatedClass(FloatText, 'FloatTextWidget')
 BoundedFloatTextWidget = DeprecatedClass(BoundedFloatText, 'BoundedFloatTextWidget')
 FloatSliderWidget = DeprecatedClass(FloatSlider, 'FloatSliderWidget')
 FloatProgressWidget = DeprecatedClass(FloatProgress, 'FloatProgressWidget')

IPython/html/widgets/widget_image.py

@@ -1,46 +1,47
 """Image class.  
 
 Represents an image in the frontend using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 import base64
 
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, CUnicode, Bytes
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
+@register()
 class Image(DOMWidget):
     """Displays an image as a widget.
 
     The `value` of this widget accepts a byte string.  The byte string is the raw
     image data that you want the browser to display.  You can explicitly define
     the format of the byte string using the `format` trait (which defaults to
     "png")."""
     _view_name = Unicode('ImageView', sync=True)
     
     # Define the custom state properties to sync with the front-end
     format = Unicode('png', sync=True)
     width = CUnicode(sync=True)
     height = CUnicode(sync=True)
     _b64value = Unicode(sync=True)
     
     value = Bytes()
     def _value_changed(self, name, old, new):
         self._b64value = base64.b64encode(new)
 
 
 # Remove in IPython 4.0
 ImageWidget = DeprecatedClass(Image, 'ImageWidget')

IPython/html/widgets/widget_int.py

@@ -1,192 +1,197
 """Int class.  
 
 Represents an unbounded int using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, CInt, Bool, CaselessStrEnum, Tuple
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class _Int(DOMWidget):
     """Base class used to create widgets that represent an int."""
     value = CInt(0, help="Int value", sync=True) 
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
 
 
 class _BoundedInt(_Int):
     """Base class used to create widgets that represent a int that is bounded
     by a minium and maximum."""
     step = CInt(1, help="Minimum step that the value can take (ignored by some views)", sync=True)
     max = CInt(100, help="Max value", sync=True)
     min = CInt(0, help="Min value", sync=True)
 
     def __init__(self, *pargs, **kwargs):
         """Constructor"""
         DOMWidget.__init__(self, *pargs, **kwargs)
         self.on_trait_change(self._validate_value, ['value'])
         self.on_trait_change(self._handle_max_changed, ['max'])
         self.on_trait_change(self._handle_min_changed, ['min'])
 
     def _validate_value(self, name, old, new):
         """Validate value."""
         if self.min > new or new > self.max:
             self.value = min(max(new, self.min), self.max)
 
     def _handle_max_changed(self, name, old, new):
         """Make sure the min is always <= the max."""
         if new < self.min:
             raise ValueError("setting max < min")
 
     def _handle_min_changed(self, name, old, new):
         """Make sure the max is always >= the min."""
         if new > self.max:
             raise ValueError("setting min > max")
 
+@register()
 class IntText(_Int):
     """Textbox widget that represents a int."""
     _view_name = Unicode('IntTextView', sync=True)
 
 
+@register()
 class BoundedIntText(_BoundedInt):
     """Textbox widget that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('IntTextView', sync=True)
 
 
+@register()
 class IntSlider(_BoundedInt):
     """Slider widget that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('IntSliderView', sync=True)
     orientation = CaselessStrEnum(values=['horizontal', 'vertical'], 
         default_value='horizontal', allow_none=False, 
         help="Vertical or horizontal.", sync=True)
     _range = Bool(False, help="Display a range selector", sync=True)
     readout = Bool(True, help="Display the current value of the slider next to it.", sync=True)
     slider_color = Unicode(sync=True)
 
 
+@register()
 class IntProgress(_BoundedInt):
     """Progress bar that represents a int bounded by a minimum and maximum value."""
     _view_name = Unicode('ProgressView', sync=True)
 
     bar_style = CaselessStrEnum(
         values=['success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the progess bar.""")
 
 class _IntRange(_Int):
     value = Tuple(CInt, CInt, default_value=(0, 1), help="Tuple of (lower, upper) bounds", sync=True)
     lower = CInt(0, help="Lower bound", sync=False)
     upper = CInt(1, help="Upper bound", sync=False)
     
     def __init__(self, *pargs, **kwargs):
         value_given = 'value' in kwargs
         lower_given = 'lower' in kwargs
         upper_given = 'upper' in kwargs
         if value_given and (lower_given or upper_given):
             raise ValueError("Cannot specify both 'value' and 'lower'/'upper' for range widget")
         if lower_given != upper_given:
             raise ValueError("Must specify both 'lower' and 'upper' for range widget")
         
         DOMWidget.__init__(self, *pargs, **kwargs)
         
         # ensure the traits match, preferring whichever (if any) was given in kwargs
         if value_given:
             self.lower, self.upper = self.value
         else:
             self.value = (self.lower, self.upper)
 
         self.on_trait_change(self._validate, ['value', 'upper', 'lower'])
     
     def _validate(self, name, old, new):
         if name == 'value':
             self.lower, self.upper = min(new), max(new)
         elif name == 'lower':
             self.value = (new, self.value[1])
         elif name == 'upper':
             self.value = (self.value[0], new)
 
 class _BoundedIntRange(_IntRange):
     step = CInt(1, help="Minimum step that the value can take (ignored by some views)", sync=True)
     max = CInt(100, help="Max value", sync=True)
     min = CInt(0, help="Min value", sync=True)
 
     def __init__(self, *pargs, **kwargs):
         any_value_given = 'value' in kwargs or 'upper' in kwargs or 'lower' in kwargs
         _IntRange.__init__(self, *pargs, **kwargs)
         
         # ensure a minimal amount of sanity
         if self.min > self.max:
             raise ValueError("min must be <= max")
         
         if any_value_given:
             # if a value was given, clamp it within (min, max)
             self._validate("value", None, self.value)
         else:
             # otherwise, set it to 25-75% to avoid the handles overlapping
             self.value = (0.75*self.min + 0.25*self.max,
                           0.25*self.min + 0.75*self.max)
         # callback already set for 'value', 'lower', 'upper'
         self.on_trait_change(self._validate, ['min', 'max'])
 
     def _validate(self, name, old, new):
         if name == "min":
             if new > self.max:
                 raise ValueError("setting min > max")
         elif name == "max":
             if new < self.min:
                 raise ValueError("setting max < min")
         
         low, high = self.value
         if name == "value":
             low, high = min(new), max(new)
         elif name == "upper":
             if new < self.lower:
                 raise ValueError("setting upper < lower")
             high = new
         elif name == "lower":
             if new > self.upper:
                 raise ValueError("setting lower > upper")
             low = new
         
         low = max(self.min, min(low, self.max))
         high = min(self.max, max(high, self.min))
         
         # determine the order in which we should update the
         # lower, upper traits to avoid a temporary inverted overlap
         lower_first = high < self.lower
         
         self.value = (low, high)
         if lower_first:
             self.lower = low
             self.upper = high
         else:
             self.upper = high
             self.lower = low
 
+@register()
 class IntRangeSlider(_BoundedIntRange):
     _view_name = Unicode('IntSliderView', sync=True)
     orientation = CaselessStrEnum(values=['horizontal', 'vertical'], 
         default_value='horizontal', allow_none=False, 
         help="Vertical or horizontal.", sync=True)
     _range = Bool(True, help="Display a range selector", sync=True)
     readout = Bool(True, help="Display the current value of the slider next to it.", sync=True)
     slider_color = Unicode(sync=True)
 
 # Remove in IPython 4.0
 IntTextWidget = DeprecatedClass(IntText, 'IntTextWidget')
 BoundedIntTextWidget = DeprecatedClass(BoundedIntText, 'BoundedIntTextWidget')
 IntSliderWidget = DeprecatedClass(IntSlider, 'IntSliderWidget')
 IntProgressWidget = DeprecatedClass(IntProgress, 'IntProgressWidget')

IPython/html/widgets/widget_selection.py

@@ -1,153 +1,156
 """Selection classes.
 
 Represents an enumeration using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from collections import OrderedDict
 from threading import Lock
 
-from .widget import DOMWidget
+from .widget import DOMWidget, register
 from IPython.utils.traitlets import Unicode, List, Bool, Any, Dict, TraitError, CaselessStrEnum
 from IPython.utils.py3compat import unicode_type
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # SelectionWidget
 #-----------------------------------------------------------------------------
 class _Selection(DOMWidget):
     """Base class for Selection widgets
     
     ``values`` can be specified as a list or dict. If given as a list,
     it will be transformed to a dict of the form ``{str(value):value}``.
     """
     
     value = Any(help="Selected value")
     values = Dict(help="""Dictionary of {name: value} the user can select.
     
     The keys of this dictionary are the strings that will be displayed in the UI,
     representing the actual Python choices.
     
     The keys of this dictionary are also available as value_names.
     """)
     value_name = Unicode(help="The name of the selected value", sync=True)
     value_names = List(Unicode, help="""Read-only list of names for each value.
         
         If values is specified as a list, this is the string representation of each element.
         Otherwise, it is the keys of the values dictionary.
         
         These strings are used to display the choices in the front-end.""", sync=True)
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
     
     
     def __init__(self, *args, **kwargs):
         self.value_lock = Lock()
         self._in_values_changed = False
         if 'values' in kwargs:
             values = kwargs['values']
             # convert list values to an dict of {str(v):v}
             if isinstance(values, list):
                 # preserve list order with an OrderedDict
                 kwargs['values'] = OrderedDict((unicode_type(v), v) for v in values)
             # python3.3 turned on hash randomization by default - this means that sometimes, randomly
             # we try to set value before setting values, due to dictionary ordering.  To fix this, force
             # the setting of self.values right now, before anything else runs
             self.values = kwargs.pop('values')
         DOMWidget.__init__(self, *args, **kwargs)
         self._value_in_values()
     
     def _values_changed(self, name, old, new):
         """Handles when the values dict has been changed.
 
         Setting values implies setting value names from the keys of the dict.
         """
         self._in_values_changed = True
         try:
             self.value_names = list(new.keys())
         finally:
             self._in_values_changed = False
         self._value_in_values()
 
     def _value_in_values(self):
         # ensure that the chosen value is one of the choices
         if self.values:
             if self.value not in self.values.values():
                 self.value = next(iter(self.values.values()))
     
     def _value_names_changed(self, name, old, new):
         if not self._in_values_changed:
             raise TraitError("value_names is a read-only proxy to values.keys(). Use the values dict instead.")
 
     def _value_changed(self, name, old, new):
         """Called when value has been changed"""
         if self.value_lock.acquire(False):
             try:
                 # Reverse dictionary lookup for the value name
                 for k,v in self.values.items():
                     if new == v:
                         # set the selected value name
                         self.value_name = k
                         return
                 # undo the change, and raise KeyError
                 self.value = old
                 raise KeyError(new)
             finally:
                 self.value_lock.release()
 
     def _value_name_changed(self, name, old, new):
         """Called when the value name has been changed (typically by the frontend)."""
         if self.value_lock.acquire(False):
             try:
                 self.value = self.values[new]
             finally:
                 self.value_lock.release()
 
 
+@register()
 class ToggleButtons(_Selection):
     """Group of toggle buttons that represent an enumeration.  Only one toggle
     button can be toggled at any point in time.""" 
     _view_name = Unicode('ToggleButtonsView', sync=True)
 
     button_style = CaselessStrEnum(
         values=['primary', 'success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the buttons.""")
 
-
+@register()
 class Dropdown(_Selection):
     """Allows you to select a single item from a dropdown."""
     _view_name = Unicode('DropdownView', sync=True)
 
     button_style = CaselessStrEnum(
         values=['primary', 'success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the buttons.""")
 
-
+@register()
 class RadioButtons(_Selection):
     """Group of radio buttons that represent an enumeration.  Only one radio
     button can be toggled at any point in time.""" 
     _view_name = Unicode('RadioButtonsView', sync=True)
     
 
+
+@register()
 class Select(_Selection):
     """Listbox that only allows one item to be selected at any given time."""
     _view_name = Unicode('SelectView', sync=True)
 
 
 # Remove in IPython 4.0
 ToggleButtonsWidget = DeprecatedClass(ToggleButtons, 'ToggleButtonsWidget')
 DropdownWidget = DeprecatedClass(Dropdown, 'DropdownWidget')
 RadioButtonsWidget = DeprecatedClass(RadioButtons, 'RadioButtonsWidget')
 SelectWidget = DeprecatedClass(Select, 'SelectWidget')

IPython/html/widgets/widget_selectioncontainer.py

@@ -1,67 +1,68
 """SelectionContainer class.  
 
 Represents a multipage container that can be used to group other widgets into
 pages.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget_box import Box
+from .widget_box import Box, register
 from IPython.utils.traitlets import Unicode, Dict, CInt
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class _SelectionContainer(Box):
     """Base class used to display multiple child widgets."""
     _titles = Dict(help="Titles of the pages", sync=True)
     selected_index = CInt(0, sync=True)
 
     # Public methods
     def set_title(self, index, title):
         """Sets the title of a container page.
 
         Parameters
         ----------
         index : int
             Index of the container page
         title : unicode
             New title"""
         self._titles[index] = title
         self.send_state('_titles')
 
     def get_title(self, index):
         """Gets the title of a container pages.
 
         Parameters
         ----------
         index : int
             Index of the container page"""
         if index in self._titles:
             return self._titles[index]
         else:
             return None
 
-
+@register()
 class Accordion(_SelectionContainer):
     """Displays children each on a separate accordion page."""
     _view_name = Unicode('AccordionView', sync=True)
 
 
+@register()
 class Tab(_SelectionContainer):
     """Displays children each on a separate accordion tab."""
     _view_name = Unicode('TabView', sync=True)
 
 
 # Remove in IPython 4.0
 AccordionWidget = DeprecatedClass(Accordion, 'AccordionWidget')
 TabWidget = DeprecatedClass(Tab, 'TabWidget')

IPython/html/widgets/widget_string.py

@@ -1,87 +1,91
 """String class.  
 
 Represents a unicode string using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from .widget import DOMWidget, CallbackDispatcher
+from .widget import DOMWidget, CallbackDispatcher, register
 from IPython.utils.traitlets import Unicode, Bool
 from IPython.utils.warn import DeprecatedClass
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class _String(DOMWidget):
     """Base class used to create widgets that represent a string."""
     value = Unicode(help="String value", sync=True)
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
     placeholder = Unicode("", help="Placeholder text to display when nothing has been typed", sync=True)
 
 
+@register()
 class HTML(_String):
     """Renders the string `value` as HTML."""
     _view_name = Unicode('HTMLView', sync=True)
 
 
+@register()
 class Latex(_String):
     """Renders math inside the string `value` as Latex (requires $ $ or $$ $$ 
     and similar latex tags)."""
     _view_name = Unicode('LatexView', sync=True)
 
 
+@register()
 class Textarea(_String):
     """Multiline text area widget."""
     _view_name = Unicode('TextareaView', sync=True)
 
     def scroll_to_bottom(self):
         self.send({"method": "scroll_to_bottom"})
 
 
+@register()
 class Text(_String):
     """Single line textbox widget."""
     _view_name = Unicode('TextView', sync=True)
 
     def __init__(self, **kwargs):
         super(Text, self).__init__(**kwargs)
         self._submission_callbacks = CallbackDispatcher()
         self.on_msg(self._handle_string_msg)
 
     def _handle_string_msg(self, _, content):
         """Handle a msg from the front-end.
 
         Parameters
         ----------
         content: dict
             Content of the msg."""
         if content.get('event', '') == 'submit':
             self._submission_callbacks(self)
 
     def on_submit(self, callback, remove=False):
         """(Un)Register a callback to handle text submission.
 
         Triggered when the user clicks enter.
 
         Parameters
         ----------
         callback: callable
             Will be called with exactly one argument: the Widget instance
         remove: bool (optional)
             Whether to unregister the callback"""
         self._submission_callbacks.register_callback(callback, remove=remove)
 
 
 # Remove in IPython 4.0
 HTMLWidget = DeprecatedClass(HTML, 'HTMLWidget')
 LatexWidget = DeprecatedClass(Latex, 'LatexWidget')
 TextareaWidget = DeprecatedClass(Textarea, 'TextareaWidget')
 TextWidget = DeprecatedClass(Text, 'TextWidget')