puremvc.interfaces

1 """ 2 PureMVC Python Port by Toby de Havilland <toby.de.havilland@puremvc.org> 3 PureMVC - Copyright(c) 2006-08 Futurescale, Inc., Some rights reserved. 4 Your reuse is governed by the Creative Commons Attribution 3.0 License 5 """ 6

7 -class ICommand:

8 """ 9 The interface definition for a PureMVC Command. 10 11 @see: L{INotification<puremvc.interfaces.INotification>} 12 """

13 - def execute(self, notification):

14 """ 15 Execute the C{ICommand}'s logic to handle a given C{INotification}. 16 17 Raises C{NotImplemented} if subclass does not implement this method 18 19 @param notification: an C{INotification} to handle. 20 """ 21 raise NotImplemented

22

23 -class IController:

24 """ 25 The interface definition for a PureMVC Controller. 26 27 In PureMVC, an C{IController} implementor 28 follows the 'Command and Controller' strategy, and 29 assumes these responsibilities: 30 31 Remembering which C{ICommand}s 32 are intended to handle which C{INotifications}. 33 34 Registering itself as an C{IObserver} with 35 the C{View} for each C{INotification} 36 that it has an C{ICommand} mapping for. 37 38 Creating a new instance of the proper C{ICommand} 39 to handle a given C{INotification} when notified by the C{View}. 40 41 Calling the C{ICommand}'s C{execute} 42 method, passing in the C{INotification}. 43 44 45 @see: L{INotification<puremvc.interfaces.INotification>} 46 @see: L{ICommand<puremvc.interfaces.ICommand>} 47 """

48 - def registerCommand(self, notificationName, commandClassRef):

49 """ 50 Register a particular C{ICommand} class as the handler for a particular C{INotification}. 51 52 @param notificationName: the name of the C{INotification} 53 @param commandClassRef: the Class of the C{ICommand} 54 """ 55 raise NotImplemented

56

57 - def executeCommand(self, notification):

58 """ 59 Execute the C{ICommand} previously registered as thehandler for C{INotification}s with the given notification name. 60 61 @param notification: the C{INotification} to execute the associated C{ICommand} for 62 """ 63 raise NotImplemented

64

65 - def removeCommand(self, notificationName):

66 """ 67 Remove a previously registered C{ICommand} to C{INotification} mapping. 68 69 @param notificationName: the name of the C{INotification} to remove the C{ICommand} mapping fo 70 """ 71 raise NotImplemented

72

73 - def hasCommand(self, notificationName):

74 """ 75 Check if a Command is registered for a given Notification 76 77 @param notificationName: the name of the C{INotification} 78 @return: whether a Command is currently registered for the given C{notificationName}. 79 """ 80 raise NotImplemented

81

82 -class IFacade:

83 """ 84 The interface definition for a PureMVC Facade. 85 86 The Facade Pattern suggests providing a single 87 class to act as a central point of communication 88 for a subsystem. 89 90 In PureMVC, the Facade acts as an interface between 91 the core MVC actors (Model, View, Controller) and 92 the rest of your application. 93 94 @see: L{IModel<puremvc.interfaces.IModel>} 95 @see: L{IView<puremvc.interfaces.IView>} 96 @see: L{IController<puremvc.interfaces.IController>} 97 @see: L{ICommand<puremvc.interfaces.ICommand>} 98 @see: L{INotification<puremvc.interfaces.INotification>} 99 """

100 - def notifyObservers(self,note):

101 """ 102 Notify the C{IObserver}s for a particular C{INotification}. 103 104 All previously attached IObservers for this INotification's list are notified 105 and are passed a reference to the INotification in the order in which they were registered. 106 107 NOTE: Use this method only if you are sending custom Notifications. Otherwise use the 108 sendNotification method which does not require you to create the Notification instance. 109 110 @param note: the C{INotification} to notify C{IObserver}s of. 111 """ 112 raise NotImplemented

113

114 - def registerProxy(self, proxy):

115 """ 116 Register an C{IProxy} with the C{Model} by name. 117 118 @param proxy: the C{IProxy} to be registered with the C{Model}. 119 """ 120 raise NotImplemented

121

