1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
#
# Kiwi: a Framework and Enhanced Widgets for Python
#
# Copyright (C) 2002-2005 Async Open Source
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
# USA
#
# Author(s): Christian Reis <kiko@async.com.br>
# Lorenzo Gil Sanchez <lgs@sicem.biz>
# Gustavo Rahal <gustavo@async.com.br>
# Johan Dahlin <jdahlin@async.com.br>
#
"""This module defines the Proxy class, which is a facility that can be used
to keep the state of a model object synchronized with a View.
"""
import sys
from kiwi import _warn, ValueUnset
from kiwi.accessors import kgetattr, ksetattr, clear_attr_cache
from kiwi.interfaces import Mixin, MixinSupportValidation
def block_widget(widget):
"""Blocks the signal handler of the 'content-changed' signal on widget"""
connection_id = widget.get_data('content-changed-id')
if connection_id:
widget.handler_block(connection_id)
def unblock_widget(widget):
"""Unblocks the signal handler of the 'content-changed' signal on widget"""
connection_id = widget.get_data('content-changed-id')
if connection_id:
widget.handler_unblock(connection_id)
class Proxy:
""" A Proxy is a class that 'attaches' an instance to an interface's
widgets, and transparently manipulates that instance's attributes as
the user alters the content of the widgets.
The Proxy takes the widget list and detects what widgets are to be
attached to the model by looking if it is a KiwiWidget and if it
has the model-attribute set.
"""
_setter_error_handler = None
def __init__(self, view, model=None, widgets=[]):
self.view = view
self.model = model
self._setup_widgets(widgets)
self._initialize_widgets()
def _initialize_widgets(self):
"""Update the contents of the widgets.
This should be called after _setup_widgets.
"""
for attribute, widget in self._attr_map.items():
if self.model is None:
# if we have no model, leave value unset so we pick up
# the widget default below.
value = ValueUnset
else:
# if we have a model, grab its value to update the widgets
self._register_proxy_in_model(attribute)
value = kgetattr(self.model, attribute, ValueUnset)
if value is ValueUnset:
# get the default value from the widget if it has any
defvalue = widget.get_property('default-value')
if defvalue is not None:
value = defvalue
tweak_function = getattr(self, "tweak_%s" % attribute, None)
if tweak_function:
tweak_function(attribute, value)
else:
self.update(attribute, value, block=True)
# The initial value of the model is set, at this point
# do a read, it'll trigger a validation for widgets who
# supports it.
if not isinstance(widget, MixinSupportValidation):
continue
data = widget.read()
if data is not ValueUnset:
widget.validate_data(data, force=True)
def _setup_widgets(self, widgets):
"""
Connect to the 'content-changed' signal of all the Kiwi widgets
in the widgets list parameter.
@param widgets: the widget names
@type widgets: list of strings
"""
self._attr_map = {}
for widget_name in widgets:
widget = getattr(self.view, widget_name, None)
if widget is None:
raise AttributeError("The widget %s was not "
"found in the view %s" % (widget_name,
self.view))
if not isinstance(widget, Mixin):
continue
data_type = widget.get_property('data-type')
if data_type is None:
raise TypeError("The KiwiWidget %s should have a data type "
"set up" % widget)
attribute = widget.get_property('model-attribute')
if not attribute:
# we don't listen for changes in this widget because
# we don't know the model attribute
_warn("The widget %s (%s) is a KiwiWidget but does not have "
"a model attribute set so it will not be eassociated "
"with the model" % (widget, widget.name))
continue
connection_id = widget.connect('content-changed',
self._on_widget__content_changed,
attribute)
widget.set_data('content-changed-id', connection_id)
# save this widget in our map
self._attr_map[attribute] = widget
# here we define the view that owns the widget
widget.owner = self.view
def _on_widget__content_changed(self, widget, attribute):
"""This is called as soon as the content of one of the widget
changes, the widgets tries fairly hard to not emit when it's not
neccessary"""
# skip updates for model if there is none, right?
if self.model is None:
return
value = widget.read()
# only update the model if the data is correct
if value is ValueUnset:
return
if isinstance(widget, MixinSupportValidation):
value = widget.validate_data(value)
# XXX: one day we might want to queue and unique updates?
self._block_proxy_in_model(True)
try:
ksetattr(self.model, attribute, value)
except:
if self._setter_error_handler:
self._setter_error_handler(sys.exc_value, self.model,
attribute, value)
else:
raise
self._block_proxy_in_model(False)
# Call global update hook
self.proxy_updated(widget, value)
def _block_proxy_in_model(self, state):
model = self.model
if not hasattr(model, "block_proxy"):
return
if state:
model.block_proxy(self)
else:
model.unblock_proxy(self)
def _register_proxy_in_model(self, attribute):
model = self.model
if not hasattr(model, "register_proxy_for_attribute"):
return
try:
model.register_proxy_for_attribute(attribute, self)
except AttributeError:
msg = ("Failed to run register_proxy() on Model %s "
"(that was supplied to %s. \n"
"(Hint: if this model also inherits from ZODB's "
"Persistent class, this problem occurs if you haven't "
"set __setstate__() up correctly. __setstate__() "
"should call Model.__init__() (and "
"Persistent.__setstate__() of course) to reinitialize "
"things properly.)")
raise TypeError(msg % (model, self))
def _unregister_proxy_in_model(self):
if self.model and hasattr(self.model, "unregister_proxy"):
self.model.unregister_proxy(self)
# Public API
def proxy_updated(self, widgetproxy, value):
""" This is a hook that is called whenever the proxy updates the
model. Implement it in the inherited class to perform actions that
should be done each time the user changes something in the interface.
This hook by default does nothing.
"""
pass
def set_setter_error_handler(self, handler):
""" Sets a method that will be called if an update to a model
attribute raises an exception. The handler will receive the
following arguments, in order:
- Exception object
- model
- attribute name
- value attempted
"""
self._setter_error_handler = handler
def update(self, attribute, value=ValueUnset, block=False):
""" Generic frontend function to update the contentss of a widget based
on its model attribute name using the internal update functions.
- attribute: the name of the attribute whose widget we wish to
updated. If accessing a radiobutton, specify its group
name.
- value specifies the value to set in the widget. If
unspecified, it defaults to the current model's value
(through an accessor, if it exists, or getattr).
- block defines if we are to block cascading proxy updates
triggered by this update. You should use block if you are
calling update on *the same attribute that is currently
being updated*.
This means if you have hooked to a signal of the widget
associated to that attribute, and you call update() for
the *same attribute*, use block=True. And pray. 8). If
block is set to False, the normal update mechanism will
occur (the model being updated in the end, hopefully).
"""
if value is ValueUnset:
# We want to obtain a value from our model
if self.model is None:
# We really want to avoid trying to update our UI if our
# model doesn't exist yet and no value was provided.
# update() is also called by user code, but it should be
# safe to return here since you shouldn't need to code
# around the lack of a model in your callbacks if you
# can help it.
return
value = kgetattr(self.model, attribute, ValueUnset)
widget = self._attr_map.get(attribute, None)
if widget is None:
raise AttributeError("Called update for `%s', which isn't "
"attached to the proxy %s. Valid "
"attributes are: %s (you may have "
"forgetten to add `:' to the name in "
"the widgets list)"
% (attribute, self, self._attr_map.keys()))
# The type of value should match the data-type property. The two
# exceptions to this rule are ValueUnset and None
if not (value is ValueUnset or value is None):
data_type = widget.get_property('data-type')
value_type = type(value)
if not isinstance(value, data_type):
raise TypeError(
"attribute %s of model %r requires a value of "
"type %s, not %s" % (
attribute, self.model,
data_type.__name__,
value_type.__name__))
if block:
block_widget(widget)
self.view.handler_block(widget)
widget.update(value)
self.view.handler_unblock(widget)
unblock_widget(widget)
else:
widget.update(value)
return True
def notify(self, attribute, value=ValueUnset):
""" Notifies the proxy that the named attribute has changed. Calls
tweak_foo by default if the attribute provided is "foo" and update_foo
exists. This should *only* be called by the FrameWork Model, not by an
end-user callback.
- name: the name of the attribute being changed
- value: what it was set to
"""
func = getattr(self, "tweak_%s" % attribute, None)
if func:
# If value is unset, send in model value to tweak_%s
if value is ValueUnset:
value = kgetattr(self.model, attribute, ValueUnset)
if value is ValueUnset:
raise ValueError("model value for %s was unset" % attribute)
func(attribute, value)
else:
self.update(attribute, value, block=True)
def new_model(self, new_model, relax_type=False):
""" Reuses the same proxy with another instance as model. Allows a
proxy interface to change model without the need to destroy and
recreate the UI (which would cause flashing, at least)
"""
# unregister previous proxy
self._unregister_proxy_in_model()
# the following isn't strictly necessary, but it currently works
# around a bug with reused ids in the attribute cache and also
# makes a lot of sense for most applications (don't want a huge
# eternal cache pointing to models that you're not using anyway)
clear_attr_cache()
if self.model is not None:
assert self.model.__class__
if not relax_type and type(new_model) != type(self.model) and \
not isinstance(new_model, self.model.__class__):
raise TypeError("New model has wrong type %s, expected %s"
% (type(new_model), type(self.model)))
self.model = new_model
self._initialize_widgets()
|