.AS File Format – Events and the display list

EventDispatcher

Every object that sends events extends flash.events.EventDispatcher or implements IEventDispatcher. Every display object does.

import flash.display.Sprite;
import flash.events.MouseEvent;

var button:Sprite = new Sprite();
button.graphics.beginFill(0x339933);
button.graphics.drawRoundRect(0, 0, 120, 40, 10);
button.buttonMode = true;
button.addEventListener(MouseEvent.CLICK, onClick);
addChild(button);

function onClick(event:MouseEvent):void {
    trace("clicked at", event.stageX, event.stageY);
}

The event object

The event flow

An event dispatched to a display object that is on the display list travels in three phases:

1. Capture – from the Stage down through each ancestor to the target’s parent. Only listeners added with useCapture true hear it.
2. Target – at the target itself.
3. Bubble – back up from the parent to the Stage, for events whose bubbles is true, such as mouse and keyboard events. ENTER_FRAME, COMPLETE and most others do not bubble.

A listener added without useCapture hears the target and bubble phases. Because of bubbling, one listener on a container can handle clicks on all its children, reading event.target to tell them apart. An event sent to an object that is not a display object on the list, such as a URLLoader, has only the target phase.

Listeners and memory

A listener is a reference from the dispatcher to the function, and through it to the object that owns the function, so an object with listeners on a long-lived dispatcher (the Stage, a timer) is not freed. Removing listeners when they are no longer needed avoids this. With useWeakReference true, the reference does not keep the listener alive; but an anonymous function held only by a weak listener can then be freed and stop being called.

Common events

Custom events

package com.example.events {
    import flash.events.Event;

    public class ScoreEvent extends Event {
        public static const SCORE_CHANGED:String = "scoreChanged";
        public var score:int;

        public function ScoreEvent(type:String, score:int,
                                   bubbles:Boolean = false, cancelable:Boolean = false) {
            super(type, bubbles, cancelable);
            this.score = score;
        }

        override public function clone():Event {
            return new ScoreEvent(type, score, bubbles, cancelable);
        }

        override public function toString():String {
            return formatToString("ScoreEvent", "type", "score");
        }
    }
}

// elsewhere, in a class that extends EventDispatcher or a display object:
dispatchEvent(new ScoreEvent(ScoreEvent.SCORE_CHANGED, points));

The [Event] metadata tag on the dispatching class tells editors and the Flex compiler which events it sends.

The display classes

Working with the display list

An object is drawn only when it is a child, directly or through containers, of the Stage. The order of children is the stacking order, the last on top; the player keeps the indexes packed, with no gaps and no depth numbers as in ActionScript 2.0.

Display properties drop ActionScript 2.0’s underscores and use different scales: x, y, width, height, rotation in degrees, scaleX and scaleY where 1 is full size, alpha from 0 to 1, visible, name, parent, stage, root, mask, filters, blendMode, cacheAsBitmap and transform.

The Stage

The Stage is reached through any display object’s stage property once it is on the list. It holds the player settings: stageWidth, stageHeight, scaleMode, align, frameRate, quality, displayState for full screen, and focus. The main SWF’s document class instance, or its main timeline, is the Stage’s first child and the root of the objects under it.

package {
    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.events.Event;

    public class Main extends Sprite {
        public function Main() {
            if (stage) init();
            else addEventListener(Event.ADDED_TO_STAGE, init);
        }

        private function init(event:Event = null):void {
            removeEventListener(Event.ADDED_TO_STAGE, init);
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;
            addEventListener(Event.ENTER_FRAME, update);
        }

        private function update(event:Event):void {
            // one step of the program each frame
        }
    }
}

Timelines and frame scripts

A MovieClip has a timeline: currentFrame, totalFrames, currentLabel, currentLabels, currentScene and scenes, and the methods play(), stop(), gotoAndPlay(frame), gotoAndStop(frame), nextFrame(), prevFrame(), nextScene() and prevScene(). Frames are counted from 1, or named by label.

Code typed on a keyframe in Flash is a frame script. Flash compiles all the frame scripts of a timeline into methods of that timeline’s class (the document class, a symbol’s linked class, or a class Flash generates such as MainTimeline), named frame1, frame2 and so on, and has the constructor register them with addFrameScript. That method of MovieClip is not in Adobe’s documentation, but it works the same from any code:

addFrameScript(frameIndex:int, script:Function [, frameIndex, script]…):void

The index counts from 0, so frame 1 is index 0, and passing null removes a script. Each frame script runs when the playhead enters its frame, after the frame’s objects are created.

public class Intro extends MovieClip {
    public function Intro() {
        addFrameScript(0, onFirstFrame, totalFrames - 1, onLastFrame);
    }
    private function onFirstFrame():void { trace("started"); }
    private function onLastFrame():void { stop(); dispatchEvent(new Event(Event.COMPLETE)); }
}

Each frame of a playing SWF goes through the same order: enterFrame is dispatched, new objects on the frame are created and frameConstructed is dispatched, the frame scripts run, exitFrame is dispatched, and the stage is drawn.