Event_Dispatcher
[ class tree: Event_Dispatcher ] [ index: Event_Dispatcher ] [ all elements ]
Packages:
Event_Dispatcher


Classes:
Event_Dispatcher
Event_Notification
Examples
   MyNotification
   sender
Files:
Dispatcher.php
Notification.php

subpackage Examples
bubbling.php
cancel.php
debugging.php
notification-class.php
object.php

Class: Event_Dispatcher

Source Location: /Event_Dispatcher-1.1.0/Event/Dispatcher.php

Class Overview




Dispatch notifications using PHP callbacks




Author(s):






            
          
          

Version:


    
  
  • Release: @package_version@
    • 




Copyright:


    
  
  • 1997-2005 The PHP Group
    • 








Methods
















Inherited Variables





Inherited Methods














Class Details



[line 80]

Dispatch notifications using PHP callbacks
The Event_Dispatcher acts acts as a notification dispatch table.  It is used to notify other objects of interesting things, if  they meet certain criteria. This information is encapsulated  in Event_Notification objects. Client objects register  themselves with the Event_Dispatcher as observers of specific  notifications posted by other objects. When an event occurs,  an object posts an appropriate notification to the Event_Dispatcher.  The Event_Dispatcher dispatches a message to each  registered observer, passing the notification as the sole argument.
The Event_Dispatcher is actually a combination of three design  patterns: the Singleton, Mediator,  and Observer patterns. The idea behind Event_Dispatcher is borrowed from  Apple's Cocoa framework.









[ Top ]








Method Detail



	
	
addNestedDispatcher   [line 431]

	

    

    

		void addNestedDispatcher(
Event_Dispatcher
&$dispatcher)
    

    


	
		add a new nested dispatcher
Notifications will be broadcasted to this dispatcher as well, which  allows you to create event bubbling.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        Event_Dispatcher  
        &$dispatcher  
        —
          The nested dispatcher
      

        

    


        
[ Top ]

  

  
  
	
	
addObserver   [line 188]

	

    

    

		void addObserver(
mixed
$callback, [string
$nName = EVENT_DISPATCHER_GLOBAL], [string
$class = null])
    

    


	
		Registers an observer callback
This method registers a callback  which is called when the notification corresponding to the  criteria given at registration time is posted.  The criteria are the notification name and eventually the  class of the object posted with the notification.
If there are any pending notifications corresponding to the criteria  given here, the callback will be called straight away.
If the notification name is empty, the observer will receive all the  posted notifications. Same goes for the class name.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        mixed  
        $callback  
        —
          A PHP callback
      

          

        string  
        $nName  
        —
          Expected notification name, serves as a filter
      

          

        string  
        $class  
        —
          Expected contained object class, serves as a filter
      

        

    


        
[ Top ]

  

  
  
	
	
getInstance   [line 156]

	

    

    

		object Event_Dispatcher &getInstance(
[string
$name = '__default'])
    

    


	
		Returns a notification dispatcher singleton
There is usually no need to have more than one notification  center for an application so this is the recommended way  to get a Event_Dispatcher object.




        
Parameters:

    

    

          

        string  
        $name  
        —
          Name of the notification dispatcher.                   The default notification dispatcher is named __default.
      

        

    


        
[ Top ]

  

  
  
	
	
getName   [line 417]

	

    

    

		string getName(
)
    

    


	
		Get the name of the dispatcher.
The name is the unique identifier of a dispatcher.


    

  • Return: name of the dispatcher
    • 

  • Access: public
    • 








        
[ Top ]

  

  
  
	
	
getObservers   [line 395]

	

    

    

		array getObservers(
[string
$nName = EVENT_DISPATCHER_GLOBAL], [string
$class = null])
    

    


	
		Get all observers, that have been registered for a notification


    

  • Return: List of all observers
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $nName  
        —
          Notification name
      

          

        string  
        $class  
        —
          Contained object class
      

        

    


        
[ Top ]

  

  
  
	
	
observerRegistered   [line 363]

	

    

    

		bool observerRegistered(
mixed
$callback, [string
$nName = EVENT_DISPATCHER_GLOBAL], [string
$class = null])
    

    


	
		Check, whether the specified observer has been registered with the  dispatcher


    

  • Return: True if the observer has been registered, false otherwise
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        mixed  
        $callback  
        —
          A PHP callback
      

          

        string  
        $nName  
        —
          Notification name
      

          

        string  
        $class  
        —
          Contained object class
      

        

    


        
[ Top ]

  

  
  
	
	
post   [line 247]

	

    

    

		object The &post(
object Notification
&$object, string
$nName, [array
$info = array()], [bool
$pending = true], [bool
$bubble = true])
    

    


	
		Creates and posts a notification object
The purpose of the optional associated object is generally to pass  the object posting the notification to the observers, so that the  observers can query the posting object for more information about  the event.
Notifications are by default added to a pending notification list.  This way, if an observer is not registered by the time they are  posted, it will still be notified when it is added as an observer.  This behaviour can be turned off in order to make sure that only  the registered observers will be notified.
The info array serves as a container for any kind of useful  information. It is added to the notification object and posted along.


    

  • Return: notification object
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        object Notification  
        &$object  
        —
          associated object
      

          

        string  
        $nName  
        —
          Notification name
      

          

        array  
        $info  
        —
          Optional user information
      

          

        bool  
        $pending  
        —
          Whether the notification is pending
      

          

        bool  
        $bubble  
        —
          Whether you want the notification to bubble up
      

        

    


        
[ Top ]

  

  
  
	
	
postNotification   [line 263]

	

    

    

		object The &postNotification(
object The
&$notification, [bool
$pending = true], [bool
$bubble = true])
    

    


	
		Posts the Event_Notification object








        
Parameters:

    

    

          

        object The  
        &$notification  
        —
          Notification object
      

          

        bool  
        $pending  
        —
          Whether to post the notification immediately
      

          

        bool  
        $bubble  
        —
          Whether you want the notification to bubble up
      

        

    


        
[ Top ]

  

  
  
	
	
removeNestedDispatcher   [line 444]

	

    

    

		boolean removeNestedDispatcher(
Event_Dispatcher
$dispatcher)
    

    


	
		remove a nested dispatcher


    

  • Access: public
    • 








        
Parameters:

    

    

          

        Event_Dispatcher  
        $dispatcher  
        —
          Dispatcher to remove
      

        

    


        
[ Top ]

  

  
  
	
	
removeObserver   [line 322]

	

    

    

		bool removeObserver(
mixed
$callback, [string
$nName = EVENT_DISPATCHER_GLOBAL], [string
$class = null])
    

    


	
		Removes a registered observer that correspond to the given criteria


    

  • Return: True if an observer was removed, false otherwise
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        mixed  
        $callback  
        —
          A PHP callback
      

          

        string  
        $nName  
        —
          Notification name
      

          

        string  
        $class  
        —
          Contained object class
      

        

    


        
[ Top ]

  

  
  
	
	
setNotificationClass   [line 467]

	

    

    

		boolean setNotificationClass(
string
$class)
    

    


	
		Changes the class used for notifications
You may call this method on an object to change it for a single  dispatcher or statically, to set the default for all dispatchers  that will be created.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $class  
        —
          name of the notification class
      

        

    


        
[ Top ]

  

  
  



        

		    

		    Documentation generated on Fri, 24 Jul 2009 06:30:02 +0000 by phpDocumentor 1.4.2. PEAR Logo Copyright ©  PHP Group 2004.