Package muntjac :: Package data :: Module property
[hide private]
[frames] | no frames]

Source Code for Module muntjac.data.property

  1  # Copyright (C) 2012 Vaadin Ltd.  
  2  # Copyright (C) 2012 Richard Lincoln 
  3  #  
  4  # Licensed under the Apache License, Version 2.0 (the "License");  
  5  # you may not use this file except in compliance with the License.  
  6  # You may obtain a copy of the License at  
  7  #  
  8  #     http://www.apache.org/licenses/LICENSE-2.0  
  9  #  
 10  # Unless required by applicable law or agreed to in writing, software  
 11  # distributed under the License is distributed on an "AS IS" BASIS,  
 12  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
 13  # See the License for the specific language governing permissions and  
 14  # limitations under the License. 
 15   
 16  """A simple data object that contains one typed value.""" 
 17   
 18   
19 -class IProperty(object):
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
40 - def getValue(self):
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
49 - def setValue(self, newValue):
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
78 - def __str__(self):
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
88 - def getType(self):
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
100 - def isReadOnly(self):
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
112 - def setReadOnly(self, newStatus):
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
124 -class ReadOnlyException(RuntimeError):
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
133 - def __init__(self, msg=None):
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
144 -class ConversionException(RuntimeError):
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
153 - def __init__(self, *args):
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
170 -class IViewer(object):
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
179 - def setPropertyDataSource(self, newDataSource):
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
188 - def getPropertyDataSource(self):
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
196 -class IEditor(IViewer):
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
213 -class ValueChangeEvent(object):
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
222 - def getProperty(self):
223 """Retrieves the IProperty that has been modified. 224 225 @return: source IProperty of the event 226 """ 227 raise NotImplementedError
228 229
230 -class IValueChangeListener(object):
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
239 - def valueChange(self, event):
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
248 -class IValueChangeNotifier(object):
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
259 - def addListener(self, listener, iface=None):
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
272 - def removeListener(self, listener, iface=None):
273 """Removes a previously registered value change listener. 274 275 @param listener: 276 listener to be removed 277 """ 278 raise NotImplementedError
279 280
281 - def removeCallback(self, callback, eventType=None):
282 raise NotImplementedError
283 284
285 -class IReadOnlyStatusChangeEvent(object):
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
294 - def getProperty(self):
295 """IProperty whose read-only state has changed. 296 297 @return: source IProperty of the event. 298 """ 299 raise NotImplementedError
300 301
302 -class IReadOnlyStatusChangeListener(object):
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
311 - def readOnlyStatusChange(self, event):
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
321 -class IReadOnlyStatusChangeNotifier(object):
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
332 - def addListener(self, listener, iface=None):
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
345 - def removeListener(self, listener, iface=None):
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
354 - def removeCallback(self, callback, eventType=None):
355 raise NotImplementedError
356