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
10 """
11 The interface definition for a PureMVC Notifier.
12
13 C{MacroCommand, Command, Mediator} and C{Proxy}
14 all have a need to send C{Notifications}.
15
16 The C{INotifier} interface provides a common method called
17 C{sendNotification} that relieves implementation code of
18 the necessity to actually construct C{Notifications}.
19
20 The C{Notifier} class, which all of the above mentioned classes
21 extend, also provides an initialized reference to the C{Facade}
22 Singleton, which is required for the convienience method
23 for sending C{Notifications}, but also eases implementation as these
24 classes have frequent C{Facade} interactions and usually require
25 access to the facade anyway.
26
27 @see: L{IFacade<puremvc.interfaces.IFacade>}
28 @see: L{INotification<puremvc.interfaces.INotification>}
29 """
30
32 """
33 Send a C{INotification}.
34
35 Convenience method to prevent having to construct new notification
36 instances in our implementation code.
37
38 Raises C{NotImplemented} if subclass does not implement this method.
39
40 @param notificationName: the name of the notification to send
41 @param body: the body of the notification (optional)
42 @param noteType: the type of the notification (optional)
43 """
44 raise NotImplementedError(self)
45
47 """
48 Initialise this INotifier instance.
49
50 This is how a Notifier gets its multitonKey. Calls to sendNotification
51 or to access the facade will fail until after this method has been
52 called.
53
54 Raises C{NotImplemented} if subclass does not implement this method.
55
56 @param key: the multitonKey for this INotifier to use
57 """
58 raise NotImplementedError(self)
59
60
62 """
63 The interface definition for a PureMVC Command
64
65 @see: L{INotification<puremvc.interfaces.INotification>}
66 """
67
69 """
70 Execute the C{ICommand}'s logic to handle a given C{INotification}.
71
72 Raises C{NotImplemented} if subclass does not implement this method
73
74 @param notification: an C{INotification} to handle.
75 """
76 raise NotImplementedError(self)
77
78
80 """
81 The interface definition for a PureMVC Controller.
82
83 In PureMVC, an C{IController} implementor
84 follows the 'Command and Controller' strategy, and
85 assumes these responsibilities:
86
87 Remembering which C{ICommand}s
88 are intended to handle which C{INotifications}.
89
90 Registering itself as an C{IObserver} with
91 the C{View} for each C{INotification}
92 that it has an C{ICommand} mapping for.
93
94 Creating a new instance of the proper C{ICommand}
95 to handle a given C{INotification} when notified by the C{View}.
96
97 Calling the C{ICommand}'s C{execute}
98 method, passing in the C{INotification}.
99
100
101 @see: L{INotification<puremvc.interfaces.INotification>}
102 @see: L{ICommand<puremvc.interfaces.ICommand>}
103 """
104
106 """
107 Register a particular C{ICommand} class as the handler for a particular
108 C{INotification}.
109
110 Raises C{NotImplemented} if subclass does not implement this method.
111
112 @param notificationName: the name of the C{INotification}
113 @param commandClassRef: the Class of the C{ICommand}
114 """
115 raise NotImplementedError(self)
116
118 """
119 Execute the C{ICommand} previously registered as the handler for
120 C{INotification}s with the given notification name.
121
122 Raises C{NotImplemented} if subclass does not implement this method.
123
124 @param notification: the C{INotification} to execute the associated
125 C{ICommand} for
126 """
127 raise NotImplementedError(self)
128
130 """
131 Remove a previously registered C{ICommand} to C{INotification} mapping.
132
133 Raises C{NotImplemented} if subclass does not implement this method.
134
135 @param notificationName: the name of the C{INotification} to remove the
136 C{ICommand} mapping for
137 """
138 raise NotImplementedError(self)
139
141 """
142 Check if a Command is registered for a given Notification.
143
144 Raises C{NotImplemented} if subclass does not implement this method.
145
146 @param notificationName: the name of the C{INotification}
147 @return: whether a Command is currently registered for the given
148 C{notificationName}.
149 """
150 raise NotImplementedError(self)
151
152
154 """
155 The interface definition for a PureMVC Facade.
156
157 The Facade Pattern suggests providing a single
158 class to act as a central point of communication
159 for a subsystem.
160
161 In PureMVC, the Facade acts as an interface between
162 the core MVC actors (Model, View, Controller) and
163 the rest of your application.
164
165 @see: L{IModel<puremvc.interfaces.IModel>}
166 @see: L{IView<puremvc.interfaces.IView>}
167 @see: L{IController<puremvc.interfaces.IController>}
168 @see: L{ICommand<puremvc.interfaces.ICommand>}
169 @see: L{INotification<puremvc.interfaces.INotification>}
170 """
171
173 """
174 Notify the C{IObserver}s for a particular C{INotification}.
175
176 All previously attached IObservers for this INotification's list are notified
177 and are passed a reference to the INotification in the order in which they were registered.
178
179 NOTE: Use this method only if you are sending custom Notifications. Otherwise use the
180 sendNotification method which does not require you to create the Notification instance.
181
182 @param note: the C{INotification} to notify C{IObserver}s of.
183 """
184 raise NotImplementedError(self)
185
187 """
188 Register an C{IProxy} with the C{Model} by name.
189
190 Raises C{NotImplemented} if subclass does not implement this method.
191
192 @param proxy: the C{IProxy} to be registered with the C{Model}.
193 """
194 raise NotImplementedError(self)
195
197 """
198 Retrieve a C{IProxy} from the C{Model} by name.
199
200 Raises C{NotImplemented} if subclass does not implement this method.
201
202 @param proxyName: the name of the C{IProxy} instance to be retrieved.
203 @return: the C{IProxy} previously regisetered by C{proxyName} with the
204 C{Model}.
205 """
206 raise NotImplementedError
207
209 """
210 Remove an C{IProxy} instance from the C{Model} by name.
211
212 Raises C{NotImplemented} if subclass does not implement this method.
213
214 @param proxyName: the C{IProxy} to remove from the C{Model}.
215 @return: the C{IProxy} that was removed from the C{Model}
216 """
217 raise NotImplementedError(self)
218
220 """
221 Check if a Proxy is registered.
222
223 Raises C{NotImplemented} if subclass does not implement this method.
224
225 @param proxyName:
226 @return: whether a Proxy is currently registered with the given
227 C{proxyName}.
228 """
229 raise NotImplementedError(self)
230
232 """
233 Register an C{ICommand} with the C{Controller}.
234
235 Raises C{NotImplemented} if subclass does not implement this method.
236
237 @param noteName: the name of the C{INotification} to associate
238 the C{ICommand} with.
239 @param commandClassRef: a reference to the C{Class} of the C{ICommand}.
240 """
241 raise NotImplementedError(self)
242
244 """
245 Remove a previously registered C{ICommand} to C{INotification} mapping
246 from the Controller.
247
248 Raises C{NotImplemented} if subclass does not implement this method.
249
250 @param notificationName: the name of the C{INotification} to remove the
251 C{ICommand} mapping for
252 """
253 raise NotImplementedError(self)
254
256 """
257 Check if a Command is registered for a given Notification.
258
259 Raises C{NotImplemented} if subclass does not implement this method.
260
261 @param notificationName:
262 @return: whether a Command is currently registered for the given
263 C{notificationName}.
264 """
265 raise NotImplementedError(self)
266
276
288
300
312
313
415
416
418 """
419 The interface definition for a PureMVC Model.
420
421 In PureMVC, C{IModel} implementors provide access to C{IProxy} objects by
422 named lookup.
423
424 An C{IModel} assumes these responsibilities:
425
426 Maintain a cache of C{IProxy} instances and Provide methods for registering, retrieving, and removing C{IProxy} instances
427 """
428
430 """
431 Register an C{IProxy} instance with the C{Model}.
432
433 Raises C{NotImplemented} if subclass does not implement this method.
434
435 @param proxy: an object reference to be held by the C{Model}.
436 """
437 raise NotImplementedError(self)
438
440 """
441 Retrieve an C{IProxy} instance from the Model.
442
443 Raises C{NotImplemented} if subclass does not implement this method.
444
445 @param proxyName: the name to associate with this C{IProxy} instance.
446 @return: the C{IProxy} instance previously registered with the given
447 C{proxyName}.
448 """
449 raise NotImplementedError(self)
450
452 """
453 Remove an C{IProxy} instance from the Model.
454
455 Raises C{NotImplemented} if subclass does not implement this method.
456
457 @param proxyName: name of the C{IProxy} instance to be removed.
458 @return: the C{IProxy} that was removed from the C{Model}
459 """
460 raise NotImplementedError(self)
461
463 """
464 Check if a Proxy is registered.
465
466 Raises C{NotImplemented} if subclass does not implement this method.
467
468 @param proxyName: name of the C{IProxy} instance
469 @return: whether a Proxy is currently registered with the given
470 C{proxyName}.
471 """
472 raise NotImplementedError(self)
473
474
476 """
477 The interface definition for a PureMVC Notification.
478
479 PureMVC does not rely upon underlying event models such
480 as the one provided with Flash, and ActionScript 3 does
481 not have an inherent event model.
482
483 The Observer Pattern as implemented within PureMVC exists
484 to support event-driven communication between the
485 application and the actors of the MVC triad.
486
487 Notifications are not meant to be a replacement for Events
488 in Flex/Flash/AIR. Generally, C{IMediator} implementors
489 place event listeners on their view components, which they
490 then handle in the usual way. This may lead to the broadcast of C{Notification}s to
491 trigger C{ICommand}s or to communicate with other C{IMediators}. C{IProxy} and C{ICommand}
492 instances communicate with each other and C{IMediator}s by broadcasting C{INotification}s.
493
494 A key difference between Flash C{Event}s and PureMVC
495 C{Notification}s is that C{Event}s follow the
496 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy
497 until some parent component handles the C{Event}, while
498 PureMVC C{Notification}s follow a 'Publish/Subscribe'
499 pattern. PureMVC classes need not be related to each other in a
500 parent/child relationship in order to communicate with one another
501 using C{Notification}s.
502
503 @see: L{IView<puremvc.interfaces.IView>}
504 @see: L{IObserver<puremvc.interfaces.IObserver>}
505 """
506
508 """
509 Get the string representation of the C{INotification} instance
510 """
511 raise NotImplementedError(self)
512
514 """
515 Get the name of the C{INotification} instance. No setter, should be set
516 by constructor only.
517
518 Raises C{NotImplemented} if subclass does not implement this method.
519 """
520 raise NotImplementedError(self)
521
522 - def setBody(self, body):
523 """
524 Set the body of the C{INotification} instance.
525
526 Raises C{NotImplemented} if subclass does not implement this method.
527 """
528 raise NotImplementedError(self)
529
531 """
532 Get the body of the C{INotification} instance.
533
534 Raises C{NotImplemented} if subclass does not implement this method.
535 """
536 raise NotImplementedError(self)
537
539 """
540 Set the type of the C{INotification} instance.
541
542 Raises C{NotImplemented} if subclass does not implement this method.
543 """
544 raise NotImplementedError(self)
545
547 """
548 Get the type of the C{INotification} instance.
549
550 Raises C{NotImplemented} if subclass does not implement this method.
551 """
552 raise NotImplementedError(self)
553
554
556 """
557 The interface definition for a PureMVC Observer.
558
559 In PureMVC, C{IObserver} implementors assume these responsibilities:
560
561 Encapsulate the notification (callback) method of the interested object.
562
563 Encapsulate the notification context of the interested object.
564
565 Provide methods for setting the interested object' notification method and context.
566
567 Provide a method for notifying the interested object.
568
569
570 PureMVC does not rely upon underlying event
571 models such as the one provided with Flash,
572 and ActionScript 3 does not have an inherent
573 event model.
574
575
576 The Observer Pattern as implemented within
577 PureMVC exists to support event driven communication
578 between the application and the actors of the
579 MVC triad.
580
581
582 An Observer is an object that encapsulates information
583 about an interested object with a notification method that
584 should be called when an C{INotification} is broadcast. The Observer then
585 acts as a proxy for notifying the interested object.
586
587
588 Observers can receive C{Notification}s by having their
589 C{notifyObserver} method invoked, passing
590 in an object implementing the C{INotification} interface, such
591 as a subclass of C{Notification}.
592
593 @see: L{IView<puremvc.interfaces.IView>}
594 @see: L{INotification<puremvc.interfaces.INotification>}
595 """
596
598 """
599 Set the notification method.
600
601 The notification method should take one parameter of type
602 C{INotification}
603
604 Raises C{NotImplemented} if subclass does not implement this method.
605
606 @param notifyMethod: the notification (callback) method of the
607 interested object
608 """
609 raise NotImplementedError(self)
610
611 - def setNotifyContext(self, notifyContext):
612 """
613 Set the notification context.
614
615 Raises C{NotImplemented} if subclass does not implement this method.
616
617 @param notifyContext: the notification context (this) of the interested
618 object
619 """
620 raise NotImplementedError(self)
621
623 """
624 Notify the interested object.
625
626 Raises C{NotImplemented} if subclass does not implement this method.
627
628 @param notification: the C{INotification} to pass to the interested
629 object's notification method
630 """
631 raise NotImplementedError(self)
632
633 - def compareNotifyContext(self, obj):
634 """
635 Compare the given object to the notification context object.
636
637 Raises C{NotImplemented} if subclass does not implement this method.
638
639 @param obj: the object to compare.
640 @return: boolean indicating if the notification context and the object
641 are the same.
642 """
643 raise NotImplementedError(self)
644
645
647 """
648 The interface definition for a PureMVC Proxy.
649
650 In PureMVC, C{IProxy} implementors assume these responsibilities:
651
652 Implement a common method which returns the name of the Proxy.
653
654 Provide methods for setting and getting the data object.
655
656 Additionally, C{IProxy}s typically:
657
658 Maintain references to one or more pieces of model data.
659 Provide methods for manipulating that data.
660 Generate C{INotifications} when their model data changes.
661 Expose their name as a C{public static const} called C{NAME}, if they are not instantiated multiple times.
662 Encapsulate interaction with local or remote services used to fetch and persist model data.
663 """
664
666 """
667 Get the Proxy name.
668
669 Raises C{NotImplemented} if subclass does not implement this method.
670
671 @return: the Proxy instance name
672 """
673 raise NotImplementedError(self)
674
676 """
677 Set the data object.
678
679 Raises C{NotImplemented} if subclass does not implement this method.
680
681 @param data: the data object
682 """
683 raise NotImplementedError(self)
684
686 """
687 Get the data object.
688
689 Raises C{NotImplemented} if subclass does not implement this method.
690
691 @return: the data as type Object
692 """
693 raise NotImplementedError(self)
694
696 """
697 Called by the Model when the Proxy is registered.
698
699 Raises C{NotImplemented} if subclass does not implement this method.
700 """
701 raise NotImplementedError(self)
702
704 """
705 Called by the Model when the Proxy is removed.
706
707 Raises C{NotImplemented} if subclass does not implement this method.
708 """
709 raise
710
711
713 """
714 The interface definition for a PureMVC View.
715
716 In PureMVC, C{IView} implementors assume these responsibilities:
717
718 In PureMVC, the C{View} class assumes these responsibilities:
719
720 Maintain a cache of C{IMediator} instances.
721
722 Provide methods for registering, retrieving, and removing C{IMediators}.
723
724 Managing the observer lists for each C{INotification} in the application.
725
726 Providing a method for attaching C{IObservers} to an C{INotification}'s observer list.
727
728 Providing a method for broadcasting an C{INotification}.
729
730 Notifying the C{IObservers} of a given C{INotification} when it broadcast.
731
732 @see: L{IMediator<puremvc.interfaces.IMediator>}
733 @see: L{IObserver<puremvc.interfaces.IObserver>}
734 @see: L{INotification<puremvc.interfaces.INotification>}
735 """
736
738 """
739 Register an C{IObserver} to be notified of C{INotifications} with a
740 given name.
741
742 Raises C{NotImplemented} if subclass does not implement this method.
743
744 @param notificationName: the name of the C{INotifications} to notify
745 this C{IObserver} of
746 @param observer: the C{IObserver} to register
747 """
748 raise NotImplementedError(self)
749
751 """
752 Remove a group of observers from the observer list for a given
753 Notification name.
754
755 Raises C{NotImplemented} if subclass does not implement this method.
756
757 @param notificationName: which observer list to remove from
758 @param notifyContext: removed the observers with this object as their
759 notifyContext
760 """
761 raise NotImplementedError(self)
762
764 """
765 Notify the C{IObservers} for a particular C{INotification}.
766
767 All previously attached C{IObservers} for this C{INotification}'s
768 list are notified and are passed a reference to the C{INotification} in
769 the order in which they were registered.
770
771 Raises C{NotImplemented} if subclass does not implement this method.
772
773 @param notification: the C{INotification} to notify C{IObservers} of
774 """
775 raise NotImplementedError(self)
776
794
806
817
829