Overview

Summary

The iterators library provides a standardized and object-oriented approach to iterating over-and-into Documents, Timelines, Layers, (Key)Frames, and Elements.

Note: to loop over and modify only Stage elements or Library items see the ElementCollection and ItemCollection classes.

Contents

• Overview
• Summary
• Usage
• Concept
• Processing multiple levels
• Halting or skipping processing of levels / branches
• API
• documents(documents, documentCallback, itemCallback, layerCallback, frameCallback, elementCallback)
• items(context, itemCallback, layerCallback, frameCallback, elementCallback)
• layers(context, layerCallback, frameCallback, elementCallback)
• frames(context, frameCallback, elementCallback)
• elements(context, elementCallback)

Usage

Instead of writing and managing potentially fiddly nested loop code to handle DOM traversal, you now leave the looping logic to the Iterators API, and delegate the processing functionality to your own custom callback functions:

function processElement(element, index, elements, context)
{
    // your processing code here
}

Each of the functions in the API accepts multiple callbacks, progressively down the chain, until you reach Element level:

Iterators.items(context, itemCallback, layerCallback, frameCallback, elementCallback);

You can start processing at any level (using the relevant method) and finish at any (lower) level, depending on whether a callback for a level has been supplied. You can choose to skip intermediate levels, for example, you can provide callbacks for Layers and Elements, but choose to skip processing Frames (although they will be iterated over to get to Elements).

Note that many of the Iterator methods accept a Context object as their first parameter, as a reference from which to start iteration from. See the Context API for more information.

Concept

To demonstrate the differences between the two approaches in code, here is a typical JSFL Layers > Frames > Elements loop:

var timeline = fl.getDocumentDOM().getTimeline();
for(var i = 0; i < timeline.layers.length; i++)
{
    var layer = timeline.layers[i];
    for(var j = 0; j < layer.frames.length; j++)
    {
        var frame = layer.frames[j];
        if(j == frame.startFrame)
        {
            var elements = frame.elements;
            for(var k = 0; k < elements.length; k++)
            {
                var element = elements[k];
                // do something with element
            }
        }
    }
}

This kind of code is probably familiar to most Flash developers, and although it looks pretty sstandard; it's not particularly flexible, and is impossible to reuse in an object oriented manner.

Using the Iterators API however, we delegate the drill down through the DOM to the library, whilst we handle only the processing, with a simple callback:

function processElement(element, index, elements, context)
{
    trace(element.name);
}

Iterators.layers(true, null, null, processElement);

green_star
green_star
green_star
grey_oval
red_square
purple_oval

Processing multiple levels

In the previous example, only the Element elements were processed, using a single callback. Iterators gives you the option to process some or all of the elements in a chain, iterating down to the last element-type specified. To process an element at any level, you simply supply a callback to the relevant method parameter:

function processLayer(layer, index, layers, context)
{
    trace('> ' + layer.name);
}

function processFrame(frame, index, frames, context)
{
    trace('    > ' + frame.startFrame);
}

function processElement(element, index, elements, context)
{
    trace('        > ' + element.name);
}

Iterators.layers(Context.create(), processLayer, processFrame, processElement);

>actions
    > 0
>Layer 4
    > 0
        "green_star"
    > 9
        "green_star"
    > 14
        "green_star"
>Layer 3
    > 0
    > 3
        "grey_oval"
>Layer 2
    > 0
        "red_square"
>Layer 1
    > 0
    > 5
        "purple_oval"

Halting or skipping processing of levels / branches

There is one last bit of functionality that the Iterators API supports, and that's some basic influence over the internal loop logic of the Iterators looping methods.

By returning true or false values (rather than no return value) from the callback functions, you can stop or skip further processing:

• Return a Boolean true to cancel all loop iteration, right back up to the top of the chain - for example when you've found an item you were using iteration to locate
• Return a Boolean false to skip the current branch of iteration - for example you want to skip the current layer (and subsequently its frames and elements)

The following example illustrates this in code, iterating through all Layers, Frames and Elements, attempting to find an Symbol Item called 'red_square', but skipping guide layers as it processes:

function processLayer(layer, index, layers, context)
{
    if(layer.layerType == 'guide')
    {
        return false;
    }
}

function processElement(element, index, elements, context)
{
    if(element.name == 'red_square')
    {
        $selection = element;
        return true;
    }
}

var state = Iterators.layers(Context.create(), processLayer, null, processElement);
if(state)
{
	alert($selection[0].name + ' selected')
}

If you run this code and have a Symbol Item called 'red_square' in a frame on your timeline you should get an alert box, and the item should be selected.

API

function documentCallback(document, index, documents, context)
{
    var collection = $$('star');
    if(collection.elements.length)
    {
        fl.setActiveWindow(document);
        collection.reveal().select();
        trace('Found in ' + document.name);
        return true; // note that true is returned to halt the Iterator processing!
    }
    trace('Not found in ' + document.name);
}
Iterators.documents(true, documentCallback);

Not found in snippets 03.fla
Not found in library items.fla
Found in frames and shapes.fla

findItemInOpenDocuments('star');

function itemCallback(item, index, items, context)
{
	trace('Updating:' + item.name)
}

function layerCallback(layer, index, layers, context)
{
	if(/^(mask|masked|guide)$/.test(layer.layerType))
	{
		layer.locked = true;
	}
	context.goto(); // update layer display by updating the playhead
}

Iterators.items(true, itemCallback, layerCallback)

Updating:Symbol 1
Updating:Symbol 2
Updating:Symbol 3
...

function layerCallback(layer, index, layers, context)
{
	context.setFrame(0);
	if(context.frame.elements.length)
	{
		layer.name = context.frame.elements[0]['name'] || layer.name;
	}
}

Iterators.layers(layerCallback);

function frameCallback(frame, index, frames, context)
{
	frame.motionTweenSync = true;
}

Iterators.frames('animation', frameCallback);

var keyframes = Context.create().setLayer('animation').keyframes;
for each(var frame in keyframes)
{
     frameCallback(frame);
}

function elementCallback(element)
{
	trace(element.name);
}
elements($selection, elementCallback);	

Symbol_1
Symbol_2
Symbol_3