|
|
"""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 inspect
|
|
|
import types
|
|
|
|
|
|
from IPython.kernel.comm import Comm
|
|
|
from IPython.config import LoggingConfigurable
|
|
|
from IPython.utils.traitlets import Unicode, Dict, Instance, Bool
|
|
|
from IPython.utils.py3compat import string_types
|
|
|
|
|
|
#-----------------------------------------------------------------------------
|
|
|
# Classes
|
|
|
#-----------------------------------------------------------------------------
|
|
|
class Widget(LoggingConfigurable):
|
|
|
|
|
|
#-------------------------------------------------------------------------
|
|
|
# Class attributes
|
|
|
#-------------------------------------------------------------------------
|
|
|
widget_construction_callback = None
|
|
|
widgets = {}
|
|
|
|
|
|
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
|
|
|
|
|
|
def _call_widget_constructed(widget):
|
|
|
"""Class 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)
|
|
|
|
|
|
#-------------------------------------------------------------------------
|
|
|
# Traits
|
|
|
#-------------------------------------------------------------------------
|
|
|
model_name = Unicode('WidgetModel', help="""Name of the backbone model
|
|
|
registered in the front-end to create and sync this widget with.""")
|
|
|
view_name = Unicode(help="""Default view registered in the front-end
|
|
|
to use to represent the widget.""", sync=True)
|
|
|
_comm = Instance('IPython.kernel.comm.Comm')
|
|
|
|
|
|
#-------------------------------------------------------------------------
|
|
|
# (Con/de)structor
|
|
|
#-------------------------------------------------------------------------
|
|
|
def __init__(self, **kwargs):
|
|
|
"""Public constructor"""
|
|
|
self.closed = False
|
|
|
self._property_lock = (None, None)
|
|
|
self._display_callbacks = []
|
|
|
self._msg_callbacks = []
|
|
|
self._keys = None
|
|
|
super(Widget, self).__init__(**kwargs)
|
|
|
|
|
|
self.on_trait_change(self._handle_property_changed, self.keys)
|
|
|
Widget._call_widget_constructed(self)
|
|
|
|
|
|
def __del__(self):
|
|
|
"""Object disposal"""
|
|
|
self.close()
|
|
|
|
|
|
#-------------------------------------------------------------------------
|
|
|
# Properties
|
|
|
#-------------------------------------------------------------------------
|
|
|
@property
|
|
|
def keys(self):
|
|
|
"""Gets a list of the traitlets that should be synced with the front-end."""
|
|
|
if self._keys is None:
|
|
|
self._keys = []
|
|
|
for trait_name in self.trait_names():
|
|
|
if self.trait_metadata(trait_name, 'sync'):
|
|
|
self._keys.append(trait_name)
|
|
|
return self._keys
|
|
|
|
|
|
@property
|
|
|
def comm(self):
|
|
|
"""Gets the Comm associated with this widget.
|
|
|
|
|
|
If a Comm doesn't exist yet, a Comm will be created automagically."""
|
|
|
if self._comm is None:
|
|
|
# Create a comm.
|
|
|
self._comm = Comm(target_name=self.model_name)
|
|
|
self._comm.on_msg(self._handle_msg)
|
|
|
self._comm.on_close(self._close)
|
|
|
Widget.widgets[self.model_id] = self
|
|
|
|
|
|
# first update
|
|
|
self.send_state()
|
|
|
return self._comm
|
|
|
|
|
|
@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 widget which closes the underlying comm.
|
|
|
When the comm is closed, all of the widget views are automatically
|
|
|
removed from the front-end."""
|
|
|
if not self.closed:
|
|
|
self._comm.close()
|
|
|
self._close()
|
|
|
|
|
|
def send_state(self, key=None):
|
|
|
"""Sends the widget state, or a piece of it, to the front-end.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
key : unicode (optional)
|
|
|
A single property's name to sync with the front-end.
|
|
|
"""
|
|
|
self._send({
|
|
|
"method" : "update",
|
|
|
"state" : self.get_state()
|
|
|
})
|
|
|
|
|
|
def get_state(self, key=None):
|
|
|
"""Gets the widget state, or a piece of it.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
key : unicode (optional)
|
|
|
A single property's name to get.
|
|
|
"""
|
|
|
keys = self.keys if key is None else [key]
|
|
|
return {k: self._pack_widgets(getattr(self, k)) for k in keys}
|
|
|
|
|
|
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 recieve callback.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
callback: method handler
|
|
|
Can have a signature of:
|
|
|
- callback(content)
|
|
|
- callback(sender, content)
|
|
|
remove: bool
|
|
|
True if the callback should be unregistered."""
|
|
|
if remove and callback in self._msg_callbacks:
|
|
|
self._msg_callbacks.remove(callback)
|
|
|
elif not remove and not callback in self._msg_callbacks:
|
|
|
if callable(callback):
|
|
|
argspec = inspect.getargspec(callback)
|
|
|
nargs = len(argspec[0])
|
|
|
|
|
|
# Bound methods have an additional 'self' argument
|
|
|
if isinstance(callback, types.MethodType):
|
|
|
nargs -= 1
|
|
|
|
|
|
# Call the callback
|
|
|
if nargs == 1:
|
|
|
self._msg_callbacks.append(lambda sender, content: callback(content))
|
|
|
elif nargs == 2:
|
|
|
self._msg_callbacks.append(callback)
|
|
|
else:
|
|
|
raise TypeError('Widget msg callback must ' \
|
|
|
'accept 1 or 2 arguments, not %d.' % nargs)
|
|
|
else:
|
|
|
raise Exception('Callback must be callable.')
|
|
|
|
|
|
def on_displayed(self, callback, remove=False):
|
|
|
"""(Un)Register a widget displayed callback.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
callback: method handler
|
|
|
Can have a signature of:
|
|
|
- callback(sender, **kwargs)
|
|
|
kwargs from display call passed through without modification.
|
|
|
remove: bool
|
|
|
True if the callback should be unregistered."""
|
|
|
if remove and callback in self._display_callbacks:
|
|
|
self._display_callbacks.remove(callback)
|
|
|
elif not remove and not callback in self._display_callbacks:
|
|
|
if callable(handler):
|
|
|
self._display_callbacks.append(callback)
|
|
|
else:
|
|
|
raise Exception('Callback must be callable.')
|
|
|
|
|
|
#-------------------------------------------------------------------------
|
|
|
# Support methods
|
|
|
#-------------------------------------------------------------------------
|
|
|
@contextmanager
|
|
|
def _property_lock(self, key, value):
|
|
|
"""Lock a property-value pair.
|
|
|
|
|
|
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)
|
|
|
|
|
|
def _should_send_property(self, key, value):
|
|
|
"""Check the property lock (property_lock)"""
|
|
|
return key != self._property_lock[0] or \
|
|
|
value != self._property_lock[1]
|
|
|
|
|
|
def _close(self):
|
|
|
"""Unsafe close"""
|
|
|
del Widget.widgets[self.model_id]
|
|
|
self._comm = None
|
|
|
self.closed = True
|
|
|
|
|
|
# Event handlers
|
|
|
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._handle_receive_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_receive_state(self, sync_data):
|
|
|
"""Called when a state is received from the front-end."""
|
|
|
for name in self.keys:
|
|
|
if name in sync_data:
|
|
|
value = self._unpack_widgets(sync_data[name])
|
|
|
with self._property_lock(name, value):
|
|
|
setattr(self, name, value)
|
|
|
|
|
|
def _handle_custom_msg(self, content):
|
|
|
"""Called when a custom msg is received."""
|
|
|
for handler in self._msg_callbacks:
|
|
|
handler(self, content)
|
|
|
|
|
|
def _handle_property_changed(self, name, old, new):
|
|
|
"""Called when a property has been changed."""
|
|
|
# Make sure this isn't information that the front-end just sent us.
|
|
|
if self._should_send_property(name, new):
|
|
|
# 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"""
|
|
|
for handler in self._display_callbacks:
|
|
|
handler(self, **kwargs)
|
|
|
|
|
|
def _pack_widgets(self, x):
|
|
|
"""Recursively converts all widget instances to model id strings.
|
|
|
|
|
|
Children widgets will be stored and transmitted to the front-end by
|
|
|
their model ids. Return value must be JSON-able."""
|
|
|
if isinstance(x, dict):
|
|
|
return {k: self._pack_widgets(v) for k, v in x.items()}
|
|
|
elif isinstance(x, list):
|
|
|
return [self._pack_widgets(v) for v in x]
|
|
|
elif isinstance(x, Widget):
|
|
|
return x.model_id
|
|
|
else:
|
|
|
return x # Value must be JSON-able
|
|
|
|
|
|
def _unpack_widgets(self, x):
|
|
|
"""Recursively converts all model id strings to widget instances.
|
|
|
|
|
|
Children widgets will be stored and transmitted to the front-end by
|
|
|
their model ids."""
|
|
|
if isinstance(x, dict):
|
|
|
return {k: self._unpack_widgets(v) for k, v in x.items()}
|
|
|
elif isinstance(x, list):
|
|
|
return [self._unpack_widgets(v) for v in x]
|
|
|
elif isinstance(x, string_types):
|
|
|
return x if x not in Widget.widgets else Widget.widgets[x]
|
|
|
else:
|
|
|
return x
|
|
|
|
|
|
def _ipython_display_(self, **kwargs):
|
|
|
"""Called when `IPython.display.display` is called on the widget."""
|
|
|
# Show view. By sending a display message, the comm is opened and the
|
|
|
# initial state is sent.
|
|
|
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 or not the widget is visible.", sync=True)
|
|
|
_css = Dict(sync=True) # Internal CSS property dict
|
|
|
|
|
|
def get_css(self, key, selector=""):
|
|
|
"""Get a CSS property of the widget.
|
|
|
|
|
|
Note: This function does not actually request the CSS from the
|
|
|
front-end; Only properties that have been set with set_css can be read.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
key: unicode
|
|
|
CSS key
|
|
|
selector: unicode (optional)
|
|
|
JQuery selector used when the CSS key/value was set.
|
|
|
"""
|
|
|
if selector in self._css and key in self._css[selector]:
|
|
|
return self._css[selector][key]
|
|
|
else:
|
|
|
return None
|
|
|
|
|
|
def set_css(self, *args, **kwargs):
|
|
|
"""Set one or more CSS properties of the widget.
|
|
|
|
|
|
This function has two signatures:
|
|
|
- set_css(css_dict, selector='')
|
|
|
- set_css(key, value, selector='')
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
css_dict : dict
|
|
|
CSS key/value pairs to apply
|
|
|
key: unicode
|
|
|
CSS key
|
|
|
value
|
|
|
CSS value
|
|
|
selector: unicode (optional)
|
|
|
JQuery selector to use to apply the CSS key/value. If no selector
|
|
|
is provided, an empty selector is used. An empty selector makes the
|
|
|
front-end try to apply the css to a default element. The default
|
|
|
element is an attribute unique to each view, which is a DOM element
|
|
|
of the view that should be styled with common CSS (see
|
|
|
`$el_to_style` in the Javascript code).
|
|
|
"""
|
|
|
selector = kwargs.get('selector', '')
|
|
|
if not selector in self._css:
|
|
|
self._css[selector] = {}
|
|
|
|
|
|
# Signature 1: set_css(css_dict, selector='')
|
|
|
if len(args) == 1:
|
|
|
if isinstance(args[0], dict):
|
|
|
for (key, value) in args[0].items():
|
|
|
if not (key in self._css[selector] and value == self._css[selector][key]):
|
|
|
self._css[selector][key] = value
|
|
|
self.send_state('_css')
|
|
|
else:
|
|
|
raise Exception('css_dict must be a dict.')
|
|
|
|
|
|
# Signature 2: set_css(key, value, selector='')
|
|
|
elif len(args) == 2 or len(args) == 3:
|
|
|
|
|
|
# Selector can be a positional arg if it's the 3rd value
|
|
|
if len(args) == 3:
|
|
|
selector = args[2]
|
|
|
if selector not in self._css:
|
|
|
self._css[selector] = {}
|
|
|
|
|
|
# Only update the property if it has changed.
|
|
|
key = args[0]
|
|
|
value = args[1]
|
|
|
if not (key in self._css[selector] and value == self._css[selector][key]):
|
|
|
self._css[selector][key] = value
|
|
|
self.send_state('_css') # Send new state to client.
|
|
|
else:
|
|
|
raise Exception('set_css only accepts 1-3 arguments')
|
|
|
|
|
|
def add_class(self, class_names, selector=""):
|
|
|
"""Add class[es] to a DOM element.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
class_names: unicode or list
|
|
|
Class name(s) to add to the DOM element(s).
|
|
|
selector: unicode (optional)
|
|
|
JQuery selector to select the DOM element(s) that the class(es) will
|
|
|
be added to.
|
|
|
"""
|
|
|
class_list = class_names
|
|
|
if isinstance(class_list, list):
|
|
|
class_list = ' '.join(class_list)
|
|
|
|
|
|
self.send({
|
|
|
"msg_type" : "add_class",
|
|
|
"class_list" : class_list,
|
|
|
"selector" : selector
|
|
|
})
|
|
|
|
|
|
def remove_class(self, class_names, selector=""):
|
|
|
"""Remove class[es] from a DOM element.
|
|
|
|
|
|
Parameters
|
|
|
----------
|
|
|
class_names: unicode or list
|
|
|
Class name(s) to remove from the DOM element(s).
|
|
|
selector: unicode (optional)
|
|
|
JQuery selector to select the DOM element(s) that the class(es) will
|
|
|
be removed from.
|
|
|
"""
|
|
|
class_list = class_names
|
|
|
if isinstance(class_list, list):
|
|
|
class_list = ' '.join(class_list)
|
|
|
|
|
|
self.send({
|
|
|
"msg_type" : "remove_class",
|
|
|
"class_list" : class_list,
|
|
|
"selector" : selector,
|
|
|
})
|
|
|
|
