##// END OF EJS Templates
Explicit 2.5px
Jonathan Frederic -
Show More
@@ -1,481 +1,482 b''
1 """Base Widget class. Allows user to create widgets in the back-end that render
1 """Base Widget class. Allows user to create widgets in the back-end that render
2 in the IPython notebook front-end.
2 in the IPython notebook front-end.
3 """
3 """
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (c) 2013, the IPython Development Team.
5 # Copyright (c) 2013, the IPython Development Team.
6 #
6 #
7 # Distributed under the terms of the Modified BSD License.
7 # Distributed under the terms of the Modified BSD License.
8 #
8 #
9 # The full license is in the file COPYING.txt, distributed with this software.
9 # The full license is in the file COPYING.txt, distributed with this software.
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Imports
13 # Imports
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 from contextlib import contextmanager
15 from contextlib import contextmanager
16 import collections
16 import collections
17
17
18 from IPython.core.getipython import get_ipython
18 from IPython.core.getipython import get_ipython
19 from IPython.kernel.comm import Comm
19 from IPython.kernel.comm import Comm
20 from IPython.config import LoggingConfigurable
20 from IPython.config import LoggingConfigurable
21 from IPython.utils.importstring import import_item
21 from IPython.utils.importstring import import_item
22 from IPython.utils.traitlets import Unicode, Dict, Instance, Bool, List, \
22 from IPython.utils.traitlets import Unicode, Dict, Instance, Bool, List, \
23 CaselessStrEnum, Tuple, CUnicode, Int, Set
23 CaselessStrEnum, Tuple, CUnicode, Int, Set
24 from IPython.utils.py3compat import string_types
24 from IPython.utils.py3compat import string_types
25
25
26 #-----------------------------------------------------------------------------
26 #-----------------------------------------------------------------------------
27 # Classes
27 # Classes
28 #-----------------------------------------------------------------------------
28 #-----------------------------------------------------------------------------
29 class CallbackDispatcher(LoggingConfigurable):
29 class CallbackDispatcher(LoggingConfigurable):
30 """A structure for registering and running callbacks"""
30 """A structure for registering and running callbacks"""
31 callbacks = List()
31 callbacks = List()
32
32
33 def __call__(self, *args, **kwargs):
33 def __call__(self, *args, **kwargs):
34 """Call all of the registered callbacks."""
34 """Call all of the registered callbacks."""
35 value = None
35 value = None
36 for callback in self.callbacks:
36 for callback in self.callbacks:
37 try:
37 try:
38 local_value = callback(*args, **kwargs)
38 local_value = callback(*args, **kwargs)
39 except Exception as e:
39 except Exception as e:
40 ip = get_ipython()
40 ip = get_ipython()
41 if ip is None:
41 if ip is None:
42 self.log.warn("Exception in callback %s: %s", callback, e, exc_info=True)
42 self.log.warn("Exception in callback %s: %s", callback, e, exc_info=True)
43 else:
43 else:
44 ip.showtraceback()
44 ip.showtraceback()
45 else:
45 else:
46 value = local_value if local_value is not None else value
46 value = local_value if local_value is not None else value
47 return value
47 return value
48
48
49 def register_callback(self, callback, remove=False):
49 def register_callback(self, callback, remove=False):
50 """(Un)Register a callback
50 """(Un)Register a callback
51
51
52 Parameters
52 Parameters
53 ----------
53 ----------
54 callback: method handle
54 callback: method handle
55 Method to be registered or unregistered.
55 Method to be registered or unregistered.
56 remove=False: bool
56 remove=False: bool
57 Whether to unregister the callback."""
57 Whether to unregister the callback."""
58
58
59 # (Un)Register the callback.
59 # (Un)Register the callback.
60 if remove and callback in self.callbacks:
60 if remove and callback in self.callbacks:
61 self.callbacks.remove(callback)
61 self.callbacks.remove(callback)
62 elif not remove and callback not in self.callbacks:
62 elif not remove and callback not in self.callbacks:
63 self.callbacks.append(callback)
63 self.callbacks.append(callback)
64
64
65 def _show_traceback(method):
65 def _show_traceback(method):
66 """decorator for showing tracebacks in IPython"""
66 """decorator for showing tracebacks in IPython"""
67 def m(self, *args, **kwargs):
67 def m(self, *args, **kwargs):
68 try:
68 try:
69 return(method(self, *args, **kwargs))
69 return(method(self, *args, **kwargs))
70 except Exception as e:
70 except Exception as e:
71 ip = get_ipython()
71 ip = get_ipython()
72 if ip is None:
72 if ip is None:
73 self.log.warn("Exception in widget method %s: %s", method, e, exc_info=True)
73 self.log.warn("Exception in widget method %s: %s", method, e, exc_info=True)
74 else:
74 else:
75 ip.showtraceback()
75 ip.showtraceback()
76 return m
76 return m
77
77
78
78
79 def register(key=None):
79 def register(key=None):
80 """Returns a decorator registering a widget class in the widget registry.
80 """Returns a decorator registering a widget class in the widget registry.
81 If no key is provided, the class name is used as a key. A key is
81 If no key is provided, the class name is used as a key. A key is
82 provided for each core IPython widget so that the frontend can use
82 provided for each core IPython widget so that the frontend can use
83 this key regardless of the language of the kernel"""
83 this key regardless of the language of the kernel"""
84 def wrap(widget):
84 def wrap(widget):
85 l = key if key is not None else widget.__module__ + widget.__name__
85 l = key if key is not None else widget.__module__ + widget.__name__
86 Widget.widget_types[l] = widget
86 Widget.widget_types[l] = widget
87 return widget
87 return widget
88 return wrap
88 return wrap
89
89
90
90
91 class Widget(LoggingConfigurable):
91 class Widget(LoggingConfigurable):
92 #-------------------------------------------------------------------------
92 #-------------------------------------------------------------------------
93 # Class attributes
93 # Class attributes
94 #-------------------------------------------------------------------------
94 #-------------------------------------------------------------------------
95 _widget_construction_callback = None
95 _widget_construction_callback = None
96 widgets = {}
96 widgets = {}
97 widget_types = {}
97 widget_types = {}
98
98
99 @staticmethod
99 @staticmethod
100 def on_widget_constructed(callback):
100 def on_widget_constructed(callback):
101 """Registers a callback to be called when a widget is constructed.
101 """Registers a callback to be called when a widget is constructed.
102
102
103 The callback must have the following signature:
103 The callback must have the following signature:
104 callback(widget)"""
104 callback(widget)"""
105 Widget._widget_construction_callback = callback
105 Widget._widget_construction_callback = callback
106
106
107 @staticmethod
107 @staticmethod
108 def _call_widget_constructed(widget):
108 def _call_widget_constructed(widget):
109 """Static method, called when a widget is constructed."""
109 """Static method, called when a widget is constructed."""
110 if Widget._widget_construction_callback is not None and callable(Widget._widget_construction_callback):
110 if Widget._widget_construction_callback is not None and callable(Widget._widget_construction_callback):
111 Widget._widget_construction_callback(widget)
111 Widget._widget_construction_callback(widget)
112
112
113 @staticmethod
113 @staticmethod
114 def handle_comm_opened(comm, msg):
114 def handle_comm_opened(comm, msg):
115 """Static method, called when a widget is constructed."""
115 """Static method, called when a widget is constructed."""
116 widget_class = import_item(msg['content']['data']['widget_class'])
116 widget_class = import_item(msg['content']['data']['widget_class'])
117 widget = widget_class(comm=comm)
117 widget = widget_class(comm=comm)
118
118
119
119
120 #-------------------------------------------------------------------------
120 #-------------------------------------------------------------------------
121 # Traits
121 # Traits
122 #-------------------------------------------------------------------------
122 #-------------------------------------------------------------------------
123 _model_module = Unicode(None, allow_none=True, help="""A requirejs module name
123 _model_module = Unicode(None, allow_none=True, help="""A requirejs module name
124 in which to find _model_name. If empty, look in the global registry.""")
124 in which to find _model_name. If empty, look in the global registry.""")
125 _model_name = Unicode('WidgetModel', help="""Name of the backbone model
125 _model_name = Unicode('WidgetModel', help="""Name of the backbone model
126 registered in the front-end to create and sync this widget with.""")
126 registered in the front-end to create and sync this widget with.""")
127 _view_module = Unicode(help="""A requirejs module in which to find _view_name.
127 _view_module = Unicode(help="""A requirejs module in which to find _view_name.
128 If empty, look in the global registry.""", sync=True)
128 If empty, look in the global registry.""", sync=True)
129 _view_name = Unicode(None, allow_none=True, help="""Default view registered in the front-end
129 _view_name = Unicode(None, allow_none=True, help="""Default view registered in the front-end
130 to use to represent the widget.""", sync=True)
130 to use to represent the widget.""", sync=True)
131 comm = Instance('IPython.kernel.comm.Comm')
131 comm = Instance('IPython.kernel.comm.Comm')
132
132
133 msg_throttle = Int(3, sync=True, help="""Maximum number of msgs the
133 msg_throttle = Int(3, sync=True, help="""Maximum number of msgs the
134 front-end can send before receiving an idle msg from the back-end.""")
134 front-end can send before receiving an idle msg from the back-end.""")
135
135
136 version = Int(0, sync=True, help="""Widget's version""")
136 version = Int(0, sync=True, help="""Widget's version""")
137 keys = List()
137 keys = List()
138 def _keys_default(self):
138 def _keys_default(self):
139 return [name for name in self.traits(sync=True)]
139 return [name for name in self.traits(sync=True)]
140
140
141 _property_lock = Tuple((None, None))
141 _property_lock = Tuple((None, None))
142 _send_state_lock = Int(0)
142 _send_state_lock = Int(0)
143 _states_to_send = Set(allow_none=False)
143 _states_to_send = Set(allow_none=False)
144 _display_callbacks = Instance(CallbackDispatcher, ())
144 _display_callbacks = Instance(CallbackDispatcher, ())
145 _msg_callbacks = Instance(CallbackDispatcher, ())
145 _msg_callbacks = Instance(CallbackDispatcher, ())
146
146
147 #-------------------------------------------------------------------------
147 #-------------------------------------------------------------------------
148 # (Con/de)structor
148 # (Con/de)structor
149 #-------------------------------------------------------------------------
149 #-------------------------------------------------------------------------
150 def __init__(self, **kwargs):
150 def __init__(self, **kwargs):
151 """Public constructor"""
151 """Public constructor"""
152 self._model_id = kwargs.pop('model_id', None)
152 self._model_id = kwargs.pop('model_id', None)
153 super(Widget, self).__init__(**kwargs)
153 super(Widget, self).__init__(**kwargs)
154
154
155 Widget._call_widget_constructed(self)
155 Widget._call_widget_constructed(self)
156 self.open()
156 self.open()
157
157
158 def __del__(self):
158 def __del__(self):
159 """Object disposal"""
159 """Object disposal"""
160 self.close()
160 self.close()
161
161
162 #-------------------------------------------------------------------------
162 #-------------------------------------------------------------------------
163 # Properties
163 # Properties
164 #-------------------------------------------------------------------------
164 #-------------------------------------------------------------------------
165
165
166 def open(self):
166 def open(self):
167 """Open a comm to the frontend if one isn't already open."""
167 """Open a comm to the frontend if one isn't already open."""
168 if self.comm is None:
168 if self.comm is None:
169 args = dict(target_name='ipython.widget',
169 args = dict(target_name='ipython.widget',
170 data={'model_name': self._model_name,
170 data={'model_name': self._model_name,
171 'model_module': self._model_module})
171 'model_module': self._model_module})
172 if self._model_id is not None:
172 if self._model_id is not None:
173 args['comm_id'] = self._model_id
173 args['comm_id'] = self._model_id
174 self.comm = Comm(**args)
174 self.comm = Comm(**args)
175
175
176 def _comm_changed(self, name, new):
176 def _comm_changed(self, name, new):
177 """Called when the comm is changed."""
177 """Called when the comm is changed."""
178 if new is None:
178 if new is None:
179 return
179 return
180 self._model_id = self.model_id
180 self._model_id = self.model_id
181
181
182 self.comm.on_msg(self._handle_msg)
182 self.comm.on_msg(self._handle_msg)
183 Widget.widgets[self.model_id] = self
183 Widget.widgets[self.model_id] = self
184
184
185 # first update
185 # first update
186 self.send_state()
186 self.send_state()
187
187
188 @property
188 @property
189 def model_id(self):
189 def model_id(self):
190 """Gets the model id of this widget.
190 """Gets the model id of this widget.
191
191
192 If a Comm doesn't exist yet, a Comm will be created automagically."""
192 If a Comm doesn't exist yet, a Comm will be created automagically."""
193 return self.comm.comm_id
193 return self.comm.comm_id
194
194
195 #-------------------------------------------------------------------------
195 #-------------------------------------------------------------------------
196 # Methods
196 # Methods
197 #-------------------------------------------------------------------------
197 #-------------------------------------------------------------------------
198
198
199 def close(self):
199 def close(self):
200 """Close method.
200 """Close method.
201
201
202 Closes the underlying comm.
202 Closes the underlying comm.
203 When the comm is closed, all of the widget views are automatically
203 When the comm is closed, all of the widget views are automatically
204 removed from the front-end."""
204 removed from the front-end."""
205 if self.comm is not None:
205 if self.comm is not None:
206 Widget.widgets.pop(self.model_id, None)
206 Widget.widgets.pop(self.model_id, None)
207 self.comm.close()
207 self.comm.close()
208 self.comm = None
208 self.comm = None
209
209
210 def send_state(self, key=None):
210 def send_state(self, key=None):
211 """Sends the widget state, or a piece of it, to the front-end.
211 """Sends the widget state, or a piece of it, to the front-end.
212
212
213 Parameters
213 Parameters
214 ----------
214 ----------
215 key : unicode, or iterable (optional)
215 key : unicode, or iterable (optional)
216 A single property's name or iterable of property names to sync with the front-end.
216 A single property's name or iterable of property names to sync with the front-end.
217 """
217 """
218 self._send({
218 self._send({
219 "method" : "update",
219 "method" : "update",
220 "state" : self.get_state(key=key)
220 "state" : self.get_state(key=key)
221 })
221 })
222
222
223 def get_state(self, key=None):
223 def get_state(self, key=None):
224 """Gets the widget state, or a piece of it.
224 """Gets the widget state, or a piece of it.
225
225
226 Parameters
226 Parameters
227 ----------
227 ----------
228 key : unicode or iterable (optional)
228 key : unicode or iterable (optional)
229 A single property's name or iterable of property names to get.
229 A single property's name or iterable of property names to get.
230 """
230 """
231 if key is None:
231 if key is None:
232 keys = self.keys
232 keys = self.keys
233 elif isinstance(key, string_types):
233 elif isinstance(key, string_types):
234 keys = [key]
234 keys = [key]
235 elif isinstance(key, collections.Iterable):
235 elif isinstance(key, collections.Iterable):
236 keys = key
236 keys = key
237 else:
237 else:
238 raise ValueError("key must be a string, an iterable of keys, or None")
238 raise ValueError("key must be a string, an iterable of keys, or None")
239 state = {}
239 state = {}
240 for k in keys:
240 for k in keys:
241 f = self.trait_metadata(k, 'to_json', self._trait_to_json)
241 f = self.trait_metadata(k, 'to_json', self._trait_to_json)
242 value = getattr(self, k)
242 value = getattr(self, k)
243 state[k] = f(value)
243 state[k] = f(value)
244 return state
244 return state
245
245
246 def set_state(self, sync_data):
246 def set_state(self, sync_data):
247 """Called when a state is received from the front-end."""
247 """Called when a state is received from the front-end."""
248 for name in self.keys:
248 for name in self.keys:
249 if name in sync_data:
249 if name in sync_data:
250 json_value = sync_data[name]
250 json_value = sync_data[name]
251 from_json = self.trait_metadata(name, 'from_json', self._trait_from_json)
251 from_json = self.trait_metadata(name, 'from_json', self._trait_from_json)
252 with self._lock_property(name, json_value):
252 with self._lock_property(name, json_value):
253 setattr(self, name, from_json(json_value))
253 setattr(self, name, from_json(json_value))
254
254
255 def send(self, content):
255 def send(self, content):
256 """Sends a custom msg to the widget model in the front-end.
256 """Sends a custom msg to the widget model in the front-end.
257
257
258 Parameters
258 Parameters
259 ----------
259 ----------
260 content : dict
260 content : dict
261 Content of the message to send.
261 Content of the message to send.
262 """
262 """
263 self._send({"method": "custom", "content": content})
263 self._send({"method": "custom", "content": content})
264
264
265 def on_msg(self, callback, remove=False):
265 def on_msg(self, callback, remove=False):
266 """(Un)Register a custom msg receive callback.
266 """(Un)Register a custom msg receive callback.
267
267
268 Parameters
268 Parameters
269 ----------
269 ----------
270 callback: callable
270 callback: callable
271 callback will be passed two arguments when a message arrives::
271 callback will be passed two arguments when a message arrives::
272
272
273 callback(widget, content)
273 callback(widget, content)
274
274
275 remove: bool
275 remove: bool
276 True if the callback should be unregistered."""
276 True if the callback should be unregistered."""
277 self._msg_callbacks.register_callback(callback, remove=remove)
277 self._msg_callbacks.register_callback(callback, remove=remove)
278
278
279 def on_displayed(self, callback, remove=False):
279 def on_displayed(self, callback, remove=False):
280 """(Un)Register a widget displayed callback.
280 """(Un)Register a widget displayed callback.
281
281
282 Parameters
282 Parameters
283 ----------
283 ----------
284 callback: method handler
284 callback: method handler
285 Must have a signature of::
285 Must have a signature of::
286
286
287 callback(widget, **kwargs)
287 callback(widget, **kwargs)
288
288
289 kwargs from display are passed through without modification.
289 kwargs from display are passed through without modification.
290 remove: bool
290 remove: bool
291 True if the callback should be unregistered."""
291 True if the callback should be unregistered."""
292 self._display_callbacks.register_callback(callback, remove=remove)
292 self._display_callbacks.register_callback(callback, remove=remove)
293
293
294 #-------------------------------------------------------------------------
294 #-------------------------------------------------------------------------
295 # Support methods
295 # Support methods
296 #-------------------------------------------------------------------------
296 #-------------------------------------------------------------------------
297 @contextmanager
297 @contextmanager
298 def _lock_property(self, key, value):
298 def _lock_property(self, key, value):
299 """Lock a property-value pair.
299 """Lock a property-value pair.
300
300
301 The value should be the JSON state of the property.
301 The value should be the JSON state of the property.
302
302
303 NOTE: This, in addition to the single lock for all state changes, is
303 NOTE: This, in addition to the single lock for all state changes, is
304 flawed. In the future we may want to look into buffering state changes
304 flawed. In the future we may want to look into buffering state changes
305 back to the front-end."""
305 back to the front-end."""
306 self._property_lock = (key, value)
306 self._property_lock = (key, value)
307 try:
307 try:
308 yield
308 yield
309 finally:
309 finally:
310 self._property_lock = (None, None)
310 self._property_lock = (None, None)
311
311
312 @contextmanager
312 @contextmanager
313 def hold_sync(self):
313 def hold_sync(self):
314 """Hold syncing any state until the context manager is released"""
314 """Hold syncing any state until the context manager is released"""
315 # We increment a value so that this can be nested. Syncing will happen when
315 # We increment a value so that this can be nested. Syncing will happen when
316 # all levels have been released.
316 # all levels have been released.
317 self._send_state_lock += 1
317 self._send_state_lock += 1
318 try:
318 try:
319 yield
319 yield
320 finally:
320 finally:
321 self._send_state_lock -=1
321 self._send_state_lock -=1
322 if self._send_state_lock == 0:
322 if self._send_state_lock == 0:
323 self.send_state(self._states_to_send)
323 self.send_state(self._states_to_send)
324 self._states_to_send.clear()
324 self._states_to_send.clear()
325
325
326 def _should_send_property(self, key, value):
326 def _should_send_property(self, key, value):
327 """Check the property lock (property_lock)"""
327 """Check the property lock (property_lock)"""
328 to_json = self.trait_metadata(key, 'to_json', self._trait_to_json)
328 to_json = self.trait_metadata(key, 'to_json', self._trait_to_json)
329 if (key == self._property_lock[0]
329 if (key == self._property_lock[0]
330 and to_json(value) == self._property_lock[1]):
330 and to_json(value) == self._property_lock[1]):
331 return False
331 return False
332 elif self._send_state_lock > 0:
332 elif self._send_state_lock > 0:
333 self._states_to_send.add(key)
333 self._states_to_send.add(key)
334 return False
334 return False
335 else:
335 else:
336 return True
336 return True
337
337
338 # Event handlers
338 # Event handlers
339 @_show_traceback
339 @_show_traceback
340 def _handle_msg(self, msg):
340 def _handle_msg(self, msg):
341 """Called when a msg is received from the front-end"""
341 """Called when a msg is received from the front-end"""
342 data = msg['content']['data']
342 data = msg['content']['data']
343 method = data['method']
343 method = data['method']
344 if not method in ['backbone', 'custom']:
344 if not method in ['backbone', 'custom']:
345 self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
345 self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
346
346
347 # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one.
347 # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one.
348 if method == 'backbone' and 'sync_data' in data:
348 if method == 'backbone' and 'sync_data' in data:
349 sync_data = data['sync_data']
349 sync_data = data['sync_data']
350 self.set_state(sync_data) # handles all methods
350 self.set_state(sync_data) # handles all methods
351
351
352 # Handle a custom msg from the front-end
352 # Handle a custom msg from the front-end
353 elif method == 'custom':
353 elif method == 'custom':
354 if 'content' in data:
354 if 'content' in data:
355 self._handle_custom_msg(data['content'])
355 self._handle_custom_msg(data['content'])
356
356
357 def _handle_custom_msg(self, content):
357 def _handle_custom_msg(self, content):
358 """Called when a custom msg is received."""
358 """Called when a custom msg is received."""
359 self._msg_callbacks(self, content)
359 self._msg_callbacks(self, content)
360
360
361 def _notify_trait(self, name, old_value, new_value):
361 def _notify_trait(self, name, old_value, new_value):
362 """Called when a property has been changed."""
362 """Called when a property has been changed."""
363 # Trigger default traitlet callback machinery. This allows any user
363 # Trigger default traitlet callback machinery. This allows any user
364 # registered validation to be processed prior to allowing the widget
364 # registered validation to be processed prior to allowing the widget
365 # machinery to handle the state.
365 # machinery to handle the state.
366 LoggingConfigurable._notify_trait(self, name, old_value, new_value)
366 LoggingConfigurable._notify_trait(self, name, old_value, new_value)
367
367
368 # Send the state after the user registered callbacks for trait changes
368 # Send the state after the user registered callbacks for trait changes
369 # have all fired (allows for user to validate values).
369 # have all fired (allows for user to validate values).
370 if self.comm is not None and name in self.keys:
370 if self.comm is not None and name in self.keys:
371 # Make sure this isn't information that the front-end just sent us.
371 # Make sure this isn't information that the front-end just sent us.
372 if self._should_send_property(name, new_value):
372 if self._should_send_property(name, new_value):
373 # Send new state to front-end
373 # Send new state to front-end
374 self.send_state(key=name)
374 self.send_state(key=name)
375
375
376 def _handle_displayed(self, **kwargs):
376 def _handle_displayed(self, **kwargs):
377 """Called when a view has been displayed for this widget instance"""
377 """Called when a view has been displayed for this widget instance"""
378 self._display_callbacks(self, **kwargs)
378 self._display_callbacks(self, **kwargs)
379
379
380 def _trait_to_json(self, x):
380 def _trait_to_json(self, x):
381 """Convert a trait value to json
381 """Convert a trait value to json
382
382
383 Traverse lists/tuples and dicts and serialize their values as well.
383 Traverse lists/tuples and dicts and serialize their values as well.
384 Replace any widgets with their model_id
384 Replace any widgets with their model_id
385 """
385 """
386 if isinstance(x, dict):
386 if isinstance(x, dict):
387 return {k: self._trait_to_json(v) for k, v in x.items()}
387 return {k: self._trait_to_json(v) for k, v in x.items()}
388 elif isinstance(x, (list, tuple)):
388 elif isinstance(x, (list, tuple)):
389 return [self._trait_to_json(v) for v in x]
389 return [self._trait_to_json(v) for v in x]
390 elif isinstance(x, Widget):
390 elif isinstance(x, Widget):
391 return "IPY_MODEL_" + x.model_id
391 return "IPY_MODEL_" + x.model_id
392 else:
392 else:
393 return x # Value must be JSON-able
393 return x # Value must be JSON-able
394
394
395 def _trait_from_json(self, x):
395 def _trait_from_json(self, x):
396 """Convert json values to objects
396 """Convert json values to objects
397
397
398 Replace any strings representing valid model id values to Widget references.
398 Replace any strings representing valid model id values to Widget references.
399 """
399 """
400 if isinstance(x, dict):
400 if isinstance(x, dict):
401 return {k: self._trait_from_json(v) for k, v in x.items()}
401 return {k: self._trait_from_json(v) for k, v in x.items()}
402 elif isinstance(x, (list, tuple)):
402 elif isinstance(x, (list, tuple)):
403 return [self._trait_from_json(v) for v in x]
403 return [self._trait_from_json(v) for v in x]
404 elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
404 elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
405 # we want to support having child widgets at any level in a hierarchy
405 # we want to support having child widgets at any level in a hierarchy
406 # trusting that a widget UUID will not appear out in the wild
406 # trusting that a widget UUID will not appear out in the wild
407 return Widget.widgets[x[10:]]
407 return Widget.widgets[x[10:]]
408 else:
408 else:
409 return x
409 return x
410
410
411 def _ipython_display_(self, **kwargs):
411 def _ipython_display_(self, **kwargs):
412 """Called when `IPython.display.display` is called on the widget."""
412 """Called when `IPython.display.display` is called on the widget."""
413 # Show view.
413 # Show view.
414 if self._view_name is not None:
414 if self._view_name is not None:
415 self._send({"method": "display"})
415 self._send({"method": "display"})
416 self._handle_displayed(**kwargs)
416 self._handle_displayed(**kwargs)
417
417
418 def _send(self, msg):
418 def _send(self, msg):
419 """Sends a message to the model in the front-end."""
419 """Sends a message to the model in the front-end."""
420 self.comm.send(msg)
420 self.comm.send(msg)
421
421
422
422
423 class DOMWidget(Widget):
423 class DOMWidget(Widget):
424 visible = Bool(True, help="Whether the widget is visible.", sync=True)
424 visible = Bool(True, help="Whether the widget is visible.", sync=True)
425 _css = Tuple(sync=True, help="CSS property list: (selector, key, value)")
425 _css = Tuple(sync=True, help="CSS property list: (selector, key, value)")
426 _dom_classes = Tuple(sync=True, help="DOM classes applied to widget.$el.")
426 _dom_classes = Tuple(sync=True, help="DOM classes applied to widget.$el.")
427
427
428 width = CUnicode(sync=True)
428 width = CUnicode(sync=True)
429 height = CUnicode(sync=True)
429 height = CUnicode(sync=True)
430 padding = CUnicode(2.5, sync=True)
430 # A default padding of 2.5 px makes the widgets look nice when displayed inline.
431 padding = CUnicode("2.5px", sync=True)
431 margin = CUnicode(sync=True)
432 margin = CUnicode(sync=True)
432
433
433 color = Unicode(sync=True)
434 color = Unicode(sync=True)
434 background_color = Unicode(sync=True)
435 background_color = Unicode(sync=True)
435 border_color = Unicode(sync=True)
436 border_color = Unicode(sync=True)
436
437
437 border_width = CUnicode(sync=True)
438 border_width = CUnicode(sync=True)
438 border_radius = CUnicode(sync=True)
439 border_radius = CUnicode(sync=True)
439 border_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_border-style.asp
440 border_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_border-style.asp
440 'none',
441 'none',
441 'hidden',
442 'hidden',
442 'dotted',
443 'dotted',
443 'dashed',
444 'dashed',
444 'solid',
445 'solid',
445 'double',
446 'double',
446 'groove',
447 'groove',
447 'ridge',
448 'ridge',
448 'inset',
449 'inset',
449 'outset',
450 'outset',
450 'initial',
451 'initial',
451 'inherit', ''],
452 'inherit', ''],
452 default_value='', sync=True)
453 default_value='', sync=True)
453
454
454 font_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_font-style.asp
455 font_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_font-style.asp
455 'normal',
456 'normal',
456 'italic',
457 'italic',
457 'oblique',
458 'oblique',
458 'initial',
459 'initial',
459 'inherit', ''],
460 'inherit', ''],
460 default_value='', sync=True)
461 default_value='', sync=True)
461 font_weight = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_weight.asp
462 font_weight = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_weight.asp
462 'normal',
463 'normal',
463 'bold',
464 'bold',
464 'bolder',
465 'bolder',
465 'lighter',
466 'lighter',
466 'initial',
467 'initial',
467 'inherit', ''] + [str(100 * (i+1)) for i in range(9)],
468 'inherit', ''] + [str(100 * (i+1)) for i in range(9)],
468 default_value='', sync=True)
469 default_value='', sync=True)
469 font_size = CUnicode(sync=True)
470 font_size = CUnicode(sync=True)
470 font_family = Unicode(sync=True)
471 font_family = Unicode(sync=True)
471
472
472 def __init__(self, *pargs, **kwargs):
473 def __init__(self, *pargs, **kwargs):
473 super(DOMWidget, self).__init__(*pargs, **kwargs)
474 super(DOMWidget, self).__init__(*pargs, **kwargs)
474
475
475 def _validate_border(name, old, new):
476 def _validate_border(name, old, new):
476 if new is not None and new != '':
477 if new is not None and new != '':
477 if name != 'border_width' and not self.border_width:
478 if name != 'border_width' and not self.border_width:
478 self.border_width = 1
479 self.border_width = 1
479 if name != 'border_style' and self.border_style == '':
480 if name != 'border_style' and self.border_style == '':
480 self.border_style = 'solid'
481 self.border_style = 'solid'
481 self.on_trait_change(_validate_border, ['border_width', 'border_style', 'border_color'])
482 self.on_trait_change(_validate_border, ['border_width', 'border_style', 'border_color'])
General Comments 0
You need to be logged in to leave comments. Login now