122 - def retreieveProxy(self, proxyName):

123 """ 124 Retrieve a C{IProxy} from the C{Model} by name. 125 126 @param proxyName: the name of the C{IProxy} instance to be retrieved. 127 @return: the C{IProxy} previously regisetered by C{proxyName} with the C{Model}. 128 """ 129 raise NotImplemented

130

131 - def removeProxy(self, proxyName):

132 """ 133 Remove an C{IProxy} instance from the C{Model} by name. 134 135 @param proxyName: the C{IProxy} to remove from the C{Model}. 136 @return: the C{IProxy} that was removed from the C{Model} 137 """ 138 raise NotImplemented

139

140 - def hasProxy(self, proxyName):

141 """ 142 Check if a Proxy is registered 143 144 @param proxyName: 145 @return: whether a Proxy is currently registered with the given C{proxyName}. 146 """ 147 raise NotImplemented

148

149 - def registerCommand(self, noteName, commandClassRef):

150 """ 151 Register an C{ICommand} with the C{Controller}. 152 153 @param noteName: the name of the C{INotification} to associate the C{ICommand} with. 154 @param commandClassRef: a reference to the C{Class} of the C{ICommand}. 155 """ 156 raise NotImplemented

157

158 - def removeCommand(self, notificationName):

159 """ 160 Remove a previously registered C{ICommand} to C{INotification} mapping from the Controller. 161 162 @param notificationName: the name of the C{INotification} to remove the C{ICommand} mapping for 163 """ 164 raise NotImplemented

165

166 - def hasCommand(self, notificationName):

167 """ 168 Check if a Command is registered for a given Notification 169 170 @param notificationName: the name of the C{INotification} 171 @return: whether a Command is currently registered for the given C{notificationName}. 172 """ 173 raise NotImplemented

174

175 - def registerMediator(self, mediator):

176 """ 177 Register an C{IMediator} instance with the C{View}. 178 179 @param mediator: a reference to the C{Mediator} instance 180 """ 181 raise NotImplemented

182

183 - def retreieveMediator(self, mediatorName):

184 """ 185 Retrieve an C{IMediator} instance from the C{View}. 186 187 @param mediatorName: the name of the C{IMediator} instance to retrievve 188 @return: the C{IMediator} previously registered with the given C{mediatorName}. 189 """ 190 raise NotImplemented

191

192 - def removeMediator(self, mediatorName):

193 """ 194 Remove a C{IMediator} instance from the C{View}. 195 196 @param mediatorName: name of the C{IMediator} instance to be removed. 197 @return: the C{IMediator} instance previously registered with the given C{mediatorName}. 198 """ 199 raise NotImplemented

200

201 -class IMediator:

202 """ 203 The interface definition for a PureMVC Mediator. 204 205 In PureMVC, C{IMediator} implementors assume these responsibilities: 206 207 Implement a common method which returns a list of all C{INotification}s the C{IMediator} has interest in. 208 209 Implement a notification callback method. 210 211 Implement methods that are called when the IMediator is registered or removed from the View. 212 213 214 Additionally, C{IMediator}s typically: 215 216 Act as an intermediary between one or more view components such as text boxes or list controls, maintaining references and coordinating their behavior. 217 218 In Flash-based apps, this is often the place where event listeners are 219 added to view components, and their handlers implemented. 220 221 Respond to and generate C{INotifications}, interacting with of the rest of the PureMVC app. 222 223 When an C{IMediator} is registered with the C{IView}, the C{IView} will call the C{IMediator}'s C{listNotificationInterests} method. The C{IMediator} will 224 return an C{List} of C{INotification} names which 225 it wishes to be notified about. 226 227 228 The C{IView} will then create an C{Observer} object 229 encapsulating that C{IMediator}'s (C{handleNotification}) method 230 and register it as an Observer for each C{INotification} name returned by 231 C{listNotificationInterests}. 232 233 @see: L{INotification<puremvc.interfaces.INotification>} 234 """

235 - def getMediatorName(self):

236 """ 237 Get the C{IMediator} instance name 238 239 @return: the C{IMediator} instance name 240 """ 241 raise NotImplemented

242

243 - def getViewComponent(self):

