MACROMEDIA FLASH 8-EXTENDING FLASH User manual

Extending Flash

Trademarks
1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central,
ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite,
FlashPaper, Flash Video Encoder, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder,
Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit,
Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in
the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases
mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and
may be registered in certain jurisdictions including internationally.
Third-Party Information
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com).
Sorenson™ Spark™ video compression and decompression technology licensed from
Sorenson Media, Inc.
Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved.
Macromedia Flash 8 video is powered by On2 TrueMotion video technology. © 1992-2005 On2 Technologies, Inc. All Rights
Reserved. http://www.on2.com.
Visual SourceSafe is a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.
Copyright © 2005 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form in whole or in part without written approval from
Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which
this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole
purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be
printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation,
commercial purposes, such as selling copies of this documentation or providing paid-for support services.
Acknowledgments
Project Management: Sheila McGinn
Writing: Jay Armstrong
Managing Editor: Rosana Francescato
Lead Editor: Lisa Stanziano
Editing: Geta Carlson, Evelyn Eldridge, Mark Nigara
Production Management: Patrice O’Neill, Kristin Conradi, Yuko Yagi
Media Design and Production: Adam Barnett, Aaron Begley, Paul Benkman. John Francis, Geeta Karmarkar, Masayo Noda,
Paul Rangel, Arena Reed, Mario Reynoso
Special thanks to Jody Bleyle, Mary Burger, Lisa Friendly, Stephanie Gowin, Bonnie Loo, Mary Ann Walsh, Erick Vera, the beta
testers, and the entire Flash and Flash Player engineering and QA teams.
First Edition: September 2005
Macromedia, Inc.
601 Townsend St.
San Francisco, CA 94103

3
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Overview of the Macromedia Flash JavaScript API. . . . . . . . . . . . . . . . .5
What’s new in the JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Flash Document Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Sample implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 1: Top-Level Functions and Methods. . . . . . . . . . . . . . . 23
Chapter 2: Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
BitmapInstance object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
BitmapItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CompiledClipInstance object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
ComponentInstance object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
componentsPanel object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Contour object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Document object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
drawingLayer object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Edge object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Effect object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Element object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Fill object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Filter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
flash object (fl). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
FLfile object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
folderItem object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
fontItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Frame object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
HalfEdge object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Instance object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Item object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Layer object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
library object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Math object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Matrix object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

4Contents
outputPanel object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Parameter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
Path object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Project object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
ProjectItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Screen object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366
ScreenOutline object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Shape object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
SoundItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Stroke object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
SymbolInstance object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
SymbolItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Text object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
TextAttrs object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
TextRun object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .466
Timeline object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468
ToolObj object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Tools object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Vertex object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
XMLUI object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
VideoItem object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Chapter 3: C-Level Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . 533
Integrating C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .534
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
The C-level API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

5
Introduction
As a Macromedia Flash user, you may be familiar with ActionScript, which lets you create
scripts that execute at runtime in Macromedia Flash Player. The Flash JavaScript application
programming interface (JavaScript API) is a complementary programming tool that lets you
create scripts that run in the authoring environment.
This document describes the objects, methods, and properties available in the JavaScript API.
It assumes that you know how to use the documented commands when working in the
authoring environment. If you have a question about what a particular command does, use
other documents in Flash Help, such as Using Flash, to find that information.
This document also assumes that you are familiar with JavaScript or ActionScript syntax and
with basic programming concepts such as functions, parameters, and data types.
This chapter contains the following sections:
Overview of the Macromedia Flash JavaScript API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
What’s new in the JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Flash Document Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Sample implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Overview of the Macromedia Flash
JavaScript API
The ActionScript language lets you write scripts to perform actions in the Flash Player
environment (that is, while a SWF file is playing). The Flash JavaScript API lets you write
scripts to perform several actions in the Flash authoring environment (that is, while a user has
the Flash program open). These scripts can be used to help streamline the authoring process.
For example, you can write scripts to automate repetitive tasks, add custom tools to the Tools
panel, or add timeline effects.

