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()