Loading...
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
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
3
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
4 Contents
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.
5
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.
6 Introduction
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.
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.
8 Introduction
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.
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, 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)
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 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. |
|
|
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 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.
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 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.
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 Text object (subclass of Element object)
07 TextRun object (text.textRuns array)
08 TextAttrs object (textRun.textAttrs array)
06 Shape object (subclass of Element object)
07 Contour object (shape.contours array)
08 HalfEdge object
09 Vertex object
09 Edge object
07 Edge object (shape.edges array)
08 HalfEdge object
09 Vertex object
09 Edge object
07 Vertex object (shape.vertices array)
08 HalfEdge object
09 Vertex object
09 Edge object
03 ScreenOutline object
04 Screen object (screenOutline.screens array)
05 Parameter object (screen.parameters array)
02 drawingLayer object
03 Path object
04 Contour object
02 Effect object (fl.effects array)
18 Introduction
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.
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 |
|
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()
23
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 removeEffect function.
See also
configureEffect(), 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
Loading...