6Introduction
The Flash JavaScript API is designed to resemble the Macromedia Dreamweaver and
Macromedia Fireworks JavaScript API (which were designed based on the Netscape JavaScript
API). The Flash JavaScript API is based on a Document Object Model (DOM), which allows
Flash documents to be accessed using JavaScript objects. The Flash JavaScript API includes all
elements of the Netscape JavaScript API, plus the Flash DOM. These added objects and their
methods and properties are described in this document. You can use any of the elements of
the native JavaScript language in a Flash script, but only elements that make sense in the
context of a Flash document will have an effect.
The JavaScript API also contains a number of methods that let you implement extensibility
using a combination of JavaScript and custom C code. For more information, see Chapter 3,
“C-Level Extensibility,” on page 533.
The JavaScript interpreter in Flash is the Mozilla SpiderMonkey engine, version 1.5, which is
available on the web at www.mozilla.org/js/spidermonkey/. SpiderMonkey is one of the two
reference implementations of the JavaScript language developed by Mozilla.org. It is the same
engine that is embedded in the Mozilla browser.
SpiderMonkey implements the core JavaScript language as defined in the ECMAScript
(ECMA-262) edition 3 language specification and it is fully compliant with the specification.
Only the browser-specific host objects, which are not part of the ECMA-262 specification, are
not supported. Similarly, many JavaScript reference guides distinguish between core
JavaScript and client-side (browser-related) JavaScript. Only core JavaScript applies to the
Flash JavaScript interpreter.
Creating JSFL files
You can use Macromedia Flash 8 or your preferred text editor to write and edit Flash
JavaScript (JSFL) files. If you use Flash, these files have a .jsfl extension by default.
You can also create a JSFL file by selecting commands in the History panel and then clicking
the Save button in the History panel or selecting Save As Command from the options pop-up
menu. The command (JSFL) file is saved in the Commands folder (see “Saving JSFL files”
on page 7). You can then open the file and edit it the same as any other script file.
The History panel provides some other useful options as well. You can copy selected
commands to the Clipboard, and you can view JavaScript commands that are generated while
you are working in Flash.

Overview of the Macromedia Flash JavaScript API 7
To copy commands from the History panel to the Clipboard:
1. Select one or more commands in the History panel.
2. Do one of the following:
■Click the Copy button.
■Select Copy Steps from the options pop-up menu.
To view JavaScript commands in the History panel:
■Select View > JavaScript in Panel from the options pop-up menu.
Saving JSFL files
You can have JSFL scripts available within the Flash authoring environment by storing them
in one of several folders within the Configuration folder. By default, the Configuration folder
is in the following location:
■Windows 2000 or Windows XP:
boot drive\Documents and Settings\user\Local Settings\Application Data\Macromedia\
Flash 8\language\Configuration\
■Mac OS X:
Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/
language/Configuration/
To determine the location of the Configuration folder, use fl.configDirectory or
fl.configURI.
Within the Configuration folder, the following folders can contain scripts that you can access
in the authoring environment: Behaviors, Commands (for scripts that appear on the
Commands menu), Effects (for timeline effects), JavaScript (for scripts used by Script Assist),
Tools (for extensible tools in the Tools panel), and WindowSWF (for panels that appear in the
Windows menu). This document focuses on scripts used for commands, effects, and tools.
If you edit a script in the Commands folder, the new script is immediately available in Flash.
If you edit a script for an effect or extensible tool, you have to close and restart Flash, or else
use the fl.reloadEffects() or fl.reloadTools() command. However, if you used a
script to add an extensible tool to the Tools panel and you then edit the script, you must
either remove and then add the tool to the Tools panel again, or else close and restart Flash for
the revised tool to be available.

8Introduction
There are three locations where you can store command, effect, and tool files so they can be
accessed in the authoring environment.
■For scripts that will appear as items in the Commands menu, save the JSFL file in the
Commands folder in the following location:
■Windows 2000 or Windows XP:
boot drive\Documents and Settings\user\Local Settings\Application
Data\Macromedia\ Flash 8\language\Configuration\Commands
■Mac OS X:
Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/
language/Configuration/Commands
■For scripts that will appear as extensible tools in the Tools panel, save the JSFL file in the
Tools folder in the following location:
■Windows 2000 or Windows XP:
boot drive\Documents and Settings\user\Local Settings\Application
Data\Macromedia\Flash 8\ language\Configuration\Tools
■Mac OS X:
Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/
language/Configuration/Tools
■For scripts that will appear as timeline effects in the Effects panel, save the JSFL file in the
Effects folder in the following location:
■Windows 2000 or Windows XP:
boot drive\Documents and Settings\user\Local Settings\Application
Data\Macromedia\Flash 8\ language\Configuration\Effects
■Mac OS X:
Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/
language/Configuration/Effects
If a JSFL file has other files that go with it, such as XML files, they should be stored in the
same directory as the JSFL file.

