Top Level

Class AsBroadcaster

Object


public class AsBroadcaster
extends 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:

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 Summary
_listeners : Array  [read-only]
A list of references to all registered listener objects.

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


Method Summary
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.
static initialize(obj:Object) : Void
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.

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


Property Detail

_listeners Property

public _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.

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]);
    }
}

See also
AsBroadcaster.initialize()


Method Detail

addListener Method

public 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.

See also
AsBroadcaster.initialize(), AsBroadcaster.removeListener()

broadcastMessage Method

public 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");

See also
AsBroadcaster.initialize(), AsBroadcaster.removeListener()

initialize Method

public static 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);

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 will fail silently.

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

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() {          // Createz 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 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

See also
AsBroadcaster.addListener(), AsBroadcaster.initialize()