1 """
2 PureMVC Python Port by Toby de Havilland <toby.de.havilland@puremvc.org>
3 PureMVC Python Port by Daniele Esposti <expo@expobrain.net>
4 PureMVC - Copyright(c) 2006-08 Futurescale, Inc., Some rights reserved.
5 Your reuse is governed by the Creative Commons Attribution 3.0 License
6 """
7
8 from puremvc import MultitonError
9 import puremvc.interfaces
10 import puremvc.patterns.facade
11
12
13 -class Observer(puremvc.interfaces.IObserver):
14 """
15 A base C{IObserver} implementation.
16
17 An C{Observer} is an object that encapsulates information
18 about an interested object with a method that should
19 be called when a particular C{INotification} is broadcast.
20
21 In PureMVC, the C{Observer} class assumes these responsibilities:
22
23 Encapsulate the notification (callback) method of the interested object.
24
25 Encapsulate the notification context (this) of the interested object.
26
27 Provide methods for setting the notification method and context.
28
29 Provide a method for notifying the interested object.
30
31 @see: L{View<puremvc.core.View>}
32 @see: L{Notification<puremvc.patterns.observer.Notification>}
33 """
34
35 - def __init__(self, notifyMethod, notifyContext):
36 """
37 Constructor.
38
39 The notification method on the interested object should take
40 one parameter of type C{INotification}
41
42 @param notifyMethod: the notification method of the interested object
43 @param notifyContext: the notification context of the interested object
44 """
45 self.notify = None
46 self.context = None
47
48 self.setNotifyMethod(notifyMethod)
49 self.setNotifyContext(notifyContext)
50
52 """
53 Set the notification method.
54
55 The notification method should take one parameter of type C{INotification}.
56
57 @param notifyMethod: the notification (callback) method of the interested object.
58 """
59 self.notify = notifyMethod
60
61 - def setNotifyContext(self, notifyContext):
62 """
63 Set the notification context.
64
65 @param notifyContext: the notification context (this) of the interested object.
66 """
67 self.context = notifyContext
68
70 """
71 Get the notification method.
72
73 @return: the notification (callback) method of the interested object.
74 """
75 return self.notify
76
78 """
79 Get the notification context.
80
81 @return: the notification context (C{this}) of the interested object.
82 """
83 return self.context
84
86 """
87 Notify the interested object.
88
89 @param notification: the C{INotification} to pass to the interested
90 object's notification method.
91 """
92 self.getNotifyMethod()(notification)
93
95 """
96 Compare an object to the notification context.
97
98 @param obj: the object to compare
99 @return: boolean indicating if the object and the notification context
100 are the same
101 """
102 return (obj is self.context)
103
104
105 -class Notifier(puremvc.interfaces.INotifier):
106 """
107 A Base C{INotifier} implementation.
108
109 C{MacroCommand, Command, Mediator} and C{Proxy}
110 all have a need to send C{Notifications}.
111
112 The C{INotifier} interface provides a common method called
113 C{sendNotification} that relieves implementation code of
114 the necessity to actually construct C{Notifications}.
115
116 The C{Notifier} class, which all of the above mentioned classes
117 extend, provides an initialized reference to the C{Facade}
118 Multiton, which is required for the convenience method
119 for sending C{Notifications}, but also eases implementation as these
120 classes have frequent C{Facade} interactions and usually require
121 access to the facade anyway.
122
123 NOTE: In the MultiCore version of the framework, there is one caveat to
124 notifiers, they cannot send notifications or reach the facade until they
125 have a valid multitonKey.
126
127 The multitonKey is set:
128
129 on a Command when it is executed by the Controller
130
131 on a Mediator is registered with the View
132
133 on a Proxy is registered with the Model.
134
135 @see: L{Proxy<puremvc.patterns.proxy.Proxy>}
136 @see: L{Facade<puremvc.patterns.facade.Facade>}
137 @see: L{Mediator<puremvc.patterns.mediator.Mediator>}
138 @see: L{MacroCommand<puremvc.patterns.command.MacroCommand>}
139 @see: L{SimpleCommand<puremvc.patterns.command.SimpleCommand>}
140 """
141
142 """Multiton error message"""
143 MULTITON_MSG = ("Notifier multiton instance for this key "
144 "is not yet initialised!")
145
147 """
148 Initialise the C{INotifier} instance with an empty multiton key
149 """
150 self.multitonKey = None
151
153 """
154 Create and send an C{INotification}.
155
156 Keeps us from having to construct new INotification instances in our
157 implementation code.
158
159
160 @param notificationName: the name of the notification to send
161 @param body: the body of the notification (optional)
162 @param noteType: the type of the notification (optional)
163 """
164 if self.facade:
165 self.facade.sendNotification(notificationName, body, noteType)
166
168 """
169 Initialize this INotifier instance.
170
171 This is how a Notifier gets its multitonKey. Calls to sendNotification
172 or to access the facade will fail until after this method has been
173 called.
174
175 Mediators, Commands or Proxies may override this method in order to
176 send notifications or access the Multiton Facade instance as soon as
177 possible. They CANNOT access the facade in their constructors, since
178 this method will not yet have been called.
179
180 @param key: the multitonKey for this INotifier to use
181 """
182 self.multitonKey = key
183
184 @property
195
198 """
199 A base C{INotification} implementation.
200
201 PureMVC does not rely upon underlying event models such
202 as the one provided with Flash, and ActionScript 3 does
203 not have an inherent event model.
204
205 The Observer Pattern as implemented within PureMVC exists
206 to support event-driven communication between the
207 application and the actors of the MVC triad.
208
209 Notifications are not meant to be a replacement for Events
210 in Flex/Flash/Apollo. Generally, C{IMediator} implementors
211 place event listeners on their view components, which they
212 then handle in the usual way. This may lead to the broadcast of C{Notification}s to
213 trigger C{ICommand}s or to communicate with other C{IMediators}. C{IProxy} and C{ICommand}
214 instances communicate with each other and C{IMediator}s
215 by broadcasting C{INotification}s.
216
217 A key difference between Flash C{Event}s and PureMVC
218 C{Notification}s is that C{Event}s follow the
219 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy
220 until some parent component handles the C{Event}, while
221 PureMVC C{Notification}s follow a 'Publish/Subscribe'
222 pattern. PureMVC classes need not be related to each other in a
223 parent/child relationship in order to communicate with one another
224 using C{Notification}s.
225
226 @see: L{Observer<puremvc.patterns.observer.Observer>}
227 """
228
229 - def __init__(self, name, body=None, noteType=None):
230 """
231 Constructor.
232
233 @param name: name of the C{Notification} instance. (required)
234 @param body: the C{Notification} body. (optional)
235 @param noteType: the type of the C{Notification} (optional)
236 """
237
238 """The name of the notification instance"""
239 self.name = name
240
241 """The body of the notification instance"""
242 self.body = body
243
244 """The type of the notification instance"""
245 self.type = noteType
246
248 """
249 Get the string representation of the C{Notification} instance.
250
251 @return: the string representation of the C{Notification} instance.
252 """
253 bd = "None" if self.body is None else repr(self.body)
254 ty = "None" if self.type is None else repr(self.type)
255
256 msg = "Notification Name: " + self.name
257 msg += "\nBody:"+bd
258 msg += "\nType:"+ty
259
260 return msg
261
263 """
264 Get the name of the C{Notification} instance.
265
266 @return: the name of the C{Notification} instance.
267 """
268 return self.name
269
270 - def setBody(self, body):
271 """
272 Set the body of the C{Notification} instance.
273 """
274 self.body = body
275
277 """
278 Get the body of the C{Notification} instance.
279
280 @return: the body object.
281 """
282 return self.body
283
284 - def setType(self, notificationType):
285 """
286 Set the type of the C{Notification} instance.
287 """
288 self.type = notificationType
289
291 """
292 Get the type of the C{Notification} instance.
293
294 @return: the type
295 """
296 return self.type
297