widget.py
415 lines
| 14.2 KiB
| text/x-python
|
PythonLexer
|
r14283 | """Base Widget class. Allows user to create widgets in the backend that render | ||
in the IPython notebook frontend. | ||||
""" | ||||
#----------------------------------------------------------------------------- | ||||
# 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 | ||||
#----------------------------------------------------------------------------- | ||||
|
r14223 | from copy import copy | ||
|
r14232 | from glob import glob | ||
|
r14223 | import uuid | ||
import sys | ||||
|
r14232 | import os | ||
|
r14341 | import inspect | ||
|
r14344 | import types | ||
|
r14223 | |||
|
r14232 | import IPython | ||
|
r14229 | from IPython.kernel.comm import Comm | ||
from IPython.config import LoggingConfigurable | ||||
|
r14311 | from IPython.utils.traitlets import Unicode, Dict, List, Instance, Bool | ||
|
r14229 | from IPython.display import Javascript, display | ||
|
r14232 | from IPython.utils.py3compat import string_types | ||
|
r14283 | #----------------------------------------------------------------------------- | ||
# Classes | ||||
#----------------------------------------------------------------------------- | ||||
|
r14232 | class Widget(LoggingConfigurable): | ||
|
r14223 | |||
|
r14313 | # Shared declarations | ||
_keys = [] | ||||
|
r14283 | # Public declarations | ||
target_name = Unicode('widget', help="""Name of the backbone model | ||||
registered in the frontend to create and sync this widget with.""") | ||||
default_view_name = Unicode(help="""Default view registered in the frontend | ||||
to use to represent the widget.""") | ||||
|
r14310 | parent = Instance('IPython.html.widgets.widget.Widget') | ||
|
r14311 | visible = Bool(True, help="Whether or not the widget is visible.") | ||
|
r14310 | |||
def _parent_changed(self, name, old, new): | ||||
if self._displayed: | ||||
raise Exception('Parent cannot be set because widget has been displayed.') | ||||
elif new == self: | ||||
raise Exception('Parent cannot be set to self.') | ||||
else: | ||||
# Parent/child association | ||||
if new is not None and not self in new._children: | ||||
new._children.append(self) | ||||
if old is not None and self in old._children: | ||||
old._children.remove(self) | ||||
|
r14313 | |||
|
r14283 | # Private/protected declarations | ||
|
r14223 | _property_lock = False | ||
|
r14313 | _css = Dict() # Internal CSS property dict | ||
_add_class = List() # Used to add a js class to a DOM element (call#, selector, class_name) | ||||
_remove_class = List() # Used to remove a js class from a DOM element (call#, selector, class_name) | ||||
|
r14310 | _displayed = False | ||
_comm = None | ||||
|
r14223 | |||
|
r14310 | def __init__(self, **kwargs): | ||
|
r14283 | """Public constructor | ||
Parameters | ||||
---------- | ||||
parent : Widget instance (optional) | ||||
Widget that this widget instance is child of. When the widget is | ||||
displayed in the frontend, it's corresponding view will be made | ||||
child of the parent's view if the parent's view exists already. If | ||||
the parent's view is displayed, it will automatically display this | ||||
widget's default view as it's child. The default view can be set | ||||
via the default_view_name property. | ||||
""" | ||||
|
r14223 | self._children = [] | ||
|
r14313 | self._add_class = [0] | ||
self._remove_class = [0] | ||||
|
r14330 | self._display_callbacks = [] | ||
|
r14387 | self._msg_callbacks = [] | ||
|
r14310 | super(Widget, self).__init__(**kwargs) | ||
|
r14223 | # Register after init to allow default values to be specified | ||
self.on_trait_change(self._handle_property_changed, self.keys) | ||||
def __del__(self): | ||||
|
r14283 | """Object disposal""" | ||
|
r14223 | self.close() | ||
|
r14283 | |||
|
r14223 | def close(self): | ||
|
r14283 | """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 frontend.""" | ||||
|
r14351 | try: | ||
self._comm.close() | ||||
del self._comm | ||||
except: | ||||
pass # Comm doesn't exist and/or is already closed. | ||||
|
r14223 | |||
|
r14310 | # Properties | ||
|
r14223 | def _get_keys(self): | ||
|
r14313 | keys = ['visible', '_css', '_add_class', '_remove_class'] | ||
|
r14223 | keys.extend(self._keys) | ||
return keys | ||||
keys = property(_get_keys) | ||||
|
r14283 | # Event handlers | ||
|
r14223 | def _handle_msg(self, msg): | ||
|
r14283 | """Called when a msg is recieved from the frontend""" | ||
|
r14387 | data = msg['content']['data'] | ||
|
r14273 | # Handle backbone sync methods CREATE, PATCH, and UPDATE | ||
|
r14387 | if 'sync_method' in data and 'sync_data' in data: | ||
sync_method = data['sync_method'] | ||||
sync_data = data['sync_data'] | ||||
self._handle_recieve_state(sync_data) # handles all methods | ||||
# Handle a custom msg from the front-end | ||||
if 'custom_content' in data: | ||||
self._handle_custom_msg(data['custom_content']) | ||||
def _handle_custom_msg(self, content): | ||||
"""Called when a custom msg is recieved.""" | ||||
for handler in self._msg_callbacks: | ||||
if callable(handler): | ||||
argspec = inspect.getargspec(handler) | ||||
nargs = len(argspec[0]) | ||||
# Bound methods have an additional 'self' argument | ||||
if isinstance(handler, types.MethodType): | ||||
nargs -= 1 | ||||
# Call the callback | ||||
if nargs == 1: | ||||
handler(content) | ||||
elif nargs == 2: | ||||
handler(self, content) | ||||
else: | ||||
raise TypeError('Widget msg callback must ' \ | ||||
'accept 1 or 2 arguments, not %d.' % nargs) | ||||
|
r14223 | |||
def _handle_recieve_state(self, sync_data): | ||||
|
r14283 | """Called when a state is recieved from the frontend.""" | ||
|
r14223 | self._property_lock = True | ||
try: | ||||
# Use _keys instead of keys - Don't get retrieve the css from the client side. | ||||
for name in self._keys: | ||||
if name in sync_data: | ||||
setattr(self, name, sync_data[name]) | ||||
finally: | ||||
self._property_lock = False | ||||
def _handle_property_changed(self, name, old, new): | ||||
|
r14283 | """Called when a proeprty has been changed.""" | ||
|
r14310 | if not self._property_lock and self._comm is not None: | ||
|
r14223 | # TODO: Validate properties. | ||
# Send new state to frontend | ||||
|
r14273 | self.send_state(key=name) | ||
|
r14232 | |||
def _handle_close(self): | ||||
|
r14283 | """Called when the comm is closed by the frontend.""" | ||
|
r14310 | self._comm = None | ||
|
r14387 | |||
def _handle_displayed(self, view_name): | ||||
"""Called when a view has been displayed for this widget instance | ||||
Parameters | ||||
---------- | ||||
view_name: unicode | ||||
Name of the view that was displayed.""" | ||||
for handler in self._display_callbacks: | ||||
if callable(handler): | ||||
argspec = inspect.getargspec(handler) | ||||
nargs = len(argspec[0]) | ||||
# Bound methods have an additional 'self' argument | ||||
if isinstance(handler, types.MethodType): | ||||
nargs -= 1 | ||||
# Call the callback | ||||
if nargs == 0: | ||||
handler() | ||||
elif nargs == 1: | ||||
handler(self) | ||||
elif nargs == 2: | ||||
handler(self, view_name) | ||||
else: | ||||
raise TypeError('Widget display callback must ' \ | ||||
'accept 0-2 arguments, not %d.' % nargs) | ||||
|
r14223 | |||
|
r14283 | # Public methods | ||
def send_state(self, key=None): | ||||
"""Sends the widget state, or a piece of it, to the frontend. | ||||
Parameters | ||||
---------- | ||||
key : unicode (optional) | ||||
A single property's name to sync with the frontend. | ||||
""" | ||||
|
r14310 | if self._comm is not None: | ||
|
r14289 | state = {} | ||
|
r14283 | |||
|
r14289 | # If a key is provided, just send the state of that key. | ||
keys = [] | ||||
if key is None: | ||||
keys.extend(self.keys) | ||||
else: | ||||
keys.append(key) | ||||
for key in self.keys: | ||||
try: | ||||
state[key] = getattr(self, key) | ||||
except Exception as e: | ||||
pass # Eat errors, nom nom nom | ||||
|
r14310 | self._comm.send({"method": "update", | ||
|
r14289 | "state": state}) | ||
|
r14283 | |||
def get_css(self, key, selector=""): | ||||
|
r14322 | """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. | ||||
|
r14283 | |||
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 | ||||
|
r14322 | def set_css(self, *args, **kwargs): | ||
"""Set one or more CSS properties of the widget (shared among all of the | ||||
views). This function has two signatures: | ||||
- set_css(css_dict, [selector='']) | ||||
- set_css(key, value, [selector='']) | ||||
|
r14283 | |||
Parameters | ||||
---------- | ||||
|
r14322 | css_dict : dict | ||
CSS key/value pairs to apply | ||||
|
r14283 | key: unicode | ||
CSS key | ||||
value | ||||
CSS value | ||||
selector: unicode (optional) | ||||
JQuery selector to use to apply the CSS key/value. | ||||
""" | ||||
|
r14322 | selector = kwargs.get('selector', '') | ||
# Signature 1: set_css(css_dict, [selector='']) | ||||
if len(args) == 1: | ||||
if isinstance(args[0], dict): | ||||
for (key, value) in args[0].items(): | ||||
self.set_css(key, value, selector=selector) | ||||
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 in 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') | ||||
|
r14313 | |||
def add_class(self, class_name, selector=""): | ||||
"""Add class[es] to a DOM element | ||||
Parameters | ||||
---------- | ||||
class_name: unicode | ||||
Class name(s) to add to the DOM element(s). Multiple class names | ||||
must be space separated. | ||||
selector: unicode (optional) | ||||
JQuery selector to select the DOM element(s) that the class(es) will | ||||
be added to. | ||||
""" | ||||
self._add_class = [self._add_class[0] + 1, selector, class_name] | ||||
self.send_state(key='_add_class') | ||||
def remove_class(self, class_name, selector=""): | ||||
"""Remove class[es] from a DOM element | ||||
Parameters | ||||
---------- | ||||
class_name: unicode | ||||
Class name(s) to remove from the DOM element(s). Multiple class | ||||
names must be space separated. | ||||
selector: unicode (optional) | ||||
JQuery selector to select the DOM element(s) that the class(es) will | ||||
be removed from. | ||||
""" | ||||
self._remove_class = [self._remove_class[0] + 1, selector, class_name] | ||||
self.send_state(key='_remove_class') | ||||
|
r14283 | |||
|
r14387 | 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. | ||||
""" | ||||
if self._comm is not None: | ||||
self._comm.send({"method": "custom", | ||||
"custom_content": content}) | ||||
def on_msg(self, callback, remove=False): | ||||
"""Register a callback for when a custom msg is recieved from the front-end | ||||
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: | ||||
self._msg_callbacks.append(callback) | ||||
|
r14330 | def on_displayed(self, callback, remove=False): | ||
"""Register a callback to be called when the widget has been displayed | ||||
|
r14332 | Parameters | ||
---------- | ||||
|
r14330 | callback: method handler | ||
Can have a signature of: | ||||
- callback() | ||||
- callback(sender) | ||||
- callback(sender, view_name) | ||||
remove: bool | ||||
True if the callback should be unregistered.""" | ||||
|
r14387 | if remove and callback in self._display_callbacks: | ||
|
r14330 | self._display_callbacks.remove(callback) | ||
|
r14387 | elif not remove and not callback in self._display_callbacks: | ||
|
r14330 | self._display_callbacks.append(callback) | ||
|
r14283 | # Support methods | ||
|
r14232 | def _repr_widget_(self, view_name=None): | ||
|
r14283 | """Function that is called when `IPython.display.display` is called on | ||
the widget. | ||||
Parameters | ||||
---------- | ||||
view_name: unicode (optional) | ||||
View to display in the frontend. Overrides default_view_name.""" | ||||
|
r14310 | |||
|
r14223 | if not view_name: | ||
|
r14232 | view_name = self.default_view_name | ||
# Create a comm. | ||||
|
r14310 | if self._comm is None: | ||
self._comm = Comm(target_name=self.target_name) | ||||
self._comm.on_msg(self._handle_msg) | ||||
self._comm.on_close(self._handle_close) | ||||
|
r14232 | |||
|
r14223 | # Make sure model is syncronized | ||
self.send_state() | ||||
# Show view. | ||||
|
r14310 | if self.parent is None or self.parent._comm is None: | ||
self._comm.send({"method": "display", "view_name": view_name}) | ||||
|
r14223 | else: | ||
|
r14310 | self._comm.send({"method": "display", | ||
|
r14223 | "view_name": view_name, | ||
|
r14310 | "parent": self.parent._comm.comm_id}) | ||
self._displayed = True | ||||
|
r14387 | self._handle_displayed(view_name) | ||
|
r14310 | |||
|
r14278 | # Now display children if any. | ||
|
r14310 | for child in self._children: | ||
if child != self: | ||||
child._repr_widget_() | ||||
|
r14232 | return None | ||