Overview of the Macromedia Flash JavaScript API 9
Running JSFL files
There are several ways to run JSFL files. The most common ways are discussed in this section.
To run a script that is in the Commands folder, do one of the following:
■Select Commands > Script Name.
■Use a keyboard shortcut that you have assigned to the script. To assign a keyboard
shortcut, use Edit > Keyboard Shortcuts and select Drawing Menu Commands from the
Commands pop-up menu. Expand the Commands node in the menu tree to view a list of
available scripts.
To run a command script that is not in the Commands folder, do one of the
following:
■From the authoring environment, select Commands > Run Command, and then select
the script to run.
■From within a script, use the fl.runScript() command.
■From the file system, double-click the script file.
To add a tool implemented in a JSFL file to the Tools panel:
1. Copy the JSFL file for the tool and any other associated files to the Tools folder (see “Saving
JSFL files” on page 7).
2. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel
(Macintosh).
3. Add the tool to the list of available tools.
4. Click OK.
You can add individual JavaScript API commands to ActionScript files by using the
MMExecute() function, which is documented in the ActionScript 2.0 Language Reference.
However, the MMExecute() function has an effect only when it is used in the context of a
custom user-interface element, such as a component Property inspector, or a SWF panel
within the authoring environment. Even if called from ActionScript, JavaScript API
commands have no effect in Flash Player or outside the authoring environment.
To issue a command from an ActionScript script:
■Use the following syntax (you can concatenate several commands into one string):
MMExecute(Javascript command string);
You can also run a script from the command line.

10 Introduction
To run a script from the command line on Windows:
■Use the following syntax (add path information as required):
"flash.exe" myTestFile.jsfl
To run a script from the command line on the Macintosh:
■Use the following syntax (add path information as required):
osascript -e 'tell application "flash" to open alias "Mac OS
X:Users:user:myTestFile.jsfl" '
The osascript command can also run AppleScript in a file. For example, you could put
the following text in a file named myScript:
tell application "flash"
open alias "Mac OS X:Users:user:myTestFile.jsfl"
end tell
Then, to invoke the script, you would use this command:
osascript myScript
What’s new in the JavaScript API
In Flash 8, several new top-level functions and objects have been added. In addition, some
existing objects now have new methods or properties. These additions, along with other
changes, are summarized below. Also, new samples are provided; see “Sample
implementations” on page 19.
If you have not used the JavaScript API before, you might want to skip this section and go
directly to “The Flash Document Object Model” on page 14.
New top-level methods
The following top-level method is new in Flash 8:
confirm()
The following top-level methods were implemented in Flash MX 2004 but are newly
documented in this release:
alert()
prompt()

What’s new in the JavaScript API 11
New objects
The following objects are new in Flash 8:
Filter object
Project object
ProjectItem object
The following object was implemented in a Flash MX 2004 update release, but is newly
documented in this release:
FLfile object
New methods and properties
The following methods and properties are new in Flash 8:
componentsPanel.reload()
document.addFilter()
document.changeFilterOrder()
document.crop()
document.deleteEnvelope()
document.disableAllFilters()
document.disableFilter()
document.disableOtherFilters()
document.enableAllFilters()
document.enableFilter()
document.exportPNG()
document.getBlendMode()
document.getFilters()
document.getMetadata()
document.importFile()
document.intersect()
document.punch()
document.removeAllFilters()
document.removeFilter()
document.setBlendMode()
document.setFilterProperty()
document.setFilters()

