PreviousNext

Using event listeners

Event listeners let an object, called a listener object, receive events generated by another object, called a broadcaster object. The broadcaster object registers the listener object to receive events generated by the broadcaster. For example, you could register a movie clip object to receive onResize notifications from the Stage, or a button instance could receive onChanged notifications from a text field object. You can register multiple listener objects to receive events from a single broadcaster, and you can register a single listener object to receive events from multiple broadcasters.

The event model for event listeners is similar to that of event handlers (see Using event handler methods), with two main differences:

To use event listeners, you create a listener object with a property that has the name of the event being generated by the broadcaster object. You then assign a function to the event listener that responds in some way to the event. Lastly, you call addListener() on the object that's broadcasting the event, passing it the name of the listener object. The following code outlines the event listener model.

listenerObject.eventName = function(){
  // your code here
};
broadcastObject.addListener(listenerObject);

The specified listener object can be any object, such as a movie clip or button instance on the Stage, or an instance of any ActionScript class. The event name is an event that occurs on broadCastObject, which then broadcasts the event to listenerObject. You can register multiple listeners to one event broadcaster.

The following example shows how to use the Selection.onSetFocus event listener to create a simple focus manager for a group of input text fields. In this case, the border of the text field that receives keyboard focus is enabled (displayed), and the border of the text field that lost focus is disabled.

To create a simple focus manager with event listeners:

  1. Using the Text tool, create a text field on the Stage.
  2. Select the text field and, in the Property inspector, select Input from the Text Type pop-up menu, and select the Show Border Around Text option.
  3. Create another input text field below the first one.

    Make sure the Show Border Around Text option is not selected for this text field. Continue to create input text fields if desired.

  4. Select Frame 1 in the Timeline and open the Actions panel (Window > Development Panels > Actions).
  5. To create an object that listens for focus notification from the Selection class, enter the following code in the Actions panel: 
    var focusListener = new Object();
focusListener.onSetFocus = function(oldFocus_txt, newFocus_txt) {
  oldFocus_txt.border = false;
  newFocus_txt.border = true;
}

    This code creates a new (generic) ActionScript object named focusListener. This object defines for itself an onSetFocus property, to which it assigns a function. The function takes two parameters: a reference to the text field that lost focus, and one to the text field that gained focus. The function sets the border property of the text field that lost focus to false, and sets the border property of the text field that gained focus to true.

  6. To register the focusListener object to receive events from the Selection object, add the following code to the Actions panel: 
    Selection.addListener(focusListener);
  7. Test the movie (Control > Test Movie), click in the first text field, and press Tab to switch focus between fields.

To unregister a listener object from receiving events, you call the removeListener() method of the broadcaster object, passing it the name of the listener object.

broadcastObject.removeListener(listenerObject);

Event listeners are available to objects of the following ActionScript classes: Key, Mouse, MovieClipLoader, Selection, TextField, and Stage. For a list of event listeners available to each class, see these class entries in ActionScript Dictionary Overview.

PreviousNext