244 """ 245 Get the C{IMediator}'s view component. 246 247 @return: the view component 248 """ 249 raise NotImplemented

250

251 - def setViewComponent(self, viewComponent):

252 """ 253 Set the C{IMediator}'s view component. 254 255 @param viewComponent: the view component 256 """ 257 raise NotImplemented

258

259 - def listNotificationInterests(self):

260 """ 261 List C{INotification} interests. 262 263 @return: an C{List} of the C{INotification} names this C{IMediator} has an interest in. 264 """ 265 raise NotImplemented

266

267 - def handleNotification(self, notification):

268 """ 269 Handle an C{INotification}. 270 271 @param notification: the C{INotification} to be handled 272 """ 273 raise NotImplemented

274

275 - def onRegister(self):

276 """ 277 Called by the View when the Mediator is registered 278 """ 279 raise NotImplemented

280

281 - def onRemove(self):

282 """ 283 Called by the View when the Mediator is removed 284 """ 285 raise NotImplemented

286

287 -class IModel:

288 """ 289 The interface definition for a PureMVC Model. 290 291 In PureMVC, C{IModel} implementors provide 292 access to C{IProxy} objects by named lookup. 293 294 An C{IModel} assumes these responsibilities: 295 296 Maintain a cache of C{IProxy} instances and Provide methods for registering, retrieving, and removing C{IProxy} instances 297 """

298 - def registerProxy(self, proxy):

299 """ 300 Register an C{IProxy} instance with the C{Model}. 301 302 @param proxy: an object reference to be held by the C{Model}. 303 """ 304 raise NotImplemented

305

306 - def retrieveProxy(self, proxyName):

307 """ 308 Retrieve an C{IProxy} instance from the Model. 309 310 @param proxyName: name of the C{IProxy} instance to retrieve. 311 @return: the C{IProxy} instance previously registered with the given C{proxyName}. 312 """ 313 raise NotImplemented

314

315 - def removeProxy(self, proxyName):

316 """ 317 Remove an C{IProxy} instance from the Model. 318 319 @param proxyName: name of the C{IProxy} instance to be removed. 320 @return: the C{IProxy} that was removed from the C{Model} 321 """ 322 raise NotImplemented

323

324 - def hasProxy(self, proxyName):

325 """ 326 Check if a Proxy is registered 327 328 @param proxyName: name of the C{IProxy} instance 329 @return: whether a Proxy is currently registered with the given C{proxyName}. 330 """ 331 raise NotImplemented

332

333 -class INotification:

334 """ 335 The interface definition for a PureMVC Notification. 336 337 PureMVC does not rely upon underlying event models such 338 as the one provided with Flash, and ActionScript 3 does 339 not have an inherent event model. 340 341 The Observer Pattern as implemented within PureMVC exists 342 to support event-driven communication between the 343 application and the actors of the MVC triad. 344 345 Notifications are not meant to be a replacement for Events 346 in Flex/Flash/AIR. Generally, C{IMediator} implementors 347 place event listeners on their view components, which they 348 then handle in the usual way. This may lead to the broadcast of C{Notification}s to 349 trigger C{ICommand}s or to communicate with other C{IMediators}. C{IProxy} and C{ICommand} 350 instances communicate with each other and C{IMediator}s by broadcasting C{INotification}s. 351 352 A key difference between Flash C{Event}s and PureMVC 353 C{Notification}s is that C{Event}s follow the 354 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy 355 until some parent component handles the C{Event}, while 356 PureMVC C{Notification}s follow a 'Publish/Subscribe' 357 pattern. PureMVC classes need not be related to each other in a 358 parent/child relationship in order to communicate with one another 359 using C{Notification}s. 360 361 @see: L{IView<puremvc.interfaces.IView>} 362 @see: L{IObserver<puremvc.interfaces.IObserver>} 363 """

364 - def getName(self):

365 """ 366 Get the name of the C{INotification} instance. 367 """ 368 raise NotImplemented

369

370 - def setBody(self, body):

371 """ 372 Set the body of the C{INotification} instance 373 """ 374 raise NotImplemented

375

376 - def getBody(self):