12 Introduction
document.setMetadata()
document.swapStrokeAndFill()
document.union()
document.zoomFactor
element.layer
element.selected
fill.focalPoint
fill.linearRGB
fill.overflow
fl.browseForFolderURL()
fl.closeProject()
fl.contactSensitiveSelection
fl.createProject()
fl.objectDrawingMode
fl.getAppMemoryInfo()
fl.getProject()
fl.objectDrawingMode
fl.showIdleMessage()
frame.getCustomEase()
frame.hasCustomEase
frame.setCustomEase()
frame.useSingleEaseCurve
shape.isDrawingObject
stroke.capType
stroke.joinType
stroke.miterLimit
stroke.strokeHinting
stroke.scaleType
stroke.shapeFill
symbolInstance.blendMode
symbolInstance.cacheAsBitmap
symbolInstance.filters
symbolItem.scalingGrid

What’s new in the JavaScript API 13
symbolItem.scalingGridRect
text.antiAliasSharpness
text.antiAliasThickness
textAttrs.letterSpacing
text.fontRenderingMode
videoItem.sourceFilePath
videoItem.videoType
xmlui.getControlItemElement()
xmlui.getEnabled()
xmlui.getVisible()
xmlui.setControlItemElement()
xmlui.setControlItemElements()
xmlui.setEnabled()
xmlui.setVisible()
Other changes
The following items have new parameters, additional acceptable values for existing
parameters, or other implementation changes in Flash 8:
document.setSelectionBounds()
document.setSelectionRect()
instance.instanceType
outputPanel.save()
fl.openProject()
text.border, text.useDeviceFonts, textAttrs.autoKern (no longer apply only to
static text)
Deprecated properties
The following property is deprecated in this release:
textAttrs.characterSpacing (recommended property to use is
textAttrs.letterSpacing)

14 Introduction
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 Flash Document Object Model 15
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.

16 Introduction
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.

The Flash Document Object Model 17
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)

18 Introduction
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 Te x t o b j ec t (subclass of Element object)
07 Te x t Ru n o b j e c t (text.textRuns array)
08 Te x t At t r s o b j e ct (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)

Sample implementations 19
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
Sample implementations
Several sample JSFL implementations are included with Flash 8. You can review and install
these files to familiarize yourself with the JavaScript API. The samples are installed in a folder
named Samples/ExtendingFlash within the folder in which you installed Flash. For example,
if you installed Flash using the default setting, the samples are placed in the following
location:
■In Windows: boot drive\Program Files\Macromedia\Flash 8\Samples and
Tutorials\Samples\ExtendingFlash
■On the Macintosh: Macintosh HD/Applications/Macromedia/Flash 8/Samples and
Tutorials/Samples/ExtendingFlash
Sample Shape command
A sample JavaScript API script named Shape.jsfl is located in the ExtendingFlash/Shape folder
(see “Sample implementations” above). This script displays information about the contours of
the shape in the Output panel.
To install and run the Shape script:
1. Copy the Shape.jsfl file to the Configuration/Commands folder (see “Saving JSFL files”
on page 7).
2. In a Flash document (FLA file), select a shape object.
3. Select Commands > Shape to run the script.

20 Introduction
Sample get and set filters command
A sample JavaScript API script named filtersGetSet.jsfl is located in the ExtendingFlash/
filtersGetSet folder (see “Sample implementations” on page 19). This script adds filters to a
selected object and displays information about the filters being added in the Output panel.
To install and run the filtersGetSet script:
1. Copy the filtersGetSet.jsfl file to the Configuration/Commands folder (see “Saving JSFL
files” on page 7).
2. In a Flash document (FLA file), select a text, movie clip, or button object.
3. Select Commands > filtersGetSet to run the script.
Sample PolyStar tool
A sample JavaScript API script named PolyStar.jsfl is located in the ExtendingFlash/PolyStar
folder (see “Sample implementations” on page 19).
The PolyStar.jsfl replicates the PolyStar tool that can be found in the Flash Tools panel. The
script demonstrates how to build the PolyStar tool using the JavaScript API, and includes
detailed comments describing what the code is doing. Read this file to gain a better
understanding of how the JavaScript API can be used. You should also read the PolyStar.xml
file in the Tools directory to learn more about how to build your own tool.
Flash includes an earlier (obfuscated) version of the PolyStar.jsfl script that you must remove
in order to use the sample PolyStar.jsfl file.