The Flash Document Object Model

The Flash Document Object Model (DOM) for the Flash JavaScript API consists of a set of top-level functions (see "Top-Level Functions and Methods" on page 23) and two top-level objects the FLfile object and the flash object (fl). Each object is guaranteed to be available to a script because it always exists when the Flash authoring environment is open. For more information, see FLfile object and flash object (fl).

When referring to the flash object, you can use flash or fl. For example, to close all open files, you can use either of the following statements:

flash.closeAll(); fl.closeAll();

The flash object contains the following child objects:

Object	How to access
componentsPanel object	Use fl.componentsPanel to access the componentsPanel object. This object corresponds to the Components panel in the Flash authoring environment.
Document object	Use fl.documents to retrieve an array of all the open documents; use fl.documents[index] to access a particular document; use fl.getDocumentDOM() to access the current document (the one with focus).
drawingLayer object	Use fl.drawingLayer to access the drawingLayer object.
Effect object	Use fl.effects to retrieve an array of effect descriptors that corresponds to the effects registered when Flash starts; use fl.effects[index] to access a particular effect; use fl.activeEffect to access the effect descriptor for the current effect being applied.
Math object	Use fl.Math to access the Math object.
outputPanel object	Use fl.outputPanel to access the outputPanel object. This object corresponds to the Output panel in the Flash authoring environment.
Project object	Use fl.getProject() to return a Project object for the currently open project.
Tools object	Use fl.tools to access an array of Tools objects.
XMLUI object	Use fl.xmlui to access an XML User Interface (XMLUI) object. The XMLUI object provides the ability to get and set properties of an XMLUI dialog box.

The Document object

An important property of the top-level flash object is the fl.documents property. (See fl.documents property.) The fl.documents property contains an array of Document objects that each represent one of the FLA files currently open in the authoring environment. The properties of each Document object represent most of the elements that a FLA file can contain. Therefore, a large portion of the DOM is composed of child objects and properties of the Document object. For more information, see Document object.

To refer to the first open document, for example, use the statement flash.documents[0] or fl.documents[0]. The first document is the first Flash document that was opened during the current session in the authoring environment. When the first opened document is closed, the indexes of the other open documents are decremented.

To find a particular document's index, use flash.findDocumentIndex(nameOfDocument) or fl.findDocumentIndex(nameOfDocument). See fl.findDocumentIndex().

To access the document that is currently focused, use the statement flash.getDocumentDOM() or fl.getDocumentDOM(). See fl.getDocumentDOM(). The latter is the syntax used in most of the examples in this document.

To find a particular document in the fl.documents array, iterate through the array and test each document for its document.name property. See fl.documents and document.name.

All the objects in the DOM that aren't listed in the previous table (see "The Flash Document Object Model" on page 14) are accessed from the Document object. For example, to access the library of a document, you use the document.library property, which retrieves a library object:

fl.getDocumentDOM().library

To access the array of items in the library, you use the library.items property; each element in the array is an Item object:

fl.getDocumentDOM().library.items

To access a particular item in the library, you specify a member of the library.items array:

fl.getDocumentDOM().library.items[0]

In other words, the library object is a child of the Document object, and the Item object is a child of the library object. For more information, see document.library, library object, library.items, and Item object.

Specifying the target of an action

Unless otherwise specified, methods affect the current focus or selection. For example, the following script doubles the size of the current selection because no particular object is specified:

fl.getDocumentDOM().scaleSelection(2, 2);

In some cases, you might want an action to specifically target the currently selected item in the Flash document. To do this, use the array that the document.selection property contains (see document.selection). The first element in the array represents the currently selected item, as shown in the following example:

var accDescription = fl.getDocumentDOM().selection[0].description;

The following script doubles the size of the first element on the Stage that is stored in the element array, instead of the current selection:

var element =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0]; if (element) {   element.width = element.width*2;   element.height = element.height*2; }

You can also do something such as loop through all the elements on the Stage and increase the width and height by a specified amount, as shown in the following example:

var elementArray =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements;   for (var i=0; i < elementArray.length; i++) {     var offset = 10;     elementArray[i].width += offset;     elementArray[i].height += offset;   }

Summary of the DOM structure

The following list displays the DOM structure in outline format. Numbers at the beginning of each line represent the level of an object. For example, an object preceded by "03" is a child of next highest "02" object, which, in turn, is a child of the next highest "01" object.

In some cases, an object is available by specifying a property of its parent object. For example, the document.timelines property contains an array of Timeline objects (see document.timelines and Timeline object). These properties are noted in the following outline.

Finally, some objects are subclasses of other objects, rather than being children of other objects. An object that is a subclass of another object has methods and/or properties of its own in addition to the methods and properties of the other object (the superclass). Subclasses share the same level in the hierarchy as their superclass. For example, the Item object is a superclass of the BitmapItem object (see Item object and BitmapItem object). These relationships are illustrated in the following outline:

01 Top-Level Functions and Methods

01 FLfile object

01 flash object (fl)

02 componentsPanel object

02 Document object (fl.documents array)

03 Filter object

03 Matrix object

03 Fill object

03 Stroke object

03 library object

04 Item object (library.items array)

04 BitmapItem object (subclass of Item object)

04 folderItem object (subclass of Item object)

04 fontItem object (subclass of Item object)

04 SoundItem object (subclass of Item object)

04 SymbolItem object (subclass of Item object)

04 VideoItem object (subclass of Item object)

03 Timeline object (document.timelines array)

04 Layer object (timeline.layers array)

05 Frame object (layer.frames array)

06 Element object (frame.elements array)]

07 Matrix object (Element.matrix)

06 Instance object (abstract class, subclass of Element object)

06 BitmapInstance object (subclass of Instance object)

06 CompiledClipInstance object (subclass of Instance object)

06 ComponentInstance object (subclass of SymbolInstance object)

07 Parameter object (componentInstance.parameters)

06 SymbolInstance object (subclass of Instance object)

06 Text object (subclass of Element object)

07 TextRun object (text.textruns array)

08 TextAttrs object (textrun.textAttrs array)

06 Shape object (subclass of Element object)

07 Contour object (shape.contours array)

08 HalfEdge object

09 Vertex object

09 Edge object

07 Edge object (shape.edges array)

08 HalfEdge object

09 Vertex object

09 Edge object

07 Vertex object (shape.vertices array)

08 HalfEdge object

09 Vertex object

09 Edge object

03 ScreenOutline object

04 Screen object (screenOutline.screens array)

05 Parameter object (screen.parameters array)

02 drawingLayer object

03 Path object

04 Contour object

02 Effect object (fl.effects array)

02 Math object

02 outputPanel object

02 Project object

03 ProjectItem object (project.items array)

02 Tools object (fl.tools array)

03 ToolObj object (tools.toolObjs array)

02 XMLUI object