Macromedia FLASH 8 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.

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

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

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

4Contents

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.

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.

6Introduction

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

fl.configDirectory or

Overview of the Macromedia Flash JavaScript API 7

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.

8Introduction

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

MMExecute() function has an effect only when it is used in the context of a

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.

Overview of the Macromedia Flash JavaScript API 9

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

10 Introduction

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

What’s new in the JavaScript API 11

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

12 Introduction

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

static text)

, text.useDeviceFonts, textAttrs.autoKern (no longer apply only to

Deprecated properties

The following property is deprecated in this release:

textAttrs.characterSpacing (recommended property to use is textAttrs.letterSpacing)

What’s new in the JavaScript API 13

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

Document object Use

drawingLayer object Use

Effect object Use

Math object Use

outputPanel object Use

Project object Use

Tools object Use

XMLUI object Use

fl.componentsPanel to access the componentsPanel object.

This object corresponds to the Components panel in the Flash authoring environment.

fl.documents to retrieve an array of all the open documents;

fl.documents[index] to access a particular document; use

use

fl.getDocumentDOM() to access the current document (the one

with focus).

fl.drawingLayer to access the drawingLayer object.

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.

fl.Math to access the Math object.

fl.outputPanel to access the outputPanel object. This object

corresponds to the Output panel in the Flash authoring environment.

fl.getProject() to return a Project object for the currently

open project.

fl.tools to access an array of Tools objects.

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.

flash or fl. For example, to close all open

14 Introduction

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

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

or fl.findDocumentIndex(nameOfDocument)

flash.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 each document for its

document.name property. See fl.documents and document.name.

fl.documents array, iterate through the array and test

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

library.items, and Item object.

document.library, library object,

flash.documents[0] or

The Flash Document Object Model 15

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 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;

}

document.selection property

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.

16 Introduction

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)

The Flash Document Object Model 17

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 Tex t o b je ct (subclass of Element object)

07 Tex t Ru n o bj ec t (

08 Text At tr s o bj ec t (

text.textRuns array)

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)

18 Introduction

02 Math object

02 outputPanel object

02 Project object

03 ProjectItem object (project.items array)

