widget.py
253 lines
| 8.7 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 | ||
|
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 | #----------------------------------------------------------------------------- | ||
# Shared | ||||
#----------------------------------------------------------------------------- | ||||
|
r14261 | def init_widget_js(): | ||
path = os.path.split(os.path.abspath( __file__ ))[0] | ||||
for filepath in glob(os.path.join(path, "*.py")): | ||||
filename = os.path.split(filepath)[1] | ||||
name = filename.rsplit('.', 1)[0] | ||||
|
r14267 | if not (name == 'widget' or name == '__init__') and name.startswith('widget_'): | ||
# Remove 'widget_' from the start of the name before compiling the path. | ||||
|
r14287 | js_path = '/static/notebook/js/widgets/%s.js' % name[7:] | ||
|
r14261 | display(Javascript(data='$.getScript("%s");' % js_path)) | ||
|
r14232 | |||
|
r14283 | #----------------------------------------------------------------------------- | ||
# Classes | ||||
#----------------------------------------------------------------------------- | ||||
|
r14232 | class Widget(LoggingConfigurable): | ||
|
r14223 | |||
|
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) | ||||
|
r14223 | |||
|
r14283 | # Private/protected declarations | ||
|
r14223 | _keys = [] | ||
_property_lock = False | ||||
_css = Dict() | ||||
|
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 = [] | ||
|
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.""" | ||||
|
r14310 | self._comm.close() | ||
del self._comm | ||||
|
r14223 | |||
|
r14310 | # Properties | ||
|
r14223 | def _get_keys(self): | ||
|
r14311 | keys = ['_css', 'visible'] | ||
|
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""" | ||
|
r14273 | # Handle backbone sync methods CREATE, PATCH, and UPDATE | ||
|
r14223 | sync_method = msg['content']['data']['sync_method'] | ||
sync_data = msg['content']['data']['sync_data'] | ||||
|
r14273 | self._handle_recieve_state(sync_data) # handles all methods | ||
|
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 | ||
|
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=""): | ||||
"""Get a CSS property of the widget views (shared among all of the | ||||
views) | ||||
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, key, value, selector=""): | ||||
"""Set a CSS property of the widget views (shared among all of the | ||||
views) | ||||
Parameters | ||||
---------- | ||||
key: unicode | ||||
CSS key | ||||
value | ||||
CSS value | ||||
selector: unicode (optional) | ||||
JQuery selector to use to apply the CSS key/value. | ||||
""" | ||||
if selector not in self._css: | ||||
self._css[selector] = {} | ||||
# Only update the property if it has changed. | ||||
if not (key in self._css[selector] and value in self._css[selector][key]): | ||||
self._css[selector][key] = value | ||||
self.send_state() # Send new state to client. | ||||
# 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 | ||||
|
r14278 | # Now display children if any. | ||
|
r14310 | for child in self._children: | ||
if child != self: | ||||
child._repr_widget_() | ||||
|
r14232 | return None | ||