377 """ 378 Get the body of the C{INotification} instance 379 """ 380 raise NotImplemented

381

382 - def setType(self, type):

383 """ 384 Set the type of the C{INotification} instance 385 """ 386 raise NotImplemented

387

388 - def getType(self):

389 """ 390 Get the type of the C{INotification} instance 391 """ 392 raise NotImplemented

393

394 - def str(self):

395 """ 396 Get the string representation of the C{INotification} instance 397 """ 398 raise NotImplemented

399

400 -class INotifier:

401 """ 402 The interface definition for a PureMVC Notifier. 403 404 C{MacroCommand, Command, Mediator} and C{Proxy} 405 all have a need to send C{Notifications}. 406 407 The C{INotifier} interface provides a common method called 408 C{sendNotification} that relieves implementation code of 409 the necessity to actually construct C{Notifications}. 410 411 The C{Notifier} class, which all of the above mentioned classes 412 extend, also provides an initialized reference to the C{Facade} 413 Singleton, which is required for the convienience method 414 for sending C{Notifications}, but also eases implementation as these 415 classes have frequent C{Facade} interactions and usually require 416 access to the facade anyway. 417 418 @see: L{IFacade<puremvc.interfaces.IFacade>} 419 @see: L{INotification<puremvc.interfaces.INotification>} 420 """

421 - def sendNotification(self, notificationName, body = None, type = None):

422 """ 423 Send a C{INotification}. 424 425 Convenience method to prevent having to construct new 426 notification instances in our implementation code. 427 428 @param notificationName: the name of the notification to send 429 @param body: the body of the notification (optional) 430 @param type: the type of the notification (optional) 431 """ 432 raise NotImplemented

433

434 -class IObserver:

435 """ 436 The interface definition for a PureMVC Observer. 437 438 In PureMVC, C{IObserver} implementors assume these responsibilities: 439 440 Encapsulate the notification (callback) method of the interested object. 441 442 Encapsulate the notification context of the interested object. 443 444 Provide methods for setting the interested object' notification method and context. 445 446 Provide a method for notifying the interested object. 447 448 449 PureMVC does not rely upon underlying event 450 models such as the one provided with Flash, 451 and ActionScript 3 does not have an inherent 452 event model. 453 454 455 The Observer Pattern as implemented within 456 PureMVC exists to support event driven communication 457 between the application and the actors of the 458 MVC triad. 459 460 461 An Observer is an object that encapsulates information 462 about an interested object with a notification method that 463 should be called when an C{INotification} is broadcast. The Observer then 464 acts as a proxy for notifying the interested object. 465 466 467 Observers can receive C{Notification}s by having their 468 C{notifyObserver} method invoked, passing 469 in an object implementing the C{INotification} interface, such 470 as a subclass of C{Notification}. 471 472 @see: L{IView<puremvc.interfaces.IView>} 473 @see: L{INotification<puremvc.interfaces.INotification>} 474 """

475 - def setNotifyMethod(self, notifyMethod):

476 """ 477 Set the notification method. 478 479 The notification method should take one parameter of type C{INotification} 480 481 @param notifyMethod: the notification (callback) method of the interested object 482 """ 483 raise NotImplemented

484

485 - def setNotifyContext(self, notifyContext):

486 """ 487 Set the notification context. 488 489 @param notifyContext: the notification context of the interested object 490 """ 491 raise NotImplemented

492

493 - def notifyObserver(self, notification):

494 """ 495 Notify the interested object. 496 497 @param notification: the C{INotification} to pass to the interested object's notification method 498 """ 499 raise NotImplemented

500

501 - def compareNotifyContext(self, object):

502 """ 503 Compare the given object to the notificaiton context object. 504 505 @param object: the object to compare. 506 @return: boolean indicating if the notification context and the object are the same. 507 """ 508 raise NotImplemented

509

510 -class IProxy:

511 """ 512 The interface definition for a PureMVC Proxy. 513 514 In PureMVC, C{IProxy} implementors assume these responsibilities: 515 516 Implement a common method which returns the name of the Proxy. 517 518 Provide methods for setting and getting the data object. 519 520 Additionally, C{IProxy}s typically: 521 522 Maintain references to one or more pieces of model data. 523 Provide methods for manipulating that data. 524 Generate C{INotifications} when their model data changes. 525 Expose their name as a C{public static const} called C{NAME}, if they are not instantiated multiple times. 526 Encapsulate interaction with local or remote services used to fetch and persist model data. 527 """

