SFL is based around a Document Object Model (DOM) that exposes a hierarchy of Objects, which represent the structure of a Flash document in the form of a hierarchical tree, very similar in nature to a family tree. Each object allows you to dynamically access and update the structure of a Flash document. The key to learning to write your own Flash extensions is to understand the Flash DOM and thus the first article in this series will explain the DOM in detail.

Types of Flash Documents
Flash MX 2004, works with two types of documents, the first is the standard timeline-based document that users of previous versions of Flash are familiar with and the second is screen-based documents, which are new in Flash MX 2004. Screen-based documents use a different metaphor for organizing your movies and you will know them as Form Applications and Slide Presentations.

The DOM of a screen-based document differs slightly from that of a timeline-based document but because timeline-based documents are far more common, I will only cover their DOM in this article.

Anatomy of a Flash Document
To begin with, I want you to think about each of the different parts of a Flash document. Flash documents are made up of:

• Timelines
• Layers
• Frames
• Symbols
• Shapes
• Textfields
• Library

Different types of symbols are stored in the library:

• Movieclips
• Buttons
• Graphics
• Bitmaps
• Sounds
• Videos
• Components

Timeline-based documents have a library and one or more timelines (Scenes). Movieclips, buttons, components, and graphics have their own timelines. Timelines contain layers, layers contain frames, and key frames contain instances of symbols from the library, shapes, and textfields.

The Flash DOM represents this hierarchy and each of those separate elements of a Flash document in the form of objects. So there is a unique object for each layer in a Flash document and there is also a unique object for every frame in a Flash document, etc.

These objects have properties that describe that particular element; so for example all layer objects have a ‘name’ property that contains the name of that particular layer:

Figure 1. Timeline: A Flash timeline object with one layer is shown.

Figure 1 shows a timeline, which contains one layer, this layer has a name of ‘Layer Name’. So in JSFL, we can access the name of that particular layer, using:

theLayerObject.name; 

Each separate type of object may also have associated methods, which manipulate that particular object in its visual form in the Flash IDE; so for example, all timeline objects have a method called ‘deleteLayer’ that removes a particular layer from that particular timeline.So in JSFL, we can get Flash to delete the first layer of a timeline using:

theTimelineObject.deleteLayer(0); 

Object Relationships
These objects have a parent/child relationship. So for example, each layer object contains references to its child frames, which are grouped together in an array. It is therefore said that a frame object is a child of a layer object. The parent of a layer object is the timeline object, which represents the timeline in which that particular layer resides. These relationships are similar in practice to a nested movieclip hierarchy in a Flash movie.

When a JSFL script is executed, an object is created for each separate element in every Flash document that is presently open in the Flash IDE. Thus your scripts can refer to any element of any of the open Flash documents using dot syntax to traverse that particular document’s DOM.

The parent/child relationship between the different elements of a Flash document and the hierarchical tree structure is shown in Figure 2.

Figure 2. Object Relationship Diagram: The Flash Document Object Model.The parent/child relationship between the different parts of a Flash Document.

Think of each section on the diagram as a separate class or type of object. Child objects that are the same color as their parent are simply sub classes of the parent, or an extension the parent object type. So for example, in the diagram above, Shape is a subclass or extension of the Element object, similarly FontItem is a subclass or extension of the Item Object.

You will also notice, that there are some labels pointing to the intersections between various objects. If an intersection represents a subclass or object relationship (the color of the parent and children are the same), then the label will contain the property you need to access to determine the type of object you are working with.

If however, the parent child relationship represents an object type, which can be accessed as a child of the parent, then the label will tell you the property that you need to access to reference each child element. So for example, the relationship between the Library object and the Item object is not a subclass relationship as the colors of parent and child are different. Thus the label tells us, that we can access the child Items of the Library object, using the library.items property, which is an array containing a collection of Item objects.

Here is a simple example: let’s say I have a Flash document that contains one Movieclip on the stage, which is on the first frame of the first layer of the first scene. To access that Movieclip’s object, I would have to traverse the DOM using dot syntax as follows:

theMovieClipObject=flash.documents[0].timelines[0].layers[0].frames[0].elements[0] 

In this particular example, I know that the one and only element on the stage is a Movieclip, but there will be times when there will be numerous elements on the stage. As Figure 2 illustrates, an element can either be of type Shape, Text, or Symbol, and the properties available to those objects differ. Thus I need to determine what type of element I am working with, and to do that I use the ‘elementType’ property:

theElement=flash.documents[0].timelines[0].layers[0].frames[0].elements[0]	elementType=theElement.elementType

The elementType property can have three possible values, “shape”, “text” or “symbol.” If the element is a movieclip, graphic, or button, I know I am working with a Symbol object and the value of the elementType property will be “symbol.” Which means that our element object will contain all the properties that that Symbol object contains.

Top of the Tree
A parent/child relationship has to stop somewhere, therefore there is always one root object?the “top of the tree” or the “daddy of daddies” so to speak. In the Flash DOM, the root object is the object that represents the Flash Application.

This object is always accessible in JSFL scripts and it goes by the name ‘flash’. It can also be accessed using the shorter name ‘fl.’

The root object contains the child objects that represent each Flash document presently open in the Flash IDE. Each of those document objects are grouped together in a property called ‘documents’ that is an array:flash.documentsSo to access the object of the first document open in the Flash IDE with a JSFL script, I would use:firstDocumentObject=flash.documents[0]; The ‘flash’ object also has various methods, which allow you to manipulate the actual Flash Application and mimic the actual functionality the Flash Application provides. For example, in the Flash IDE it is possible to close the Flash Application by simply opening the File menu and then selecting the Quit option. We can do the same thing with JSFL in our scripts, by calling: flash.quit();In the Flash IDE, it is also possible to close the currently focused document simply by opening the File menu and selecting the Close option. We can again, do the same thing with JSFL in our scripts, by calling:flash.closeDocument(theDocumentObject); For a full list of all the various objects and their associated, methods and properties checkout Macromedia’s official JSAPI documentation.