1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 """A simple data object that contains one typed value."""
17
18
20 """The C{IProperty} is a simple data object that contains one typed value.
21 This interface contains methods to inspect and modify the stored value
22 and its type, and the object's read-only state.
23
24 The C{IProperty} also defines the events C{IReadOnlyStatusChangeEvent} and
25 C{ValueChangeEvent}, and the associated C{listener} and C{notifier}
26 interfaces.
27
28 The C{IViewer} interface should be used to attach the IProperty to an
29 external data source. This way the value in the data source can be
30 inspected using the C{IProperty} interface.
31
32 The C{IProperty.editor} interface should be implemented if the value
33 needs to be changed through the implementing class.
34
35 @author: Vaadin Ltd.
36 @author: Richard Lincoln
37 @version: 1.1.2
38 """
39
41 """Gets the value stored in the IProperty. The returned object is
42 compatible with the class returned by getType().
43
44 @return: the value stored in the IProperty
45 """
46 raise NotImplementedError
47
48
50 """Sets the value of the IProperty.
51
52 Implementing this functionality is optional. If the functionality is
53 missing, one should declare the IProperty to be in read-only mode and
54 throw C{ReadOnlyException} in this function.
55
56 Note: It is not required, but highly recommended to support setting the
57 value also as a C{String} in addition to the native type of the
58 IProperty (as given by the C{getType} method). If the
59 string conversion fails or is unsupported, the method should
60 throw C{ConversionException}. The string conversion
61 should at least understand the format returned by the
62 C{__str__} method of the IProperty.
63
64 @param newValue:
65 New value of the IProperty. This should be assignable to the
66 type returned by getType, but also String type should be
67 supported
68
69 @raise ReadOnlyException:
70 if the object is in read-only mode
71 @raise ConversionException:
72 if newValue can't be converted into the IProperty's native
73 type directly or through String
74 """
75 raise NotImplementedError
76
77
79 """Returns the value of the IProperty in human readable textual format.
80 The return value should be assignable to the C{setValue} method if
81 the IProperty is not in read-only mode.
82
83 @return: String representation of the value stored in the IProperty
84 """
85 raise NotImplementedError
86
87
89 """Returns the type of the IProperty. The methods C{getValue} and
90 C{setValue} must be compatible with this type: one must be able
91 to safely cast the value returned from C{getValue} to the given
92 type and pass any variable assignable to this type as an argument to
93 C{setValue}.
94
95 @return: type of the IProperty
96 """
97 raise NotImplementedError
98
99
101 """Tests if the IProperty is in read-only mode. In read-only mode calls
102 to the method C{setValue} will throw
103 C{ReadOnlyException} and will not modify the value of the
104 IProperty.
105
106 @return: C{True} if the IProperty is in read-only mode, C{False} if
107 it's not
108 """
109 raise NotImplementedError
110
111
113 """Sets the IProperty's read-only mode to the specified status.
114
115 This functionality is optional, but all properties must implement the
116 C{isReadOnly} mode query correctly.
117
118 @param newStatus:
119 new read-only status of the IProperty
120 """
121 raise NotImplementedError
122
123
125 """C{Exception} object that signals that a requested IProperty
126 modification failed because it's in read-only mode.
127
128 @author: Vaadin Ltd.
129 @author: Richard Lincoln
130 @version: 1.1.2
131 """
132
134 """Constructs a new C{ReadOnlyException} with the specified
135 detail message.
136
137 @param msg:
138 the detail message
139 """
140 if msg is not None:
141 super(ReadOnlyException, self).__init__(msg)
142
143
145 """An exception that signals that the value passed to the
146 C{setValue} method couldn't be converted to the native type of
147 the IProperty.
148
149 @author: Vaadin Ltd.
150 @version: 1.1.2
151 """
152
154 """Constructs a new C{ConversionException} with the specified
155 detail message and cause.
156
157 @param args: tuple of the form
158 - ()
159 - (msg)
160 1. the detail message
161 - (cause)
162 1. The cause of the the conversion failure
163 - (msg, cause)
164 1. the detail message
165 2. The cause of the the conversion failure
166 """
167 super(ConversionException, self).__init__(*args)
168
169
171 """Interface implemented by the viewer classes capable of using a IProperty
172 as a data source.
173
174 @author: Vaadin Ltd.
175 @author: Richard Lincoln
176 @version: 1.1.2
177 """
178
180 """Sets the IProperty that serves as the data source of the viewer.
181
182 @param newDataSource:
183 the new data source IProperty
184 """
185 raise NotImplementedError
186
187
189 """Gets the IProperty serving as the data source of the viewer.
190
191 @return: the IProperty serving as the viewers data source
192 """
193 raise NotImplementedError
194
195
197 """Interface implemented by the editor classes capable of editing the
198 IProperty.
199
200 Implementing this interface means that the IProperty serving as the data
201 source of the editor can be modified through the editor. It does not
202 restrict the editor from editing the IProperty internally, though if the
203 IProperty is in a read-only mode, attempts to modify it will result in the
204 C{ReadOnlyException} being thrown.
205
206 @author: Vaadin Ltd.
207 @author: Richard Lincoln
208 @version: 1.1.2
209 """
210 pass
211
212
214 """An C{Event} object specifying the IProperty whose value has been
215 changed.
216
217 @author: Vaadin Ltd.
218 @author: Richard Lincoln
219 @version: 1.1.2
220 """
221
223 """Retrieves the IProperty that has been modified.
224
225 @return: source IProperty of the event
226 """
227 raise NotImplementedError
228
229
231 """The C{listener} interface for receiving
232 C{ValueChangeEvent} objects.
233
234 @author: Vaadin Ltd.
235 @author: Richard Lincoln
236 @version: 1.1.2
237 """
238
240 """Notifies this listener that the IProperty's value has changed.
241
242 @param event:
243 value change event object
244 """
245 raise NotImplementedError
246
247
249 """The interface for adding and removing C{ValueChangeEvent}
250 listeners. If a IProperty wishes to allow other objects to receive
251 C{ValueChangeEvent} generated by it, it must implement this
252 interface.
253
254 @author: Vaadin Ltd.
255 @author: Richard Lincoln
256 @version: 1.1.2
257 """
258
260 """Registers a new value change listener for this IProperty.
261
262 @param listener:
263 the new Listener to be registered
264 """
265 raise NotImplementedError
266
267
268 - def addCallback(self, callback, eventType=None, *args):
269 raise NotImplementedError
270
271
273 """Removes a previously registered value change listener.
274
275 @param listener:
276 listener to be removed
277 """
278 raise NotImplementedError
279
280
282 raise NotImplementedError
283
284
286 """An C{Event} object specifying the IProperty whose read-only
287 status has been changed.
288
289 @author: Vaadin Ltd.
290 @author: Richard Lincoln
291 @version: 1.1.2
292 """
293
295 """IProperty whose read-only state has changed.
296
297 @return: source IProperty of the event.
298 """
299 raise NotImplementedError
300
301
303 """The listener interface for receiving C{IReadOnlyStatusChangeEvent}
304 objects.
305
306 @author: Vaadin Ltd.
307 @author: Richard Lincoln
308 @version: 1.1.2
309 """
310
312 """Notifies this listener that a IProperty's read-only status has
313 changed.
314
315 @param event:
316 Read-only status change event object
317 """
318 raise NotImplementedError
319
320
322 """The interface for adding and removing C{IReadOnlyStatusChangeEvent}
323 listeners. If a IProperty wishes to allow other objects to receive
324 C{IReadOnlyStatusChangeEvent} generated by it, it must implement this
325 interface.
326
327 @author: Vaadin Ltd.
328 @author: Richard Lincoln
329 @version: 1.1.2
330 """
331
333 """Registers a new read-only status change listener for this IProperty.
334
335 @param listener:
336 the new Listener to be registered
337 """
338 raise NotImplementedError
339
340
341 - def addCallback(self, callback, eventType=None, *args):
342 raise NotImplementedError
343
344
346 """Removes a previously registered read-only status change listener.
347
348 @param listener:
349 listener to be removed
350 """
351 raise NotImplementedError
352
353
355 raise NotImplementedError
356