User Guide

Event listeners 363
The priority parameter of the addEventListener() method is not an official part of the
DOM Level 3 event model. It is included in ActionScript 3.0 to provide you with more
flexibility in organizing your event listeners. When you call
addEventListener(), you can
set the priority for that event listener by passing an integer value as the
priority parameter.
The default value is 0, but you can set it to negative or positive integer values. The higher the
number, the sooner that event listener will be executed. Event listeners with the same priority
are executed in the order that they were added, so the earlier a listener is added, the sooner it
will be executed.
The
useWeakReference parameter allows you to specify whether the reference to the listener
function is weak or normal. Setting this parameter to
true allows you to avoid situations in
which listener functions persist in memory even though they are no longer needed. Flash
Player uses a technique called garbage collection to clear objects from memory that are no
longer in use. An object is considered no longer in use if no references to it exist. The garbage
collector disregards weak references, which means that a listener function that has only a weak
reference pointing to it is eligible for garbage collection.
Removing event listeners
You can use the removeEventListener() method to remove an event listener that you no
longer need. It is a good idea to remove any listeners that will no longer be used. Required
parameters include the
eventName and listener parameters, which are the same as the
required parameters for the
addEventListener() method. Recall that you can listen for
events during all event phases by calling
addEventListener() twice, once with useCapture
set to
true, and then again with it set to false. To remove both event listeners, you would
need to call
removeEventListener() twice, once with useCapture set to true, and then
again with it set to
false.
Dispatching events
The dispatchEvent() method can be used by advanced programmers to dispatch a custom
event object into the event flow. The only parameter accepted by this method is a reference to
an event object, which must be an instance of the Event class or a subclass of the Event class.
Once dispatched, the
target property of the event object is set to the object on which
dispatchEvent() was called.