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