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
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.
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.
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
1
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
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
Example
The following example displays a message in the Output panel when the extensible tool is
active and a key is released.
function keyUp() {
fl.trace("Key is released");
}
See also
keyDown()
mouseDoubleClick()
Availability
Flash MX 2004.
Usage
function mouseDoubleClick() {
// statements
}
Parameters
None.
Returns
Nothing.
Description
Function; called when the extensible tool is active and the mouse button is double-clicked on
the Stage.
Example
The following example displays a message in the Output panel when the extensible tool is
active and the mouse button is double-clicked.
function mouseDoubleClick() {
fl.trace("Mouse was double-clicked");
}
mouseDoubleClick() 31
mouseDown()
Availability
Flash MX 2004.
Usage
function mouseDown( [ pt ] ) {
// statements
}
Parameters
pt A point that specifies the location of the mouse when the button is pressed. It is passed to
the function when the mouse button is pressed. This parameter is optional.
Returns
Nothing.
Description
Function; called when the extensible tool is active and the mouse button is pressed while the
pointer is over the Stage.
Example
The following examples show how this function can be used when the extensible tool is active.
The first example displays a message in the Output panel that the mouse button was pressed.
The second example displays the x and y coordinates of the mouse’s location when the button
was pressed.
function mouseDown() {
fl.trace("Mouse button has been pressed");
}
function mouseDown(pt) {
fl.trace("x = "+ pt.x+" :: y = "+pt.y);
}
32 Top-Level Functions and Methods
mouseMove()
Availability
Flash MX 2004.
Usage
function mouseMove( [ pt ] ) {
// statements
}
Parameters
pt A point that specifies the current location of the mouse. It is passed to the function
whenever the mouse moves, which tracks the mouse location. If the Stage is in edit or
edit-in-place mode, the point coordinates are relative to the object being edited. Otherwise,
the point coordinates are relative to the Stage. This parameter is optional.
Returns
Nothing.
Description
Function; called whenever the extensible tool is active and the mouse moves over a specified
point on the Stage. The mouse button can be down or up.
Example
The following examples show how this function can be used. The first example displays a
message in the Output panel that the mouse is being moved. The second example displays
the x and y coordinates of the mouse’s location as it moves.
function mouseMove() {
fl.trace("moving");
}
function mouseMove(pt) {
fl.trace("x = "+ pt.x + " :: y = " + pt.y);
}
mouseMove() 33
mouseUp()
Availability
Flash MX 2004.
Usage
function mouseUp() {
// statements
}
Parameters
None.
Returns
Nothing.
Description
Function; called whenever the extensible tool is active and the mouse button is released after
being pressed on the Stage.
Example
The following example displays a message in the Output panel when the extensible tool is
active and the mouse button is released.
function mouseUp() {
fl.trace("mouse is up");
}
notifySettingsChanged()
Availability
Flash MX 2004.
Usage
function notifySettingsChanged() {
// statements
}
Parameters
None.
34 Top-Level Functions and Methods
Returns
Nothing.
Description
Function; called when the extensible tool is active and the user changes its options in the
Property inspector. You can use the
of the options (see
Example
tools.activeTool).
tools.activeTool property to query the current values
The following example displays a message in the Output panel when the extensible tool is
active and the user changes its options in the Property inspector.
function notifySettingsChanged() {
var theTool = fl.tools.activeTool;
var newValue = theTool.myProp;
}
prompt()
Availability
Flash MX 2004.
Usage
prompt( promptMsg, [ text ] )
Parameters
promptMsg A string to display in the Prompt dialog box (limited to 256 characters on
Macintosh OS X).
text An optional string to display as a default value for the text field.
Returns
The string the user typed if the user clicks OK; null if the user clicks Cancel.
Description
Method; displays a prompt and optional text in a modal Alert dialog box, along with OK and
Cancel buttons.
prompt() 35
Example
The following example prompts the user to enter a user name. If the user types a name and
clicks OK, the name appears in the Output panel.
var userName = prompt("Enter user name", "Type user name here");
fl.trace(userName);
See also
alert(), confirm()
removeEffect()
Availability
Flash MX 2004.
Usage
function removeEffect() {
// statements
}
Parameters
None.
Returns
Nothing.
Description
Function; called when the user changes an effect’s properties or uses the Remove Effect menu
item. The code contained in this function returns the object(s) to their original state. For
example, if the effect broke a text string apart, the
removeEffect() method would remove
the text string that was broken apart and replace it with the original string.
See also
configureEffect(), executeEffect()
36 Top-Level Functions and Methods
setCursor()
Availability
Flash MX 2004.
Usage
function setCursor() {
// statements
}
Parameters
None.
Returns
Nothing.
Description
Function; called when the extensible tool is active and the mouse moves, to allow the script to
set custom pointers. The script should call
For a list that shows which pointers correspond to which integer values, see
tools.setCursor().
Example
function setCursor() {
fl.tools.setCursor( 1 );
}
tools.setCursor() to specify the pointer to use.
setCursor() 37
38 Top-Level Functions and Methods
CHAPTER 2
Objects
This chapter briefly describes each of the objects available in the Flash JavaScript application
programming interface (JavaScript API). The objects are listed in alphabetical order in the
following table:
Object Description
BitmapInstance object The BitmapInstance object is a subclass of the Instance object
and represents a bitmap in a frame.
BitmapItem object A BitmapItem object refers to a bitmap in the library of a
document. The BitmapItem object is a subclass of the Item
object.
CompiledClipInstance object The CompiledClipInstance object is a subclass of the Instance
object.
ComponentInstance object The ComponentInstance object is a subclass of the
SymbolInstance object and represents a component in a
frame.
componentsPanel object The componentsPanel object, which represents the
Components panel, is a property of the flash object (fl) and can
be accessed by
Contour object A Contour object represents a closed path of half edges on the
boundary of a shape.
Document object The Document object represents the Stage.
drawingLayer object The drawingLayer object is accessible from JavaScript as a
child of the flash object.
Edge object The Edge object represents an edge of a shape on the Stage.
Effect object The Effect object represents an instance of a timeline effect.
Element object Everything that appears on the Stage is of the type Element.
Fill object The Fill object contains all the properties of the Fill color
setting of the Tools panel or of a selected shape.
fl.componentsPanel.
2
39
Object Description
Filter object The Filter object contains all the properties for all filters.
flash object (fl) The flash object represents the Flash application.
FLfile object The FLfile object lets you write Flash extensions that can
access, modify, and remove files and folders on the local file
system.
folderItem object The folderItem object is a subclass of the Item object.
fontItem object The fontItem object is a subclass of the Item object.
Frame object The Frame object represents frames in the layer.
HalfEdge object Directed side of the edge of a Shape object.
Instance object The Instance object is a subclass of the Element object.
Item object The Item object is an abstract base class.
Layer object The Layer object represents a layer in the timeline.
library object The library object represents the Library panel.
Math object The Math object is available as a read-only property of the
flash object; see
Matrix object The Matrix object represents a transformation matrix.
outputPanel object The outputPanel object represents the Output panel, which
displays troubleshooting information such as syntax errors.
Parameter object The Parameter object type is accessed from the
screen.parameters array (which corresponds to the screen
Property inspector in the Flash authoring tool) or by the
componentInstance.parameters array (which corresponds to
the component Property inspector in the authoring tool).
Path object The Path object defines a sequence of line segments (straight,
curved, or both), which you typically use when creating
extensible tools.
Project object The Project object represents a Flash Project (FLP) file.
ProjectItem object The ProjectItem object represents an item (file on disk) that
has been added to a project.
Screen object The Screen object represents a single screen in a slide or form
document.
ScreenOutline object The ScreenOutline object represents the group of screens in a
slide or form document.
fl.Math.
40 Objects
Object Description
Shape object The Shape object is a subclass of the Element object. The
Shape object provides more precise control than the drawing
APIs for manipulating or creating geometry on the Stage.
SoundItem object The SoundItem object is a subclass of the Item object. It
represents a library item used to create a sound.
Stroke object The Stroke object contains all the settings for a stroke,
including the custom settings.
SymbolInstance object The SymbolInstance object is a subclass of the Instance
object and represents a symbol in a frame.
SymbolItem object The SymbolItem object is a subclass of the Item object.
Text object The Text object represents a single text item in a document.
TextAttrs object The TextAttrs object contains all the properties of text that can
be applied to a subselection. This object is a subclass of the
Text object.
TextRun object The TextRun object represents a run of characters that have
attributes that match all of the properties in the TextAttrs
object.
Timeline object The Timeline object represents the Flash timeline, which can
be accessed for the current document by
fl.getDocumentDOM().getTimeline().
ToolObj object A ToolObj object represents an individual tool in the Tools
panel.
Tools object The Tools object is accessible from the Flash object
fl.tools).
(
Vertex object The Vertex object is the part of the shape data structure that
holds the coordinate data.
VideoItem object The VideoItem object is a subclass of the Item object.
XMLUI object The XMLUI object provides the ability to get and set
properties of an XMLUI dialog box, and accept or cancel
out of one.
41
CHAPTER 3
Objects
BitmapInstance object
Inheritance Element object > Instance object > BitmapInstance object
Availability
Flash MX 2004.
Description
The BitmapInstance object is a subclass of the Instance object and represents a bitmap in a
frame (see Instance object).
Method summary for the BitmapInstance object
In addition to the Instance object methods, you can use the following methods with the
BitmapInstance object:
Method Description
bitmapInstance.getBits() Lets you create bitmap effects by getting the bits out of the
bitmap, manipulating them, and then returning them to Flash.
bitmapInstance.setBits() Sets the bits of an existing bitmap element.
Property summary for the BitmapInstance object
In addition to the Instance object properties, you can use the following properties with the
BitmapInstance object.
Property Description
bitmapInstance.hPixels Read-only; an integer that represents the width of the bitmap,
in pixels.
bitmapInstance.vPixels Read-only; an integer that represents the height of the bitmap,
in pixels.
bitmapInstance.getBits()
Availability
Flash MX 2004.
Usage
bitmapInstance.getBits()
42 Objects
Parameters
None.
Returns
An object that contains width, height, depth, bits, and, if the bitmap has a color table,
cTab properties. The bits element is an array of bytes. The cTab element is an array of color
values of the form
"#RRGGBB". The length of the array is the length of the color table.
The byte array is meaningful only when referenced by a DLL or shared library. You typically
use it only when creating an extensible tool or effect. For information on creating DLLs for
use with Flash JavaScript, see Chapter 3, “C-Level Extensibility.”
Description
Method; lets you create bitmap effects by getting the bits out of the bitmap, manipulating
them, and then returning them to Flash. See also
Example
bitmapInstance.setBits().
The following code creates a reference to the currently selected object; tests whether the object
is a bitmap; and traces the height, width, and bit depth of the bitmap:
var isBitmap = fl.getDocumentDOM().selection[0].instanceType;
if(isBitmap == "bitmap"){
var bits = fl.getDocumentDOM().selection[0].getBits();
fl.trace("height = " + bits.height);
fl.trace("width = " + bits.width);
fl.trace("depth = " + bits.depth);
}
See also
bitmapInstance.setBits()
bitmapInstance.hPixels
Availability
Flash MX 2004.
Usage
bitmapInstance.hPixels
Description
Read-only property; an integer that represents the width of the bitmap—that is, the number
of pixels in the horizontal dimension.
BitmapInstance object 43
Example
The following code retrieves the width of the bitmap in pixels:
// Get the number of pixels in the horizontal dimension.
var bmObj = fl.getDocumentDOM().selection[0];
var isBitmap = bmObj.instanceType;
if(isBitmap == "bitmap"){
var numHorizontalPixels = bmObj.hPixels;
}
See also
bitmapInstance.vPixels
bitmapInstance.setBits()
Availability
Flash MX 2004.
Usage
bitmapInstance.setBits(bitmap)
Parameters
bitmap An object that contains height, width, depth, bits, and cTab properties. The
height, width, and depth properties are integers. The bits property is a byte array. The
cTab property is required only for bitmaps with a bit depth of 8 or less and is a string that
represents a color value in the form
NOTE
The byte array is meaningful only when referenced by an external library. You typically
use it only when creating an extensible tool or effect.
"#RRGGBB".
Returns
Nothing.
Description
Method; sets the bits of an existing bitmap element. This lets you create bitmap effects by
getting the bits out of the bitmap, manipulating them, and then returning the bitmap to
Flash.
44 Objects
Example
The following code tests whether the current selection is a bitmap, and then sets the height of
the bitmap to 150 pixels:
var isBitmap = fl.getDocumentDOM().selection[0].instanceType;
if(isBitmap == "bitmap"){
var bits = fl.getDocumentDOM().selection[0].getBits();
bits.height = 150;
fl.getDocumentDOM().selection[0].setBits(bits);
}
See also
bitmapInstance.getBits()
bitmapInstance.vPixels
Availability
Flash MX 2004.
Usage
bitmapInstance.vPixels
Description
Read-only property; an integer that represents the height of the bitmap—that is, the number
of pixels in the vertical dimension.
Example
The following code gets the height of the bitmap in pixels:
// Get the number of pixels in the vertical dimension.
var bmObj = fl.getDocumentDOM().selection[0];
var isBitmap = bmObj.instanceType;
if(isBitmap == "bitmap"){
var numVerticalPixels = bmObj.vPixels;
}
See also
bitmapInstance.hPixels
BitmapInstance object 45
CHAPTER 4
Objects
BitmapItem object
Inheritance Item object > BitmapItem object
Availability
Flash MX 2004.
Description
A BitmapItem object refers to a bitmap in the library of a document. The BitmapItem object
is a subclass of the Item object (see Item object).
Property summary for the BitmapItem object
In addition to the Item object properties, the BitmapItem object has following properties:
Property Description
bitmapItem.allowSmoothing A Boolean value that specifies whether to allow
smoothing of a bitmap.
bitmapItem.compressionType A string that determines the type of image
compression applied to the bitmap.
bitmapItem.quality An integer that specifies the quality of the bitmap
bitmapItem.useImportedJPEGQuality A Boolean value that specifies whether to use the
default imported JPEG quality.
bitmapItem.allowSmoothing
Availability
Flash MX 2004.
Usage
bitmapItem.allowSmoothing
Description
Property; a Boolean value that specifies whether to allow smoothing of a bitmap (true) or not
(
false).
46 Objects
Example
The following code sets the allowSmoothing property of the first item in the library of the
current document to
fl.getDocumentDOM().library.items[0].allowSmoothing = true;
alert(fl.getDocumentDOM().library.items[0].allowSmoothing);
true:
bitmapItem.compressionType
Availability
Flash MX 2004.
Usage
bitmapItem.compressionType
Description
Property; a string that determines the type of image compression applied to the bitmap.
Acceptable values are
bitmapItem.useImportedJPEGQuality is false, "photo" corresponds to JPEG with a
quality from 0 to 100; if
corresponds to JPEG using the default document quality value. The value
corresponds to GIF or PNG format. (See bitmapItem.useImportedJPEGQuality.)
Example
The following code sets the compressionType property of the first item in the library of the
current document to
fl.getDocumentDOM().library.items[0].compressionType = "photo";
alert(fl.getDocumentDOM().library.items[0].compressionType);
"photo" or "lossless". If the value of
bitmapItem.useImportedJPEGQuality is true, "photo"
"lossless"
"photo":
bitmapItem.quality
Availability
Flash MX 2004.
Usage
bitmapItem.quality
Description
Property; an integer that specifies the quality of the bitmap. To use the default document
quality, specify -1; otherwise, specify an integer from 0 to 100. Available only for JPEG
compression.
BitmapItem object 47
Example
The following code sets the quality property of the first item in the library of the current
document to 65:
fl.getDocumentDOM().library.items[0].quality = 65;
alert(fl.getDocumentDOM().library.items[0].quality);
bitmapItem.useImportedJPEGQuality
Availability
Flash MX 2004.
Usage
bitmapItem.useImportedJPEGQuality
Description
Property; a Boolean value that specifies whether to use the default imported JPEG quality
(
true) or not (false). Available only for JPEG compression.
Example
The following code sets the useImportedJPEGQuality property of the first item in the
library of the current document to
fl.getDocumentDOM().library.items[0].useImportedJPEGQuality = true;
alert(fl.getDocumentDOM().library.items[0].useImportedJPEGQuality);
true:
48 Objects
CHAPTER 5
Objects
CompiledClipInstance object
Inheritance Element object > Instance object > CompiledClipInstance object
Availability
Flash MX 2004.
Description
The CompiledClipInstance object is a subclass of the Instance object. It is essentially an
instance of a movie clip that has been converted to a compiled clip library item. (See Instance
object.)
Property summary for the CompiledClipInstance object
In addition to the properties of the Instance object, the CompiledClipInstance object has the
following properties:
Property Description
compiledClipInstance.accName
compiledClipInstance.actionScript
compiledClipInstance.description
compiledClipInstance.forceSimple
compiledClipInstance.shortcut
compiledClipInstance.silent
compiledClipInstance.tabIndex
A string that is equivalent to the Name field in the
Accessibility panel.
A string that represents the ActionScript for this
instance; equivalent to
A string that is equivalent to the Description field in the
Accessibility panel.
A Boolean value that enables and disables the children
of the object to be accessible.
A string that is equivalent to the Shortcut field in the
Accessibility panel.
A Boolean value that enables or disables the
accessibility of the object; equivalent to the inverse
logic of the Make Object Accessible setting in the
Accessibility panel.
An integer that is equivalent to the Tab Index field in the
Accessibility panel.
symbolInstance.actionScript.
CompiledClipInstance object 49
compiledClipInstance.accName
Availability
Flash MX 2004.
Usage
compiledClipInstance.accName
Description
Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers
identify objects by reading the name aloud.
Example
The following example gets and sets the accessibility name of the first selected object:
// Get the name of the object.
var theName = fl.getDocumentDOM().selection[0].accName;
// Set the name of the object.
fl.getDocumentDOM().selection[0].accName = 'Home Button';
compiledClipInstance.actionScript
Availability
Flash MX 2004.
Usage
compiledClipInstance.actionScript
Description
Property; a string that represents the ActionScript for this instance; equivalent to
symbolInstance.actionScript.
Example
The following code assigns ActionScript to specified elements:
// Assign some ActionScript to a specified Button compiled clip instance.
fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0]
.actionScript = "on(click) {trace('button is clicked');}";
// Assign some ActionScript to the currently selected Button compiled clip
instance.
fl.getDocumentDOM().selection[0].actionScript =
"on(click) {trace('button is clicked');}";
50 Objects
compiledClipInstance.description
Availability
Flash MX 2004.
Usage
compiledClipInstance.description
Description
Property; a string that is equivalent to the Description field in the Accessibility panel. The
description is read by the screen reader.
Example
The following example illustrates getting and setting the description property:
// Get the description of the current selection.
var theDescription = fl.getDocumentDOM().selection[0].description;
// Set the description of the current selection.
fl.getDocumentDOM().selection[0].description =
"This is compiled clip number 1";
compiledClipInstance.forceSimple
Availability
Flash MX 2004.
Usage
compiledClipInstance.forceSimple
Description
Property; a Boolean value that enables and disables the children of the object to be accessible.
This is equivalent to the inverse logic of the Make Child Objects Accessible setting in the
Accessibility panel. If
Accessible option being unchecked. If
forceSimple is true, it is the same as the Make Child Objects
forceSimple is false, it is the same as the Make
Child Object Accessible option being checked.
Example
The following example illustrates getting and setting the forceSimple property:
// Query if the children of the object are accessible.
var areChildrenAccessible = fl.getDocumentDOM().selection[0].forceSimple;
// Allow the children of the object to be accessible.
fl.getDocumentDOM().selection[0].forceSimple = false;
CompiledClipInstance object 51
compiledClipInstance.shortcut
Availability
Flash MX 2004.
Usage
compiledClipInstance.shortcut
Description
Property; a string that is equivalent to the Shortcut field in the Accessibility panel. The
shortcut is read by the screen readers. This property is not available for dynamic text fields.
Example
The following example illustrates getting and setting the shortcut property:
// Get the shortcut key of the object.
var theShortcut = fl.getDocumentDOM().selection[0].shortcut;
// Set the shortcut key of the object.
fl.getDocumentDOM().selection[0].shortcut = "Ctrl+I";
compiledClipInstance.silent
Availability
Flash MX 2004.
Usage
compiledClipInstance.silent
Description
Property; a Boolean value that enables or disables the accessibility of the object; equivalent to
the inverse logic of Make Object Accessible setting in the Accessibility panel. That is, if
silent is true, then Make Object Accessible is unchecked. If silent is false, then Make
Object Accessible is checked.
Example
The following example illustrates getting and setting the silent property:
// Query if the object is accessible.
var isSilent =fl.getDocumentDOM().selection[0].silent;
// Set the object to be accessible.
fl.getDocumentDOM().selection[0].silent = false;
52 Objects
compiledClipInstance.tabIndex
Availability
Flash MX 2004.
Usage
compiledClipInstance.tabIndex
Description
Property; an integer that is equivalent to the Tab Index field in the Accessibility panel. Creates
a tab order in which objects are accessed when the user presses the Tab key.
Example
The following example illustrates getting and setting the tabIndex property:
// Get the tabIndex of the object.
var theTabIndex = fl.getDocumentDOM().selection[0].tabIndex;
// Set the tabIndex of the object.
fl.getDocumentDOM().sele ction[0].tabIndex = 1;
CompiledClipInstance object 53
CHAPTER 6
Objects
ComponentInstance object
Inheritance Element object > Instance object > SymbolInstance object >
ComponentInstance object
Availability
Flash MX 2004.
Description
The ComponentInstance object is a subclass of the SymbolInstance object and represents a
component in a frame. (See SymbolInstance object.)
Property summary for the ComponentInstance object
In addition to all the properties of the SymbolInstance object, the ComponentInstance object
has the following property:
Property Description
componentInstance.parameters Read-only; an array of ActionScript 2.0 properties that
are accessible from the component Property inspector.
componentInstance.parameters
Availability
Flash MX 2004.
Usage
componentInstance.parameters
Description
Read-only property; an array of ActionScript 2.0 properties that are accessible from the
component Property inspector. See “Parameter object” on page 337.
Example
The following example illustrates getting and setting the parameters property:
var parms = fl.getDocumentDOM().selection[0].parameters;
parms[0].value = "some value";
See also
Parameter object
54 Objects
CHAPTER 7
Objects
componentsPanel object
Availability
Flash MX 2004.
Description
The componentsPanel object, which represents the Components panel, is a property of the
flash object (fl) and can be accessed by
Method summary for the componentsPanel object
You can use the following methods with the componentsPanel object:
Method Description
componentsPanel.addItemToDocument() Adds the specified component to the document
componentsPanel.reload() Refreshes the Components panel's list of
fl.componentsPanel. (See flash object (fl).)
at the specified position.
components.
componentsPanel.addItemToDocument()
Availability
Flash MX 2004.
Usage
componentsPanel.addItemToDocument( position, categoryName, componentName )
Parameters
position A point (for example, {x:0, y:100}) that specifies the location at which to add the
component. Specify
component’s registration point.
categoryName A string that specifies the name of the component category (for example,
"Data"). The valid category names are listed in the Components panel.
componentName A string that specifies the name of the component in the specified category
(for example, "
Components panel.
Returns
Nothing.
position relative to the center point of the component—not the
WebServiceConnector"). The valid component names are listed in the
componentsPanel object 55
Description
Adds the specified component to the document at the specified position.
Examples
The following examples illustrate some ways to use this method:
fl.componentsPanel.addItemToDocument({x:0, y:0}, "User Interface",
"CheckBox");
fl.componentsPanel.addItemToDocument({x:0, y:100}, "Data",
"WebServiceConnector");
fl.componentsPanel.addItemToDocument({x:0, y:200}, "User Interface",
"Button");
componentsPanel.reload()
Availability
Flash 8.
Usage
componentsPanel.reload()
Parameters
None.
Returns
A Boolean value of true if the Component panel list is refreshed, false otherwise.
Description
Method; refreshes the Components panel’s list of components.
Example
The following example refreshes the Components panel:
fl.componentsPanel.reload();
56 Objects
CHAPTER 8
Contour object
Availability
Flash MX 2004.
Description
A Contour object represents a closed path of half edges on the boundary of a shape.
Method summary for the Contour object
You can use the following method with the Contour object:
Property Description
contour.getHalfEdge() Returns a HalfEdge object on the contour of the selection.
Property summary for the Contour object
Objects
You can use the following properties with the Contour object:
Property Description
contour.interior Read-only: the value is true if the contour encloses an area; false
otherwise.
contour.orientation Read-only; an integer indicating the orientation of the contour.
contour.getHalfEdge()
Availability
Flash MX 2004.
Usage
contour.getHalfEdge()
Parameters
None.
Returns
A HalfEdge object.
Contour object 57
Description
Method; returns a HalfEdge object on the contour of the selection.
Example
This example traverses all the contours of a selected shape and shows the coordinates of the
vertices in the Output panel:
// with a shape selected
var elt = fl.getDocumentDOM().selection[0];
elt.beginEdit();
var contourArray = elt.contours;
var contourCount = 0;
for (i=0; i<contourArray.length; i++)
{
var contour = contourArray[i];
contourCount++;
var he = contour.getHalfEdge();
var iStart = he.id;
var id = 0;
while (id != iStart)
{
// get the next vertex.
var vrt = he.getVertex();
var x = vrt.x;
var y = vrt.y;
fl.trace("vrt: " + x + ", " + y);
he = he.getNext();
id = he.id;
}
}
elt.endEdit();
58 Objects
contour.interior
Availability
Flash MX 2004.
Usage
contour.interior
Description
Read-only property; the value is true if the contour encloses an area; false otherwise.
Example
This example traverses all the contours in the selected shape and shows the value of the
interior property for each contour in the Output panel:
var elt = fl.getDocumentDOM().selection[0];
elt.beginEdit();
var contourArray = elt.contours;
var contourCount = 0;
for (i=0; i<contourArray.length; i++) {
var contour = contourArray[i];
fl.trace("Next Contour, interior:" + contour.interior );
contourCount++;
}
elt.endEdit();
contour.orientation
Availability
Flash MX 2004.
Usage
contour.orientation
Description
Read-only property; an integer indicating the orientation of the contour. The value of the
integer is -1 if the orientation is counterclockwise, 1 if it is clockwise, and 0 if it is a contour
with no area.
Contour object 59
Example
The following example traverses all the contours of the selected shape and shows the value of
the
orientation property of each contour in the Output panel:
var elt = fl.getDocumentDOM().selection[0];
elt.beginEdit();
var contourArray = elt.contours;
var contourCount = 0;
for (i=0; i<contourArray.length; i++) {
var contour = contourArray[i];
fl.trace("Next Contour, orientation:" + contour.orientation);
contourCount++;
}
elt.endEdit();
60 Objects
Objects
Document object
Availability
Flash MX 2004.
Description
The Document object represents the Stage. That is, only FLA files are considered documents.
Method summary for the Document object
You can use the following methods with the Document object.
Method Description
document.addDataToDocument() Stores specified data with a document.
document.addDataToSelection() Stores specified data with the selected object(s).
document.addFilter() Applies a filter to the selected objects.
document.addItem() Adds an item from any open document or library to
the specified Document object.
document.addNewLine() Adds a new path between two points.
document.addNewOval() Adds a new oval in the specified bounding
rectangle.
document.addNewPublishProfile() Adds a new publish profile and makes it the current
one.
document.addNewRectangle() Adds a new rectangle or rounded rectangle, fitting
it into the specified bounds.
document.addNewScene() Adds a new scene (Timeline object) as the next
scene after the currently selected scene and makes
the new scene the currently selected scene.
document.addNewText() Inserts a new empty text field.
document.align() Aligns the selection.
document.allowScreens() Use this method before using the
document.screenOutline property.
document.arrange() Arranges the selection on the Stage.
document.breakApart() Performs a break-apart operation on the current
selection.
Document object 61
Method Description
document.canEditSymbol()
document.canRevert() Determines whether you can use the
document.canTestMovie() Determines whether you can use the
document.canTestScene() Determines whether you can use the
document.changeFilterOrder() Changes the index of the filter in the Filter list.
document.clipCopy() Copies the current selection from the document to
document.clipCut() Cuts the current selection from the document and
document.clipPaste() Pastes the contents of the Clipboard into the
document.close() Closes the specified document.
document.convertLinesToFills() Converts lines to fills on the selected objects.
document.convertToSymbol() Converts the selected Stage item(s) to a new
document.crop() Uses top selected drawing object to crop all
document.deleteEnvelope() Deletes the envelope (bounding box that contains
document.deletePublishProfile() Deletes the currently active profile, if there is more
document.deleteScene() Deletes the current scene (Timeline object) and, if
document.deleteSelection() Deletes the current selection on the Stage.
document.disableAllFilters() Disables all filters on the selected objects.
document.disableFilter() Disables the specified filter in the Filters list.
document.disableOtherFilters() Disables all filters except the one at the specified
document.distribute() Distributes the selection.
Indicates whether Edit Symbols menu and
functionality is enabled.
document.revert() or fl.revertDocument() method
successfully.
document.testMovie() method successfully.
document.testScene() method successfully.
the Clipboard.
writes it to the Clipboard.
document.
symbol.
selected drawing objects underneath it.
one or more objects) from the selected object.
than one.
the deleted scene was not the last one, sets the
next scene as the current Timeline object.
position in the Filters list.
62 Objects
Method Description
document.distributeToLayers() Performs a distribute-to-layers operation on the
current selection; equivalent to selecting Distribute
to Layers.
document.documentHasData() Checks the document for persistent data with the
specified name.
document.duplicatePublishProfile() Duplicates the currently active profile and gives the
duplicate version focus.
document.duplicateScene() Makes a copy of the currently selected scene,
giving the new scene a unique name and making it
the current scene.
document.duplicateSelection() Duplicates the selection on the Stage.
document.editScene() Makes the specified scene the currently selected
scene for editing.
document.enableAllFilters() Enables all the filters on the Filters list for the
selected object(s)
document.enableFilter() Enables the specified filter for the selected
object(s).
document.enterEditMode() Switches the authoring tool into the editing mode
specified by the parameter.
document.exitEditMode() Exits from symbol-editing mode and returns focus
to the next level up from the editing mode.
document.exportPNG() Exports the document as one or more PNG files.
document.exportPublishProfile() Exports the currently active profile to an XML file.
document.exportSWF() Exports the document in the Flash SWF format.
document.getAlignToDocument() Identical to retrieving the value of the To Stage
button in the Align panel.
document.getBlendMode() Returns a string that specifies the blend mode for
the selected object(s).
document.getCustomFill() Retrieves the fill object of the selected shape or, if
specified, the Tools panel and Property inspector.
document.getCustomStroke() Returns the stroke object of the selected shape or,
if specified, the Tools panel and Property inspector.
document.getDataFromDocument() Retrieves the value of the specified data.
document.getElementProperty() Gets the specified Element property for the current
selection.
.
Document object 63
Method Description
document.getElementTextAttr()
document.getFilters() Returns an array that contains the list of filters
document.getMetadata() Returns a string containing the XML metadata
document.getSelectionRect() Gets the bounding rectangle of the current
document.getTextString() Gets the currently selected text.
document.getTimeline() Retrieves the current Timeline object in the
document.getTransformationPoint() Gets the location of the transformation point of the
document.group() Converts the current selection to a group.
document.importPublishProfile() Imports a profile from a file.
document.importFile() Imports a file into the document.
document.importSWF() Imports a SWF file into the document.
document.intersect() Creates an intersection drawing object from all
document.match() Makes the size of the selected objects the same.
document.mouseClick() Performs a mouse click from the arrow tool.
document.mouseDblClk() Performs a double mouse click from the arrow tool.
document.moveSelectedBezierPointsBy() If the selection contains at least one path with at
document.moveSelectionBy() Moves selected objects by a specified distance.
document.optimizeCurves() Optimizes smoothing for the current selection,
document.publish() Publishes the document according to the active
Gets a specified TextAttrs property of the selected
text objects.
applied to the currently selected object(s).
associated with the document.
selection.
document.
current selection.
selected drawing objects.
least one Bézier point selected, this method moves
all selected Bézier points on all selected paths by
the specified amount.
allowing multiple passes, if specified, for optimal
smoothing; equivalent to selecting Modify > Shape >
Optimize.
Publish Settings (File > Publish Settings);
equivalent to selecting File > Publish.
64 Objects
Method Description
document.punch() Uses top selected drawing object to punch through
all selected drawing objects underneath it.
document.removeAllFilters() Removes all filters from the selected object(s).<
document.removeDataFromDocument() Removes persistent data with the specified name
that has been attached to the document.
document.removeDataFromSelection() Removes persistent data with the specified name
that has been attached to the selection.
document.removeFilter() Removes the specified filter from the Filters list of
the selected object(s).
document.renamePublishProfile() Renames the current profile.
document.renameScene() Renames the currently selected scene in the
Scenes panel.
document.reorderScene() Moves the specified scene before another
specified scene.
document.resetTransformation() Resets the transformation matrix; equivalent to
selecting Modify > Transform > Remove transform.
document.revert() Reverts the specified document to its previously
saved version; equivalent to selecting File > Revert.
document.rotateSelection() Rotates the selection by a specified number of
degrees.
document.save() Saves the document in its default location;
equivalent to selecting File > Save.
document.saveAndCompact() Saves and compacts the file; equivalent to
selecting File > Save and Compact.
document.scaleSelection() Scales the selection by a specified amount;
equivalent to using the Free Transform tool to scale
the object.
document.selectAll() Selects all items on the Stage; equivalent to
pressing Control+A (Windows) or Command+A
(Macintosh) or selecting Edit > Select All.
document.selectNone() Deselects any selected items.
document.setAlignToDocument() Sets the preferences for document.align(),
document.distribute(),document.match(), and
document.space() to act on the document;
equivalent to enabling the To Stage button in the
Align panel.
Document object 65
Method Description
document.setBlendMode()
document.setCustomFill() Sets the fill settings for the Tools panel, Property
document.setCustomStroke() Sets the stroke settings for the Tools panel,
document.setElementProperty() Sets the specified Element property on selected
document.setElementTextAttr() Sets the specified TextAttrs property of the
document.setFillColor() Changes the fill color of the selection to the
document.setFilterProperty() Sets a specified filter property for the currently
document.setFilters() Applies filters to the selected objects .
document.setInstanceAlpha() Sets the opacity of the instance.
document.setInstanceBrightness() Sets the brightness for the instance.
document.setInstanceTint() Sets the tint for the instance.
document.setMetadata() Sets the XML metadata for the specified
document.setSelectionBounds() Moves and resizes the selection in a single
document.setSelectionRect() Draws a rectangular selection marquee relative to
document.setStroke() Sets the color, width, and style of the selected
document.setStrokeColor() Changes the stroke color of the selection to the
document.setStrokeSize() Changes the stroke size of the selection to the
document.setStrokeStyle() Changes the stroke style of the selection to the
document.setTextRectangle() Changes the bounding rectangle for the selected
Sets the blend mode for the selected objects.
inspector, and any selected shapes.
Property inspector, and any selected shapes.
object(s) in the document.
selected text items to the specified value.
specified color.
selected object(s).
document, overwriting any existing metadata.
operation.
the Stage, using the specified coordinates.
strokes.
specified color.
specified size.
specified style.
text item to the specified size.
66 Objects
Method Description
document.setTextSelection() Sets the text selection of the currently selected text
field to the values specified by the
endIndex values.
document.setTextString() Inserts a string of text.
document.setTransformationPoint() Moves the transformation point of the current
selection.
document.skewSelection() Skews the selection by a specified amount.
document.smoothSelection() Smooths the curve of each selected fill outline or
curved line.
document.space() Spaces the objects in the selection evenly.
document.straightenSelection() Straightens the currently selected strokes;
equivalent to using the Straighten button in the
Tools panel.
document.swapElement() Swaps the current selection with the specified one.
document.swapStrokeAndFill() Swaps the Stroke and Fill colors.
document.testMovie() Executes a Test Movie operation on the document.
document.testScene() Executes a Test Scene operation on the current
scene of the document.
document.traceBitmap() Performs a trace bitmap on the current selection;
equivalent to selecting Modify > Bitmap > Trace
Bitmap.
document.transformSelection() Performs a general transformation on the current
selection by applying the matrix specified in the
arguments.
document.unGroup() Ungroups the current selection.
document.union() Combines all selected shapes into a drawing
object.
document.unlockAllElements() Unlocks all locked elements on the currently
selected frame.
document.xmlPanel() Posts a XMLUI dialog box.
startIndex and
Document object 67
Property summary for the Document object
You can use the following properties with the Document object.
Property Description
document.accName A string that is equivalent to the Name field in the
Accessibility panel.
document.autoLabel A Boolean value that is equivalent to the Auto
Label check box in the Accessibility panel.
document.backgroundColor A string, hexadecimal value, or integer that
represents the background color.
document.currentPublishProfile A string that specifies the name of the active
publish profile for the specified document.
document.currentTimeline An integer that specifies the index of the active
timeline.
document.description A string that is equivalent to the Description field in
the Accessibility panel.
document.forceSimple A Boolean value that specifies whether the children
of the specified object are accessible.
document.frameRate A float value that specifies the number of frames
displayed per second when the SWF file plays; the
default is 12.
document.height An integer that specifies the height of the
document (Stage) in pixels.
document.library Read-only; the library object for a document.
document.livePreview A Boolean value that specifies if Live Preview is
enabled.
document.name Read-only; a string that represents the name of a
document (FLA file).
document.path Read-only; a string that represents the path of the
document.
document.publishProfiles Read-only; an array of the publish profile names for
the document.
document.screenOutline Read-only; the current ScreenOutline object for the
document.
document.selection An array of the selected objects in the document.
document.silent A Boolean value that specifies whether the object
is accessible.
68 Objects
Property Description
document.timelines Read-only; an array of Timeline objects (see
Timeline object).
document.viewMatrix Read-only; a Matrix object.
document.width An integer that specifies the width of the document
(Stage) in pixels.
document.zoomFactor Specifies the zoom percent of the Stage at author
time.
document.accName
Availability
Flash MX 2004.
Usage
document.accName
Description
Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers
identify objects by reading the name aloud.
Example
The following example sets the accessibility name of the document to "Main Movie":
fl.getDocumentDOM().accName = "Main Movie";
The following example gets the accessibility name of the document:
fl.trace(fl.getDocumentDOM().accName);
document.addDataToDocument()
Availability
Flash MX 2004.
Usage
document.addDataToDocument( name, type, data )
Document object 69
Parameters
name A string that specifies the name of the data to add.
type A string that defines the type of data to add. Acceptable values are type are
"integer", "integerArray", "double", "doubleArray", "string", and "byteArray".
data the value to add. Valid types depend on the type parameter.
Returns
Nothing.
Description
Method; stores specified data with a document. Data is written to the FLA file and is available
to JavaScript when the file reopens.
Example
The following example adds an integer value of 12 to the current document:
fl.getDocumentDOM().addDataToDocument("myData", "integer", 12);
The following example returns the value of the data named "myData" and displays the result
in the Output panel:
fl.trace(fl.getDocumentDOM().getDataFromDocument("myData"));
See also
document.getDataFromDocument(), document.removeDataFromDocument()
document.addDataToSelection()
Availability
Flash MX 2004.
Usage
document.addDataToSelection( name, type, data )
Parameters
name A string that specifies the name of the persistent data.
type Defines the type of data. Acceptable values are "integer", "integerArray",
"double", "doubleArray", "string", and "byteArray".
data The value to add. Valid types depend on the type parameter.
Returns
Nothing.
70 Objects
Description
Method; stores specified data with the selected object(s). Data is written to the FLA file and is
available to JavaScript when the file reopens. Only symbols and bitmaps support persistent
data.
Example
The following example adds an integer value of 12 to the selected object:
fl.getDocumentDOM().addDataToSelection("myData", "integer", 12);
See also
document.removeDataFromSelection()
document.addFilter()
Availability
Flash 8.
Usage
document.addFilter( filterName )
Parameters
filterName A string specifying the filter to be added to the Filter list and enabled for the
selected object(s). Acceptable values are
"blurFilter", "dropShadowFilter", "glowFilter", "gradientBevelFilter", and
"gradientGlowFilter".
"adjustColorFilter", "bevelFilter",
Returns
Nothing.
Description
Method; applies a filter to the selected objects and places the filter at the end of the Filter list.
Example
The following example applies a glow filter to the selected object(s):
fl.getDocumentDOM().addFilter("glowFilter");
See also
document.changeFilterOrder(), document.disableFilter(),
document.enableFilter(), document.getFilters(), document.removeFilter(),
document.setBlendMode(), document.setFilterProperty()
Document object 71
document.addItem()
Availability
Flash MX 2004.
Usage
document.addItem( position, item )
Parameters
position A point that specifies the x and y coordinates of the location at which to add the
item. It uses the center of a symbol or the upper-left corner of a bitmap or video.
item An Item object that specifies the item to add and the library from which to add it (see
Item object).
Returns
A Boolean value: true if successful; false otherwise.
Description
Method; adds an item from any open document or library to the specified Document object.
Example
The following example adds the first item from the library to the first document at the
specified location for the selected symbol, bitmap, or video:
var item = fl.documents[0].library.items[0];
fl.documents[0].addItem({x:0,y:0}, item);
The following example adds the symbol myMovieClip from the current document’s library to
the current document:
var itemIndex = fl.getDocumentDOM().library.findItemIndex("myMovieClip");
var theItem = fl.getDocumentDOM().library.items[itemIndex];
fl.getDocumentDOM().addItem({x:0,y:0}, theItem);
The following example adds the symbol myMovieClip from the second document in the
documents array to the third document in the documents array:
var itemIndex = fl.documents[1].library.findItemIndex("myMovieClip");
var theItem = fl.documents[1].library.items[itemIndex];
fl.documents[2].addItem({x:0,y:0}, theItem);
72 Objects
document.addNewLine()
Availability
Flash MX 2004.
Usage
document.addNewLine( startPoint, endpoint )
Parameters
startpoint A pair of floating-point numbers that specify the x and y coordinates where the
line starts.
endpoint A pair of floating-point numbers that specify the x and y coordinates where the
line ends.
Returns
Nothing.
Description
Method; adds a new path between two points. The method uses the document’s current
stroke attributes and adds the path on the current frame and current layer. This method works
in the same way as clicking on the line tool and drawing a line.
Example
The following example adds a line between the specified starting point and ending point:
fl.getDocumentDOM().addNewLine({x:216.7, y:122.3}, {x:366.8, y:165.8});
document.addNewOval()
Availability
Flash MX 2004.
Usage
document.addNewOval( boundingRectangle [, bSuppressFill [, bSuppressStroke
]] )
Document object 73
Parameters
boundingRectangle A rectangle that specifies the bounds of the oval to be added. For
information on the format of
bSuppressFill A Boolean value that, if set to true, causes the method to create the shape
without a fill. The default value is
bSuppressStroke A Boolean value that, if set to true, causes the method to create the
shape without a stroke. The default value is
boundingRectangle, see document.addNewRectangle().
false. This parameter is optional.
false. This parameter is optional.
Returns
Nothing.
Description
Method; adds a new oval in the specified bounding rectangle. This method performs the same
operation as the oval tool. The method uses the document’s current default stroke and fill
attributes and adds the oval on the current frame and layer. If
the oval is drawn without a fill. If
a stroke. If both
bSuppressFill and bSuppressStroke are set to true, the method has no
bSuppressStroke is set to true, the oval is drawn without
bSuppressFill is set to true,
effect.
Example
The following example adds a new oval within the specified coordinates; it is 164 pixels in
width and 178 pixels in height:
flash.getDocumentDOM().addNewOval({left:72,top:50,right:236,bottom:228});
The following example draws the oval without a fill:
flash.getDocumentDOM().addNewOval({left:72,top:50,right:236,bottom:228},
true);
The following example draws the oval without a stroke:
flash.getDocumentDOM().addNewOval({left:72,top:50,right:236,bottom:228},
false, true);
74 Objects
document.addNewPublishProfile()
Availability
Flash MX 2004.
Usage
document.addNewPublishProfile( [profileName ] )
Parameters
profileName The unique name of the new profile. If you do not specify a name, a default
name is provided. This parameter is optional.
Returns
An integer that is the index of the new profile in the profiles list. Returns -1 if a new profile
cannot be created.
Description
Method; adds a new publish profile and makes it the current one.
Example
The following example adds a new publish profile with a default name and then displays the
name of the profile in the Output panel:
fl.getDocumentDOM().addNewPublishProfile();
fl.outputPanel.trace(fl.getDocumentDOM().currentPublishProfile);
The following example adds a new publish profile with the name "my profile":
fl.getDocumentDOM().addNewPublishProfile("my profile");
See also
document.deletePublishProfile()
document.addNewRectangle()
Availability
Flash MX 2004.
Usage
document.addNewRectangle( boundingRectangle, roundness
[, bSuppressFill [, bSuppressStroke ] ] )
Document object 75
Parameters
boundingRectangle A rectangle that specifies the bounds within which the new rectangle
is added, in the format
left and top values specify the location of the upper-left corner (e.g., left:0,top:0
represents the upper-left of the Stage), and the
{left:value1,top:value2,right:value3,bottom:value4}. The
right and bottom values specify location of
the lower-right corner. Therefore, the width of the rectangle is the difference in value between
left and right, and the height of the rectangle is the difference in value between top and
bottom.
In other words, the rectangle bounds do not all correspond to the values shown in the
Property inspector. The
inspector, respectively. However, the
left and top values correspond to the X and Y values in the Property
right and bottom values don’t correspond to the W and
H values in the Property inspector. For example, consider a rectangle with the following
bounds:
{left:10,top:10,right:50,bottom:100}
This rectangle would display the following values in the Property inspector:
X = 10, Y = 10, W = 40, H = 90
roundness
An integer value from 0 to 999 that specifies the roundness to use for the
corners. The value is specified as number of points. The greater the value, the greater the
roundness.
bSuppressFill A Boolean value that, if set to true, causes the method to create the shape
without a fill. The default value is
bSuppressStroke A Boolean value that, if set to true, causes the method to create the
rectangle without a stroke. The default value is
false. This parameter is optional.
false. This parameter is optional.
Returns
Nothing.
Description
Method; adds a new rectangle or rounded rectangle, fitting it into the specified bounds. This
method performs the same operation as the rectangle tool. The method uses the document’s
current default stroke and fill attributes and adds the rectangle on the current frame and layer.
If the
bSuppressFill parameter is set to true, the rectangle is drawn without a fill. If the
bSuppressStroke parameter is set to true, the rectangle is drawn without a stroke. If both
bSuppressFill and bSuppressStroke are set to true, the method has no effect.
76 Objects
Example
The following example adds a new rectangle with no rounding on the corners within the
specified coordinates; it is 100 pixels in width and in height:
flash.getDocumentDOM().addNewRectangle({left:0,top:0,right:100,bottom:100},
0);
The following example adds a new rectangle with no rounding on the corners and without a
fill; it is 100 pixels in width and 200 in height:
flash.getDocumentDOM().addNewRectangle({left:10,top:10,right:110,bottom:210
},0, true);
The following example adds a new rectangle with no rounding on the corners and without a
stroke; it is 200 pixels in width and 100 in height:
flash.getDocumentDOM().addNewRectangle({left:20,top:20,right:220,bottom:120
},0, false, true);
document.addNewScene()
Availability
Flash MX 2004.
Usage
document.addNewScene( [name] )
Parameters
name Specifies the name of the scene. If you do not specify a name, a new scene name is
generated.
Returns
A Boolean value: true if the scene is added successfully; false otherwise.
Description
Method; adds a new scene (Timeline object) as the next scene after the currently selected
scene and makes the new scene the currently selected scene. If the specified scene name
already exists, the scene is not added and the method returns an error.
Document object 77
Example
The following example adds a new scene named myScene after the current scene in the
current document. The variable
success will be true when the new scene is created; false
otherwise.
var success = flash.getDocumentDOM().addNewScene("myScene");
The following example adds a new scene using the default naming convention. If only one
scene exists, the newly created scene is named
fl.getDocumentDOM().addNewScene();
"Scene 2".
document.addNewText()
Availability
Flash MX 2004.
Usage
document.addNewText( boundingRectangle )
Parameters
boundingRectangle Specifies the size and location of the text field; for information on the
format of
calling
Returns
Nothing.
boundingRectangle, see document.addNewRectangle(). It should be followed by
document.seTextString() to populate the new text box.
Description
Method; inserts a new empty text field.
Example
The following example creates a new text field in the upper-left corner of the Stage and then
sets the text string to
fl.getDocumentDOM().addNewText({left:0, top:0, right:100, bottom:100});
fl.getDocumentDOM().setTextString('Hello World!');
See also
document.setTextString()
78 Objects
"Hello World":
document.align()
Availability
Flash MX 2004.
Usage
document.align( alignmode [, bUseDocumentBounds ] )
Parameters
alignmode A string that specifies how to align the selection. Acceptable values are "left",
"right", "top", "bottom", "vertical center", and "horizontal center".
bUseDocumentBounds A Boolean value that, if set to true, causes the method to align to
the bounds of the document. Otherwise, the method uses the bounds of the selected objects.
The default is
Returns
Nothing.
Description
Method; aligns the selection.
Example
The following example aligns objects to left and to the Stage. This is equivalent to turning on
the To Stage setting in the Align panel and clicking the Align to Left button:
fl.getDocumentDOM().align("left", true);
false. This parameter is optional.
See also
document.distribute(), document.getAlignToDocument(),
document.setAlignToDocument()
document.allowScreens()
Availability
Flash MX 2004.
Usage
document.allowScreens()
Parameters
None.
Document object 79
Returns
A Boolean value: true if document.screenOutline can be used safely; false otherwise.
Description
Method; use before using the document.screenOutline property. If this method returns the
value
true, you can safely access document.screenOutline; Flash displays an error if you
access
document.screenOutline in a document without screens.
Example
The following example determines whether screens methods can be used in the current
document:
if(fl.getDocumentDOM().allowScreens()) {
fl.trace("screen outline is available.");
}
else {
fl.trace("whoops, no screens.");
}
See also
document.screenOutline
document.arrange()
Availability
Flash MX 2004.
Usage
document.arrange( arrangeMode )
Parameters
arrangeMode Specifies the direction in which to move the selection. Acceptable values are
"back", "backward", "forward", and "front". It provides the same capabilities as these
options provide on the Modify >Arrange menu.
Returns
Nothing.
Description
Method; arranges the selection on the Stage. This method applies only to non-shape objects.
80 Objects
Example
The following example moves the current selection to the front:
fl.getDocumentDOM().arrange("front");
document.autoLabel
Availability
Flash MX 2004.
Usage
document.autoLabel
Description
Property; a Boolean value that is equivalent to the Auto Label check box in the Accessibility
panel. You can use this property to tell Flash to automatically label objects on the Stage with
the text associated with them.
Example
The following example gets the value of the autoLabel property and displays the result in the
Output panel:
var isAutoLabel = fl.getDocumentDOM().autoLabel;
fl.trace(isAutoLabel);
The following example sets the autoLabel property to true, telling Flash to automatically
label objects on the Stage:
fl.getDocumentDOM().autoLabel = true;
document.backgroundColor
Availability
Flash MX 2004.
Usage
document.backgroundColor
Description
Property; the color of the background, in one of the following formats:
■ A string in the format "#RRGGBB" or "#RRGGBBAA"
■ A hexadecimal number in the format 0xRRGGBB
■ An integer that represents the decimal equivalent of a hexadecimal number
Document object 81
Example
The following example sets the background color to black:
fl.getDocumentDOM().backgroundColor = '#000000';
document.breakApart()
Availability
Flash MX 2004.
Usage
document.breakApart()
Parameters
None.
Returns
Nothing.
Description
Method; performs a break-apart operation on the current selection.
Example
The following example breaks apart the current selection:
fl.getDocumentDOM().breakApart();
document.canEditSymbol()
Availability
Flash MX 2004.
Usage
document.canEditSymbol()
Parameters
None.
Returns
A Boolean value: true if the Edit Symbols menu and functionality are available for use; false
otherwise.
82 Objects
Description
Method; indicates whether the Edit Symbols menu and functionality are enabled. This is not
related to whether the selection can be edited. This method should not be used to test
whether
Example
fl.getDocumentDOM().enterEditMode() is allowed.
The following example displays in the Output panel the state of the Edit Symbols menu and
functionality:
fl.trace("fl.getDocumentDOM().canEditSymbol() returns: " +
fl.getDocumentDOM().canEditSymbol());
document.canRevert()
Availability
Flash MX 2004.
Usage
document.canRevert()
Parameters
None.
Returns
A Boolean value: true if you can use the document.revert() or fl.revertDocument()
methods successfully;
false otherwise.
Description
Method; determines whether you can use the document.revert() or
fl.revertDocument() method successfully.
Example
The following example checks whether the current document can revert to the previously
saved version. If so,
if(fl.getDocumentDOM().canRevert()){
fl.getDocumentDOM().revert();
}
fl.getDocumentDOM().revert() restores the previously saved version.
Document object 83
document.canTestMovie()
Availability
Flash MX 2004.
Usage
document.canTestMovie()
Parameters
None.
Returns
A Boolean value: true if you can use the document.testMovie() method successfully:
false otherwise.
Description
Method; determines whether you can use the document.testMovie() method successfully.
Example
The following example tests whether fl.getDocumentDOM().testMovie() can be used. If
so, it calls the method.
if(fl.getDocumentDOM().canTestMovie()){
fl.getDocumentDOM().testMovie();
}
See also
document.canTestScene(), document.testScene()
document.canTestScene()
Availability
Flash MX 2004.
Usage
document.canTestScene()
Parameters
None.
84 Objects
Returns
A Boolean value: true if you can use the document.testScene() method successfully;
false otherwise.
Description
Method; determines whether you can use the document.testScene() method successfully.
Example
The following example first tests whether fl.getDocumentDOM().testScene() can be used
successfully. If so, it calls the method.
if(fl.getDocumentDOM().canTestScene()){
fl.getDocumentDOM().testScene();
}
See also
document.canTestMovie(), document.testMovie()
document.changeFilterOrder()
Availability
Flash 8.
Usage
document.changeFilterOrder( oldIndex, newIndex )
Parameters
oldIndex An integer that represents the current zero-based index position of the filter you
want to reposition in the Filters list.
newIndex An integer that represents the new index position of the filter in the list.
Returns
Nothing.
Description
Method; changes the index of the filter in the Filter list. Any filters above or below newIndex
are shifted up or down accordingly. For example, using the filters shown below, if you issue
the command
fl.getDocumentDOM().changeFilterOrder(3, 0), the filters are rearranged
as follows:
Before: blurFilter, dropShadowFilter, glowFilter, gradientBevelFilter
After: gradientBevelFilter, blurFilter, dropShadowFilter, glowFilter
Document object 85
If you then issue the command fl.getDocumentDOM().changeFilterOrder(0, 2), the
filters are rearranged as follows:
Before: gradientBevelFilter, blurFilter, dropShadowFilter, glowFilter
After: blurFilter, dropShadowFilter, gradientBevelFilter, glowFilter
Example
The following example moves the filter that is currently in the second position in the Filter list
to the first position:
fl.getDocumentDOM().changeFilterOrder(1,0);
See also
document.addFilter(), document.disableFilter(), document.enableFilter(),
document.getFilters(), document.removeFilter(), Filter object
document.clipCopy()
Availability
Flash MX 2004.
Usage
document.clipCopy()
Parameters
None.
Returns
Nothing.
Description
Method; copies the current selection from the document to the Clipboard.
Example
The following example copies the current selection from the document to the Clipboard:
fl.getDocumentDOM().clipCopy();
86 Objects
document.clipCut()
Availability
Flash MX 2004.
Usage
document.clipCut()
Parameters
None.
Returns
Nothing.
Description
Method; cuts the current selection from the document and writes it to the Clipboard.
Example
The following example cuts the current selection from the document and writes it to the
Clipboard:
fl.getDocumentDOM().clipCut();
document.clipPaste()
Availability
Flash MX 2004.
Usage
document.clipPaste( [bInPlace] )
Parameters
bInPlace A Boolean value that, when set to true, causes the method to perform a paste-in-
place operation. The default value is
false, which causes the method to perform a paste
operation to the center of the document. This parameter is optional.
Returns
Nothing.
Description
Method; pastes the contents of the Clipboard into the document.
Document object 87
Example
The following examples pastes the Clipboard contents to the center of the document:
fl.getDocumentDOM().clipPaste();
The following example pastes the Clipboard contents in place in the current document:
fl.getDocumentDOM().clipPaste(true);
document.close()
Availability
Flash MX 2004.
Usage
document.close( [bPromptToSaveChanges] )
Parameters
bPromptToSaveChanges A Boolean value that, when set to true, causes the method to
prompt the user with a dialog box if there are unsaved changes in the document. If
bPromptToSaveChanges is set to false, the user is not prompted to save any changed
documents. The default value is
Returns
Nothing.
true. This parameter is optional.
Description
Method; closes the specified document.
Example
The following example closes the current document and prompts the user with a dialog box to
save changes:
fl.getDocumentDOM().close();
The following example closes the current document without saving changes:
fl.getDocumentDOM().close(false);
88 Objects
document.convertLinesToFills()
Availability
Flash MX 2004.
Usage
document.convertLinesToFills()
Parameters
None.
Returns
Nothing.
Description
Method; converts lines to fills on the selected objects.
Example
The following example converts the current selected lines to fills:
fl.getDocumentDOM().convertLinesToFills();
document.convertToSymbol()
Availability
Flash MX 2004.
Usage
document.convertToSymbol( type, name, registrationPoint )
Parameters
type A string that specifies the type of symbol to create. Acceptable values are "movie
, "button", and "graphic".
clip"
name A string that specifies the name for the new symbol, which must be unique. You can
submit an empty string to have this method create a unique symbol name for you.
registration point Specifies the point that represents the 0,0 location for the symbol.
Acceptable values are:
"center", "center right", "bottom left", "bottom center", and "bottom right".
Returns
"top left", "top center", "top right", "center left",
An object for the newly created symbol, or null if it cannot create the symbol.
Document object 89
Description
Method; converts the selected Stage item(s) to a new symbol. For information on defining
linkage and shared asset properties for a symbol, see Item object.
Example
The following examples create a movie clip symbol with a specified name, a button symbol
with a specified name, and a movie clip symbol with a default name:
newMc = fl.getDocumentDOM().convertToSymbol("movie clip", "mcSymbolName",
"top left");
newButton = fl.getDocumentDOM().convertToSymbol("button", "btnSymbolName",
"bottom right");
newClipWithDefaultName = fl.getDocumentDOM().convertToSymbol("movie clip",
"", "top left");
document.crop()
Availability
Flash 8.
Usage
document.crop()
Parameters
None.
Returns
A Boolean value: true if successful; false otherwise.
Description
Method; uses the top selected drawing object to crop all selected drawing objects underneath
it. This method returns
false if there are no drawing objects selected or if any of the selected
items are not drawing objects.
Example
The following example crops the currently selected objects:
fl.getDocumentDOM().crop();
See also
document.deleteEnvelope(), document.intersect(), document.punch(),
document.union(), shape.isDrawingObject
90 Objects
document.currentPublishProfile
Availability
Flash MX 2004.
Usage
document.currentPublishProfile
Description
Property; a string that specifies the name of the active publish profile for the specified
document.
Example
The following example adds a new publish profile with the default name and then displays the
name of the profile in the Output panel:
fl.getDocumentDOM().addNewPublishProfile();
fl.outputPanel.trace(fl.getDocumentDOM().currentPublishProfile);
The following example changes the selected publish profile to "Default":
fl.getDocumentDOM().currentPublishProfile = "Default";
document.currentTimeline
Availability
Flash MX 2004.
Usage
document.currentTimeline
Description
Property; an integer that specifies the index of the active timeline. You can set the active
timeline by changing the value of this property; the effect is almost equivalent to calling
document.editScene(). The only difference is that you don’t get an error message if the
index of the timeline is not valid; the property is simply not set, which causes silent failure.
Example
The following example displays the index of the current timeline.
var myCurrentTL = fl.getDocumentDOM().currentTimeline;
fl.trace("The index of the current timeline is: "+ myCurrentTL);
Document object 91
The following example changes the active timeline from the main timeline to a scene named
"myScene".
var i = 0;
var curTimelines = fl.getDocumentDOM().timelines;
while(i < fl.getDocumentDOM().timelines.length){
if(curTimelines[i].name == "myScene"){
fl.getDocumentDOM().currentTimeline = i;
}
++i;
}
See also
document.getTimeline()
document.deleteEnvelope()
Availability
Flash 8.
Usage
document.deleteEnvelope();
Parameters
None.
Returns
A Boolean value: true if successful; false otherwise.
Description
Method; deletes the envelope (bounding box that contains one or more objects) from the
selected objects.
Example
The following example deletes the envelope from the selected objects:
fl.getDocumentDOM().deleteEnvelope();
See also
document.crop(), document.intersect(), document.punch(), document.union(),
shape.isDrawingObject
92 Objects
document.deletePublishProfile()
Availability
Flash MX 2004.
Usage
document.deletePublishProfile()
Parameters
None.
Returns
An integer that is the index of the new current profile. If a new profile is not available, the
method leaves the current profile unchanged and returns its index.
Description
Method; deletes the currently active profile, if there is more than one. There must be at least
one profile left.
Example
The following example deletes the currently active profile, if there is more than one, and
displays the index of the new currently active profile:
alert(fl.getDocumentDOM().deletePublishProfile());
See also
document.addNewPublishProfile()
document.deleteScene()
Availability
Flash MX 2004.
Usage
document.deleteScene()
Parameters
None.
Returns
A Boolean value: true if the scene is successfully deleted; false otherwise.
Document object 93
Description
Method; deletes the current scene (Timeline object) and, if the deleted scene was not the last
one, sets the next scene as the current Timeline object. If the deleted scene was the last one, it
sets the first object as the current Timeline object. If only one Timeline object (scene) exists, it
returns the value
Example
false.
Assuming there are three scenes (Scene0, Scene1, and Scene2) in the current document, the
following example makes
fl.getDocumentDOM().editScene(2);
var success = fl.getDocumentDOM().deleteScene();
Scene2 the current scene and then deletes it:
document.deleteSelection()
Availability
Flash MX 2004.
Usage
document.deleteSelection()
Parameters
None.
Returns
Nothing.
Description
Method; deletes the current selection on the Stage. Displays an error message if there is no
selection.
Example
The following example deletes the current selection in the document:
fl.getDocumentDOM().deleteSelection();
94 Objects
document.description
Availability
Flash MX 2004.
Usage
document.description
Description
Property; a string that is equivalent to the Description field in the Accessibility panel. The
description is read by the screen reader.
Example
The following example sets the description of the document:
fl.getDocumentDOM().description= "This is the main movie";
The following example gets the description of the document and displays it in the Output
panel:
fl.trace(fl.getDocumentDOM().description);
document.disableAllFilters()
Availability
Flash 8.
Usage
document.disableAllFilters()
Parameters
None.
Returns
Nothing.
Description
Method; disables all filters on the selected objects.
Document object 95
Example
The following example disables all filters on the selected objects:
fl.getDocumentDOM().disableAllFilters();
See also
document.addFilter(), document.changeFilterOrder(), document.disableFilter(),
document.disableOtherFilters(), document.enableAllFilters(),
document.getFilters(), document.removeAllFilters(), Filter object
document.disableFilter()
Availability
Flash 8.
Usage
document.disableFilter( filterIndex )
Parameters
filterIndex An integer representing the zero-based index of the filter in the Filter list.
Returns
Nothing.
Description
Method; disables the specified filter in the Filters list.
Example
The following example disables the first and third filters (index values of 0 and 2) in the
Filters list from the selected object(s):
fl.getDocumentDOM().disableFilter(0);
fl.getDocumentDOM().disableFilter(2);
See also
document.addFilter(), document.changeFilterOrder(),
document.disableAllFilters(), document.disableOtherFilters(),
document.enableFilter(), document.getFilters(), document.removeFilter(), Filter
object
96 Objects
document.disableOtherFilters()
Availability
Flash 8.
Usage
document.disableOtherFilters( enabledFilterIndex )
Parameters
enabledFilterIndex An integer representing the zero-based index of the filter that should
remain enabled after other filters are disabled.
Returns
Nothing.
Description
Method; disables all filters except the one at the specified position in the Filters list.
Example
The following example disables all filters except the second filter in the list (index value of 1):
fl.getDocumentDom().disableOtherFilters(1);
See also
document.addFilter(), document.changeFilterOrder(),
document.disableAllFilters(), document.disableFilter(),
document.enableFilter(), document.getFilters(), document.removeFilter(), Filter
object
document.distribute()
Availability
Flash MX 2004.
Usage
document.distribute( distributemode [, bUseDocumentBounds ] )
Document object 97
Parameters
distributemode A string that specifies where to distribute the selected object. Acceptable
values are
center"
bUseDocumentBounds A Boolean value that, when set to true, distributes the selected
"left edge", "horizontal center", "right edge", "top edge", "vertical
, and "bottom edge".
objects using the bounds of the document. Otherwise, the method uses the bounds of the
selected object. The default is
Returns
false.
Nothing.
Description
Method; distributes the selection.
Example
The following example distributes the selected objects by the top edge:
fl.getDocumentDOM().distribute("top edge");
The following example distributes the selected objects by top edge and expressly sets the
bUseDcoumentBounds parameter:
fl.getDocumentDOM().distribute("top edge", false);
The following example distributes the selected objects by their top edges, using the bounds of
the document:
fl.getDocumentDOM().distribute("top edge", true);
See also
document.getAlignToDocument(), document.setAlignToDocument()
document.distributeToLayers()
Availability
Flash MX 2004.
Usage
document.distributeToLayers()
Parameters
None.
98 Objects
Returns
Nothing.
Description
Method; performs a distribute-to-layers operation on the current selection—equivalent to
selecting Distribute to Layers. This method displays an error if there is no selection.
Example
The following example distributes the current selection to layers:
fl.getDocumentDOM().distributeToLayers();
document.documentHasData()
Availability
Flash MX 2004.
Usage
document.documentHasData( name )
Parameters
name A string that specifies the name of the data to check.
Returns
A Boolean value: true if the document has persistent data; false otherwise.
Description
Method; checks the document for persistent data with the specified name.
Example
The following example checks the document for persistent data with the name "myData":
var hasData = fl.getDocumentDOM().documentHasData("myData");
See also
document.addDataToDocument(), document.getDataFromDocument(),
document.removeDataFromDocument()
Document object 99
document.duplicatePublishProfile()
Availability
Flash MX 2004.
Usage
document.duplicatePublishProfile( [profileName ] )
Parameters
profileName A string that specifies the unique name of the duplicated profile. If you do
not specify a name, the method uses the default name. This parameter is optional.
Returns
An integer that is the index of the new profile in the profile list. Returns -1 if the profile
cannot be duplicated.
Description
Method; duplicates the currently active profile and gives the duplicate version focus.
Example
The following example duplicates the currently active profile and displays the index of the
new profile in the Output panel:
fl.trace(fl.getDocumentDOM().duplicatePublishProfile("dup profile"));
document.duplicateScene()
Availability
Flash MX 2004.
Usage
document.duplicateScene()
Parameters
None.
Returns
A Boolean value: true if the scene is duplicated successfully; false otherwise.
Description
Method; makes a copy of the currently selected scene, giving the new scene a unique name
and making it the current scene.
100 Objects
Loading...