Overview

Summary

Contents

• Overview
• Summary
• Concept
• Event types
• Native JSFL event model limitations
• Event API
• add(type, callback, name, scope)
• remove(type, name)
• removeAll(type)
• get(type, name)
• Event classes
• DocumentEvent(type)
• LayerEvent()
• FrameEvent()
• MouseEvent()

Concept

Flash's standard event mechanism is a simple callback-based event model, which allows the developer to add events via string, and have a callback (event handler) called when the event fires:

var eventId = fl.addEventListener("documentClosed", onDocumentClosed);

However, there are a few problems with the standard Flash event handler implementation:

• It's impossible to keep track of (and therefore remove) listener ids between external script executions (i.e. in development)
• No information about the event is passed to the event handler function
• There's no overall management of registered event handlers

xJSFL's Event library and classes attempt to answer these shortcomings with a standard Event model and Event classes similar to AS3's, as well as the ability to add, remove and get events by event and type - and all between external calls.

Usage

Adding an event handler to fire on an event

The main difference with registering an event handle function between JSFL and xJSFL is that with xJSFL you supply the eventId you want to keep track of:

function onDocumentChanged(event)
{
    trace(event.document.name);
}

xjsfl.events.add(DocumentEvent.CHANGED, onDocumentChanged, 'onDocumentChanged');

Note that the function name and the eventId name are not related, nor do they have to be the same. It is the string name that is used to add and remove the callback - the callback itself is merely stored as a reference.

What to do within the event handler

Once the handler is added, and when an appropriate event is fired within Flash, the handler is called and from within you have access to the properties at the time of the event, via the event object.

Bear in mind though that due to some inherent limitations of the Flash event model, these cannot always be relied on to return a true state of the Flash environment at the time of the event.

Updating and removing the event handler

When it comes to updating the event handler you can simply add it again with the same name, or if at any point you want to remove the event handler, you simply call the remove() method with the type and name of the previously-added handler:

xjsfl.events.remove(DocumentEvent.CHANGED, 'onDocumentChanged');

Event types

Rather than simply calling an event handler function with no information about the event that took place, the xJSFL Event model defines specific Event classes, instances of which are passed to event handler functions in a manner already familiar to AS3 developer.

These event instances have both a specific type, as well as a common name property that maps directly to the standard eventType strings as accepted by the standard fl.addEventlistener() function. Note however that the xJSFL Event constant names are slightly differently to the Flash event strings.

Additional properties are specific to each event class.

Native JSFL event model limitations

The JSAPI appears to fire a frameChanged event before it has updated the document / timeline properties, which results in frame Events reporting the previous document and timeline.

At the moment, I don't know how to solve this. I've experimented with lastParam properties, comparing the Date of the callback, firing events in order with pre and post handlers, attempting to force a document update by calling flash or document methods first, but so far every route has been a dead end. It may just be that it's not possible.

Other limitations include:

• Although "frameChanged" fires when you edit a new symbol, the document properties do not update in time, so again, you end up with the wrong document/timeline data fed into the Event.
• timeline.getSelectedframes() often returns nothing from within an event handler, so is effectively useless for interactive tools relying on the current frame selection.
• Multiple events can be fired for what seem like single events to the user - for example, selecting the same layer fires a layer event once, but selecting a new layer fires a layer event twice, with timeline.currentLayer reporting the same layer for both events.

If you can live with these fairly annoying limitations, you may be able to get some mileage out of at least the Document, Layer & Mouse events.

Event API

The event API is the central place to add and remove event handler functions.

function onDocumentChanged(event)
{
    trace(event.document.name);
}
xjsfl.events.add(DocumentEvent.CHANGED, onDocumentChanged, 'onDocumentChanged');

// On changing the current document
Untitled-2

xjsfl.events.add(DocumentEvent.CHANGED, handlers.onDocumentChanged, 'onDocumentChanged', handlers);

xjsfl.events.add(DocumentEvent.CHANGED, this.onDocumentChanged, 'myModule.onDocumentChanged', this);

xjsfl.events.remove(DocumentEvent.CHANGED, 'onDocumentChanged');

xjsfl.events.remove('documentHandler');

xjsfl.events.removeAll(DocumentEvent.CHANGED);

xjsfl.events.removeAll();

var callback = xjsfl.events.get(MouseEvent.MOVE, 'onMouseMove');
trace(callback);

function onMouseMove(event)
{
    trace(event);
}

Event classes

This section describes the Event classes that will be dispatched from the main xjsfl.event library.

function onDocumentNew(event)
{
    trace(event.document.name);
}
xjsfl.events.add(DocumentEvent.NEW, onDocumentNew);

// On creating a new document
Untitled-1

function onLayerChanged(event)
{
    trace(event);
}
xjsfl.events.add(LayerEvent.CHANGED, onLayerChanged);

// On changing layer, or creating a new layer
[object LayerEvent timeline="Scene 1" layer="Layer 2"]

function onFrameChanged(event)
{
    trace(event);
}
xjsfl.events.add(FrameEvent.CHANGED, onFrameChanged);

// On changing frame, or creating a new frame
[object FrameEvent timeline="Scene 1" layer="Layer 2" frame="11"]

function onMouseMove(event)
{
    trace(event);
}
xjsfl.events.add(MouseEvent.MOVE, onMouseMove);

// On moving the mouse
[object MouseEvent x="424.95" y="7" shift="false" ctrl="false" alt="false"]