528 - def getProxyName(self):

529 """ 530 Get the Proxy name 531 532 @return: the Proxy instance name 533 """ 534 raise NotImplemented

535

536 - def setData(data):

537 """ 538 Set the data object 539 540 @param data: the data object 541 """ 542 raise NotImplemented

543

544 - def getData():

545 """ 546 Get the data object 547 548 @return: the data as type Object 549 """ 550 raise NotImplemented

551

552 - def onRegister( ):

553 """ 554 Called by the Model when the Proxy is registered 555 """ 556 raise NotImplemented

557

558 - def onRemove( ):

559 """ 560 Called by the Model when the Proxy is removed 561 """ 562 raise NotImplemented

563

564 -class IView:

565 """ 566 The interface definition for a PureMVC View. 567 568 In PureMVC, C{IView} implementors assume these responsibilities: 569 570 In PureMVC, the C{View} class assumes these responsibilities: 571 572 Maintain a cache of C{IMediator} instances. 573 574 Provide methods for registering, retrieving, and removing C{IMediators}. 575 576 Managing the observer lists for each C{INotification} in the application. 577 578 Providing a method for attaching C{IObservers} to an C{INotification}'s observer list. 579 580 Providing a method for broadcasting an C{INotification}. 581 582 Notifying the C{IObservers} of a given C{INotification} when it broadcast. 583 584 @see: L{IMediator<puremvc.interfaces.IMediator>} 585 @see: L{IObserver<puremvc.interfaces.IObserver>} 586 @see: L{INotification<puremvc.interfaces.INotification>} 587 """

588 - def registerObserver(self, notificationName, observer):

589 """ 590 Register an C{IObserver} to be notified of C{INotifications} with a given name. 591 592 @param notificationName: the name of the C{INotifications} to notify this C{IObserver} of 593 @param observer: the C{IObserver} to register 594 """ 595 raise NotImplemented

596

597 - def notifyObservers(self, notification):

598 """ 599 Notify the C{IObservers} for a particular C{INotification}. 600 601 All previously attached C{IObservers} for this C{INotification}'s 602 list are notified and are passed a reference to the C{INotification} in 603 the order in which they were registered.</P> 604 605 @param notification: the C{INotification} to notify C{IObservers} of. 606 """ 607 raise NotImplemented

608

609 - def registerMediator(self, mediator):

610 """ 611 Register an C{IMediator} instance with the C{View}. 612 613 Registers the C{IMediator} so that it can be retrieved by name, 614 and further interrogates the C{IMediator} for its 615 C{INotification} interests. 616 617 If the C{IMediator} returns any C{INotification} 618 names to be notified about, an C{Observer} is created encapsulating 619 the C{IMediator} instance's C{handleNotification} method 620 and registering it as an C{Observer} for all C{INotifications} the 621 C{IMediator} is interested in. 622 623 @param mediator: a reference to the C{IMediator} instance 624 """ 625 raise NotImplemented

626

627 - def retrieveMediator(self, mediatorName):

628 """ 629 Retrieve an C{IMediator} from the C{View}. 630 631 @param mediatorName: the name of the C{IMediator} instance to retrieve. 632 @return: the C{IMediator} instance previously registered with the given C{mediatorName}. 633 """ 634 raise NotImplemented

635

636 - def removeMediator(self, mediatorName):

637 """ 638 Remove an C{IMediator} from the C{View}. 639 640 @param mediatorName: name of the C{IMediator} instance to be removed. 641 @return: the C{IMediator} that was removed from the C{View} 642 """ 643 raise NotImplemented

644

645 - def hasMediator(self, mediatorName):

646 """ 647 Check if a Mediator is registered or not 648 649 @param mediatorName: name of the C{IMediator} 650 @return: whether a Mediator is registered with the given C{mediatorName}. 651 """ 652 raise NotImplemented

653

Source Code for Module puremvc.interfaces