02 Tools object (

03 ToolObj object (

fl.tools array)

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.

Sample implementations 19

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.

20 Introduction

To remove the earlier version of the PolyStar.jsfl file that was installed with Flash:

1. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel

(Macintosh).

2. In the Customize Tools Panel dialog box, click the Rectangle tool on the left side of the

dialog box.

The Rectangle tool and the PolyStar tool should now be listed in the Current Selection list on the right side of the dialog box.

3. Select the PolyStar tool in the Current Selection list.

4. Click Remove.

5. Click OK.

6. Quit Flash.

7. Remove only the PolyStar.jsfl file from the Configuration/Tools folder (see “Saving JSFL

files” on page 7).The PolyStar.xml and PolyStar.png files are needed by the new

PolyStar.jsfl file that you will install later. When you restart Flash, the PolyStar tool no longer appears in the Customize Tools Panel dialog box.

To install the updated PolyStar example files:

1. If Flash is running, exit the application.

2. Copy the new PolyStar.jsfl file to the Configuration/Tools folder (see “Saving JSFL files”

on page 7). The PolyStar.xml and PolyStar.png files that you see in this folder are needed

by the new PolyStar.jsfl file.

3. Restart Flash.

4. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel

(Macintosh). You should see PolyStar tool in the available tools list.

5. Click the Rectangle tool at the left side of the Customize Tools Panel dialog box. The

Rectangle Tool should appear in the Current Selection list at the right side of the dialog box.

6. Select the PolyStar tool from the Available Tools list.

7. Click Add.

8. Click OK.

The PolyStar tool now appears in the Rectangle tool pop-up menu.

Sample implementations 21

Sample Trace Bitmap panel

A set of files named TraceBitmap.fla and TraceBitmap.swf are located in the ExtendingFlash/ TraceBitmapPanel folder (see “Sample implementations” on page 19). These files illustrate how to design and build a panel to control the functions of Flash. They also show the use of the

MMExecute() function to call JavaScript commands from an ActionScript script.

To run the TraceBitmap sample:

1. If Flash is running, exit from Flash.

2. Copy the TraceBitmap.swf file to the Configuration/WindowSWF folder (see “Saving

JSFL files” on page 7).

3. Start Flash.

4. Create or open a Flash document (FLA file), and import a bitmap or JPEG image into

the file.

You can use the flower.jpg file provided in the TraceBitmapPanel folder or another image of your choice.

5. With the imported image selected, select Window > Other Panels > TraceBitmap.

6. Click Submit.

The image is converted into a group of shapes.

Sample DLL

A sample DLL implementation is located in the ExtendingFlash/dllSampleComputeSum folder (see “Sample implementations” on page 19). For more information about building DLLs, see Chapter 3, “C-Level Extensibility,” on page 533.

22 Introduction

CHAPTER 1

Top-Level Functions and Methods

This chapter describes the top-level functions and methods that are available when you use the Macromedia Flash JavaScript application programming interface (JavaScript API). For information about where to store JavaScript API files, see “Saving JSFL files” on page 7.

The following lists summarize the areas in the authoring environment that relate to each function or method. Following the lists, the functions and methods are listed in alphabetical order.

Global methods

The following methods can be called from any JavaScript API script:

alert() confirm() prompt()

Timeline effects

The following functions are specific to timeline effects:

configureEffect() executeEffect() removeEffect()

Extensible tools

The following functions are available in scripts that create extensible tools:

activate() configureTool() deactivate() keyDown() keyUp() mouseDoubleClick() mouseDown() mouseMove() mouseUp() notifySettingsChanged() setCursor()

activate()

Availability

Flash MX 2004.

Usage

function activate() {

// statements

}

Parameters

None.

Returns

Nothing.

Description

Function; called when the extensible tool becomes active (that is, when the tool is selected in the Tools panel). Use this function to perform any initialization tasks the tool requires.

24 Top-Level Functions and Methods

Example

The following example sets the value of tools.activeTool when the extensible tool is selected in the Tools panel:

function activate() {

var theTool = fl.tools.activeTool

}

See also

tools.activeTool

alert()

Availability

Flash MX 2004.

Usage

alert ( alertText )

Parameters

alertText A string that specifies the message you want to display in the Alert dialog box.

Returns

Nothing.

Description

Method; displays a string in a modal Alert dialog box, along with an OK button.

Example

The following example displays the message “Process Complete” in an Alert dialog box:

alert("Process Complete");

See also

confirm(), prompt()

alert() 25

configureEffect()

Availability

Flash MX 2004.

Usage

function configureEffect() {

// Statements

}

Parameters

None.

Returns

Nothing.

Description

Function; called once when Flash loads; place any global initialization statements for your effect inside this function. The per instance parameter data for an effect cannot be accessed here.

See also

executeEffect(), removeEffect()

configureTool()

Availability

Flash MX 2004.

Usage

function configureTool() {

// statements

}

Parameters

None.

Returns

Nothing.

26 Top-Level Functions and Methods

Description

Function; called when Flash opens and the extensible tool is loaded into the Tools panel. Use this function to set any information Flash needs to know about the tool.

Example

The following examples show two possible implementations of this function:

function configureTool() {

theTool = fl.tools.activeTool; theTool.setToolName("myTool"); theTool.setIcon("myTool.png"); theTool.setMenuString("My Tool's menu string"); theTool.setToolTip("my tool's tool tip"); theTool.setOptionsFile( "mtTool.xml" );

}

function configureTool() {

theTool = fl.tools.activeTool; theTool.setToolName("ellipse"); theTool.setIcon("Ellipse.png"); theTool.setMenuString("Ellipse"); theTool.setToolTip("Ellipse"); theTool.showTransformHandles( true );

}

confirm()

Availability

Flash 8.

Usage

confirm ( strAlert )

Parameters

strAlert A string that specifies the message you want to display in the Alert dialog box.

Returns

A Boolean value: true if the user clicks OK; false if the user clicks Cancel.

Description

Method; displays a string in a modal Alert dialog box, along with OK and Cancel buttons.

confirm() 27

Example

The following example displays the message “Sort data?” in an Alert dialog box:

confirm("Sort data?");

See also

alert(), prompt()

deactivate()

Availability

Flash MX 2004.

Usage

function deactivate() {

// statements

}

Parameters

None.

Returns

Nothing.

Description

Function; called when the extensible tool becomes inactive (that is, when the active tool changes from this tool to another one). Use this function to perform any cleanup the tool needs.

Example

The following example displays a message in the Output panel when the tool becomes inactive:

function deactivate() {

fl.trace( "Tool is no longer active" );

}

28 Top-Level Functions and Methods

executeEffect()

Availability

Flash MX 2004.

Usage

function executeEffect() {

// statements

}

Parameters

None.

Returns

Nothing.

Description

Function; called when the user first applies an effect or changes an effect’s properties. The code contained in this function modifies the original object(s) to create the desired effect. It is also responsible for copying the original to a hidden layer if necessary for the function.

See also

configureEffect(), removeEffect()

removeEffect

keyDown()

Availability

Flash MX 2004.

Usage

function keyDown() {

// statements

}

Parameters

None.

Returns

Nothing.

keyDown() 29

Description

Function; called when the extensible tool is active and the user presses a key. The script should call

tools.getKeyDown() to determine which key was pressed.

Example

The following example displays information about which key was pressed when the extensible tool is active and the user presses a key.

function keyDown() {

fl.trace("key " + fl.tools.getKeyDown() + " was pressed");

}

See also

keyUp(), tools.getKeyDown()

keyUp()

Availability

Flash MX 2004.

Usage

function keyUp() {

// statements

}

Parameters

None.

Returns

Nothing.

Description

Function; called when the extensible tool is active and a key is released.

30 Top-Level Functions and Methods

+ 524 hidden pages