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.

Reserved. http://www.on2.com.

Visual SourceSafe is a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.

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

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

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

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA FLASH 8-LEARNING ACTIONSCRIPT 2.0 IN FLASH User manual

MACROMEDIA

MACROMEDIA COLDFUSION MX 61-GETTING STARTED BUILDING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLASH 8-COMPONENTS LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT User manual

MACROMEDIA

MACROMEDIA FLASH MX PROFESSIONAL 2004 - FLASH LITE 1.1... Instruction Manual

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA FIREWORKS 8-EXTENDING FIREWORKS User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004-DATA Operation instructions

MACROMEDIA

MACROMEDIA STUDIO 8-EXPLORING STUDIO 8 User manual

MACROMEDIA

MACROMEDIA DIRECTOR MX-LINGO DICTIONARY User manual

MACROMEDIA

MACROMEDIA COLDFUSION MX 61 - INSTALLING COLDFUSION MX FOR IBM WEBSPHERE APPLICATION... User manual

MACROMEDIA

MACROMEDIA CONTRIBUTE 3 - DEPLOYING AND PUBLISHING... User manual

MACROMEDIA

MACROMEDIA DREAMWEAVER 8 User manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-INSTALLING FLASH MEDIA SERVER... User manual

MACROMEDIA

MACROMEDIA BREEZE Quick reference guide

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA CONTRIBUTE-USING CONTRIBUTE Mounting instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA FLASH 8-GETTING STARTED WITH FLASH User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLASH MX 2004 - FLASH LITE AUTHORING GUIDELINES FOR THE I-MODE... Instruction Manual

MACROMEDIA

MACROMEDIA FLEX BUILDER-USING FLEX BUILDER Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 5-ADVANCED ADMINISTRATION User manual

MACROMEDIA

MACROMEDIA FLASH REMOTING MX-USING FLASH REMOTING FOR FLASH MX 2004 ACTIONSCRIPT... Mounting instructions

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual