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

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.