AsBroadcaster

Package	Top Level
Class	public class AsBroadcaster
Inheritance	AsBroadcaster Object

Player version:

Flash Player 6

Provides event notification and listener management capabilities that you can add to user-defined objects. This class is intended for advanced users who want to create custom event handling mechanisms. You can use this class to make any object an event broadcaster and to create one or more listener objects that receive notification anytime the broadcasting object calls the broadcastMessage() method.

There is no constructor function for the AsBroadcaster class. To use this class, follow this process:

Select or create an object to serve as the event broadcaster.
Make the object an event broadcaster by calling the static AsBroadcaster.initialize(obj:Object) method, where the obj parameter is the name of the object that you selected to be the broadcaster.
Select or create one or more listener objects. Listener objects receive notification whenever the broadcasting object broadcasts a message
Define a listener method for each of your listener objects. The listener method executes ActionScript code in response to the event notification. The name of the method must match the name of the event that is broadcasted by the broadcasting object.
Register each listener object with the event broadcaster by calling myBroadcaster.addListener(myListener), where myBroadcaster is the name of the event broadcaster object and myListener is the name of the listener object. Each event broadcaster stores a list of listener objects to be notified when a message is broadcast. Use the addListener() method to add listeners to the list, and use removeListener() to remove listeners from the list.
Finally, to broadcast a message, call the myBroadcaster.broadcastMessage(eventName:String) method, where myBroadcaster is the name of the event broadcaster and eventName is the name of the event that matches the name of the listener method.

Note: A common mistake is to capitalize the second letter of AsBroadcaster. When calling the AsBroadcaster.initialize() method, ensure that the second letter is lowercase. Any misspelling of AsBroadcaster fails silently.

	Property
		_listeners : Array [read-only]A list of references to all registered listener objects.

	Properties inherited from class Object
	`__proto__, __resolve, constructor, prototype`

	Methods inherited from class Object
	`addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch`

Property detail

_listeners

property

_listeners:Array [read-only]

Player version:

Flash Player 6

A list of references to all registered listener objects. This property is intended for internal use, and is not intended for direct manipulation. Objects are added to and removed from this array by calls to the addListener() and removelistener() methods.

You can call this property only from an object that was initialized by using the AsBroadcaster.initialize() method.

Implementation
public function get _listeners():Array

See also

AsBroadcaster.initialize()

Example
The following example shows how to use the length property to ascertain the number of listener objects currently registered to an event broadcaster. The following code works if it is added to the first full example in the Examples section of the AsBroadcaster.initialize() entry:

trace(someObject._listeners.length); // Output: 2

For advanced users, the following example shows how to use the _listeners property to list all of the listeners registered with an event broadcaster, along with all of the properties of each listener object. The following example creates two different listener methods for the first listener object.

var someObject:Object = new Object();         // create broadcast object

var myListener1:Object = new Object();        // create listener object
var myListener2:Object = new Object();        // create listener object

myListener1.someEvent = function() {          // create listener method
    trace("myListener1 received someEvent");
}
myListener1.anotherEvent = function() {       // create another listener method
    trace("myListener1 received anotherEvent");
}
myListener2.someEvent = function() {          // create listener method
    trace("myListener2 received someEvent");
}

AsBroadcaster.initialize(someObject);         // make someObject an event broadcaster
someObject.addListener(myListener1);          // register myListener1 as listener
someObject.addListener(myListener2);          // register myListener2 as listener

var numListeners:Number = someObject._listeners.length;  // get number of registered listeners

// cycle through all listener objects, listing all properties of each listener object
for (var i:Number = 0; i < numListeners; i++) {
    trace("Listener " + i + " listens for these events:");
    for (item in someObject._listeners[i]) {
        trace ("   " + item + ": " + someObject._listeners[i][item]);
    }
}

Method detail

addListener

()

method

public function addListener(listenerObj:Object):Boolean

Player version:

Flash Player 6

Registers an object to receive event notification messages. This method is called on the broadcasting object and the listener object is sent as an argument.

Parameters

listenerObj:Object — The name of the listener object that receives event notification.

Returns

Boolean — Although this method technically returns a Boolean value, in practical terms it returns Void because it always returns the value true.

Example
The following example is an excerpt from the full example provided in the entry for the AsBroadcaster.initialize() method.

someObject.addListener(myListener1);          // Register myListener1 as listener.
someObject.addListener(myListener2);          // Register myListener2 as listener.

broadcastMessage

()

method

public function broadcastMessage(eventName:String):Void

Player version:

Flash Player 6

Sends an event message to each object in the list of listeners. When the message is received by the listening object, Flash Player attempts to invoke a function of the same name on the listening object. Suppose that your object broadcasts an event message like this:

obj.broadcastMessage("onAlert");

When this message is received, Flash Player invokes a method named onAlert() on the receiving listener object.

Note: You can pass arguments to your listener functions by including additional arguments to the broadcastMessage() method. Any arguments that appear after the eventName parameter are received as arguments by the listener method.

You can call this method only from an object that was initialized by using the AsBroadcaster.initialize() method.

Parameters

eventName:String — The name of the event to broadcast. The name of any listener methods must match this parameter in order to receive the broadcast event. You can pass arguments to the listener methods by including additional arguments after eventName.

Example
The following example is an excerpt from the first full example provided in the entry for the AsBroadcaster.initialize() method:

someObject.broadcastMessage("someEvent");     // Broadcast the "someEvent" message.

The following example is an excerpt from the second full example provided in the entry for the AsBroadcaster.initialize() method. It shows how to send arguments to listener methods.

someObject.broadcastMessage("someEvent", 3, "arbitrary string");

initialize

()

method

public static function initialize(obj:Object):Void

Player version:

Flash Player 6

Adds event notification and listener management functionality to a given object. This is a static method; it must be called by using the AsBroadcaster class (where someObject is the name of the object to be initialized as an event broadcaster):

AsBroadcaster.initialize(someObject);

This method adds the _listeners property along with the following three methods to the object specified by the obj parameter:

obj.addListener()
obj.removeListener()
obj.broadcastMessage()

Parameters

obj:Object — An object to serve as a broadcasting object.

Example
The following example creates a generic object, someObject, and turns it into an event broadcaster. The output should be the strings shown in the two trace() statements:

var someObject:Object = new Object();         // Creates broadcast object.

var myListener1:Object = new Object();        // Creates listener object.
var myListener2:Object = new Object();        // Creates listener object.

myListener1.someEvent = function() {          // Creates listener method.
    trace("myListener1 received someEvent");
}
myListener2.someEvent = function() {          // Creates listener method.
    trace("myListener2 received someEvent");
}

AsBroadcaster.initialize(someObject);         // Makes someObject an event broadcaster.
someObject.addListener(myListener1);          // Registers myListener1 as listener.
someObject.addListener(myListener2);          // Registers myListener2 as listener.
someObject.broadcastMessage("someEvent");     // Broadcasts the "someEvent" message.

The following example shows how to pass extra arguments to a listener method by using the broadcastMessage() method. The output should be the three strings shown in the three trace() statements, which also include the arguments passed in through the broadcastMessage() method.

var someObject:Object = new Object();

var myListener:Object = new Object();     
myListener.someEvent = function(param1:Number, param2:String) { 
    trace("myListener received someEvent");
    trace("param1: " + param1);
    trace("param2: " + param2);
}

AsBroadcaster.initialize(someObject);     
someObject.addListener(myListener);          
someObject.broadcastMessage("someEvent", 3, "arbitrary string");

removeListener

()

method

public function removeListener(listenerObj:Object):Boolean

Player version:

Flash Player 6

Removes an object from the list of objects that receive event notification messages.

You can call this method only from an object that has been initialized by using the AsBroadcaster.initialize() method.

Parameters

listenerObj:Object — The name of a listener object that is registered to receive event notification from the broadcasting object.

Returns

Boolean — Returns true if the listener object is removed, and false otherwise.

Example
The following example shows how to remove a listener from the list of registered listeners. The following code works if it is added to the first full example in the Examples section of the AsBroadcaster.initialize() entry. The trace() statements are included only to verify that the number of registered listeners is reduced by one after calling the removeListener() method.

trace(someObject._listeners.length);    // Output: 2
someObject.removeListener(myListener1);
trace(someObject._listeners.length);    // Output: 1

Flash CS5 ActionScript 2.0 Language Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Frames No Frames
Class AsBroadcaster	Properties \| Methods

	Method
		addListener(listenerObj:Object):Boolean Registers an object to receive event notification messages.
		broadcastMessage(eventName:String):Void Sends an event message to each object in the list of listeners.
		initialize(obj:Object):Void [static]Adds event notification and listener management functionality to a given object.
		removeListener(listenerObj:Object):Boolean Removes an object from the list of objects that receive event notification messages.