MACROMEDIA DIRECTOR MX 2004-DIRECTOR SCRIPTING Service manual

DIRECTOR
®
MX
2004
Director Scripting Reference

Trademarks
ActiveEdit, ActiveTest, Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain,
Authorware, Authorware Star, Backstage, Blue Sky Software, Blue Sky, Breeze, Bright Tiger, Clustercats, ColdFusion, Contents
Tab Composer, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT,
Extreme 3D, Fireworks, Flash, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, Help
To Source, HomeSite, Hotspot Studio, HTML Help Studio, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects,
Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia,
Macromedia Action!, Macromedia Central, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra,
Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC
Logo and Design, Mediamaker, Movie Critic, Open Sesame!, RoboDemo, RoboEngine JFusion, RoboHelp, RoboHelp Office,
RoboInfo, RoboInsight, RoboPDF, 1-Step RoboPDF, RoboFlash, RoboLinker, RoboScreenCapture, ReSize, Roundtrip,
Roundtrip HTML, Shockwave, Sitespring, Smart Publishing Wizard, Software Video Camera, SoundEdit, Titlemaker,
UltraDev, Web Design 101, what the web can be, WinHelp, WinHelp 2000, WinHelp BugHunter, WinHelp Find+, WinHelp
Graphics Locator, WinHelp Hyperviewer, WinHelp Inspector, and Xtra 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.
Apple Disclaimer
APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE
ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.
THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC
LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO
STATE.
Copyright © 2004 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 prior written approval of
Macromedia, Inc.
Second Edition: September 2004
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
CHAPTER 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
What’s new with Director scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What’s new in this documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Finding information about scripting in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CHAPTER 2: Director Scripting Essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Types of scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Scripting terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Scripting syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Literal values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Conditional constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Events, messages, and handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Linear lists and property lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
JavaScript syntax arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CHAPTER 3: Writing Scripts in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Choosing between Lingo and JavaScript syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Scripting in dot syntax format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Introducing the Director objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object model diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Top level functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Introduction to object-oriented programming in Director . . . . . . . . . . . . . . . . . . 54
Object-oriented programming with Lingo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Object-oriented programming with JavaScript syntax . . . . . . . . . . . . . . . . . . . . . . 65
Writing scripts in the Script window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

4 Contents
CHAPTER 4: Debugging Scripts in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Good scripting habits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Basic debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Debugging in the Script window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Debugging in the Message window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Debugging in the Object inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Debugging in the Debugger window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Debugging projectors and Shockwave movies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Advanced debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
CHAPTER 5: Director Core Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
CHAPTER 6: Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
CHAPTER 7: Scripting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
CHAPTER 8: 3D Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
CHAPTER 9: Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
CHAPTER 10: Events and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
CHAPTER 11: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
CHAPTER 12: Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
CHAPTER 13: Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
CHAPTER 14: Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103

5
CHAPTER 1
Introduction
This reference provides conceptual and how-to information about scripting in Macromedia
Director MX 2004, and also provides reference descriptions and examples for the scripting
application programming interfaces (APIs) that you use to write scripts.
The scripting APIs are the means by which you access the functionality of Director through
script to add interactivity to a movie. By using these APIs, you can create interactive functionality
that is identical to that provided by the prewritten behaviors that are shipped with Director, in
addition to functionality that is more powerful and more varied than that provided by the
prewritten behaviors.
The prewritten behaviors enable you to add basic interactive functionality to a movie, such as
moving the playhead to a frame number or marker, or zooming in when a user clicks a sprite.
They also enable non-interactive functionality such as sprite animation, media loading, and frame
navigation. The scripting APIs enable you to extend and customize these types of functionality.
Intended audience
This reference is intended for you if you want to do any of the following:
•Extend the existing functionality of prewritten behaviors by using script.
•Add functionality to a movie by using script instead of prewritten behaviors.
•Add more powerful, varied, and custom functionality to a movie than that provided by
prewritten behaviors.
This reference is intended to provide all the information, from basic to advanced, you need to add
interactivity to your movies by using script. Therefore, you do not need to have any prior
scripting experience to write effective scripts in Director.
Regardless of your experience level with Director, Lingo, or JavaScript syntax, take a few moments
to browse Chapter 2, “Director Scripting Essentials,” on page 9 and Chapter 3, “Writing Scripts
in Director,” on page 49 before you begin writing scripts. Like any product, Director has its own
unique set of scripting conventions, types of data, and so on. You will need to be comfortable
with these unique characteristics of Director before you can write effective scripts.

6 Chapter 1: Introduction
What’s new with Director scripting
If you have written scripts in previous versions of Director, you should note some new and
important changes about scripting in this latest release.
Dot syntax scripting format
In previous releases of Director, you could write Lingo scripts by using two types of syntax:
verbose syntax or dot syntax. Verbose syntax was very similar to English, and was relatively easy
for new programmers to learn. However, verbose syntax scripts quickly became long and complex,
and were difficult to debug.
Now that the scripting model of Director is compatible with both Lingo and JavaScript syntax,
scripts should be written only in dot syntax. Dot syntax will be familiar to many programmers,
since it is the syntax used in most object-oriented languages such as Java or C++, and in many
web-based scripting languages such as Microsoft JScript or JavaScript.
To support backwards compatibility, scripts written by using verbose syntax in previous versions
of Director will still run. However, starting with Director MX 2004, dot syntax is the
recommended syntax to use, and is the only syntax that will be supported and documented in
the future.
For more information on using dot syntax to write scripts, see “Scripting in dot syntax format”
on page 50.
JavaScript syntax compatibility
Director is now compatible with JavaScript syntax. This means that in addition to being able to
author and debug scripts by using Lingo, which is the long-time scripting language of Director,
you can choose to author and debug scripts by using JavaScript syntax. The implementation of
JavaScript in Director is referred to as JavaScript syntax throughout this reference.
The support of JavaScript syntax in Director helps create a scripting environment that is familiar
not only to JavaScript developers but also to developers experienced with Macromedia Flash
ActionScript, Macromedia Flash Communication Server, Macromedia Dreamweaver,
Macromedia Authorware, and a number of other environments.
The implementation of JavaScript syntax in Director is JavaScript 1.5, which means that it is fully
compliant with the ECMAScript Language Specification ECMA-262, 3rd Edition. Almost all of
the features and functionality in JavaScript 1.5 are now available in Director.
For more information on choosing Lingo or JavaScript syntax, see “Choosing between Lingo and
JavaScript syntax” on page 49.
Note: This reference is intended to only discuss the features and functionality of the JavaScript 1.5
implementation that are essential to writing JavaScript syntax scripts in Director. It is not intended to
provide a complete reference for JavaScript 1.5. For more detailed information on JavaScript 1.5 than
is provided in this reference, see one of the many third-party resources on the subject.
New ways to access the scripting APIs
In this release of Director, the scripting APIs have been grouped into objects, and are accessed
through these objects. These objects contain the functionality required to add interactivity to
your movies and are accessible to both Lingo and JavaScript syntax within Director, projectors,
and Macromedia Shockwave Player.

Finding information about scripting in Director 7
Although the way you access the scripting APIs in this release may vary from previous releases,
you still have access to the same APIs that you did before, in addition to some brand new ones.
The only difference is that you access them by using the new objects.
For more information on the objects and their corresponding scripting APIs, see “Introducing the
Director objects” on page 51.
What’s new in this documentation
If you learned how to script in previous versions of Director, you should know about some
changes in the scripting documentation for this release. The Director Scripting Reference takes the
place of the Lingo Dictionary that was shipped with previous versions of Director. This reference is
organized differently than the Lingo Dictionary.
In the Lingo Dictionary, information about the scripting model was organized by feature.
For example, if you wanted to learn how to work with sprites in script, you looked up that
information in one of the sections under the Sprites heading, such as Dragging Sprites, Sprite
Dimensions, and so on. In addition, all of the scripting APIs were listed in a single alphabetical
list, which meant that all functions, properties, events, and so on were mixed together
alphabetically.
In the Director Scripting Reference, information about the scripting model is organized by object.
This organization closely reflects the organization of the actual scripting objects that you use in
your scripts. For example, if you want to find out how to work with sprites in script, you should
look for the Sprite section in the chapter, Director Core Objects.
The scripting APIs are still listed in alphabetical order, but they are categorized by API type. For
example, all methods are listed alphabetically under the Methods heading, all properties are listed
alphabetically under the Properties heading, and so on.
Finding information about scripting in Director
With its new organization, the Director Scripting Reference contains the following topics:
Director Scripting Essentials Provides information about the basic scripting concepts and
components you will use when scripting in Director.
Writing Scripts in Director Provides information about the Director scripting environment in
addition to advanced scripting concepts and techniques.
Debugging Scripts in Director Provides information about how to find problems in your
scripts when they are not performing as expected.
Director Core Objects Provides a list of the objects and APIs that you use to access the core
functionality and features in Director, such as the Director player engine, movie windows, sprites,
sounds, and so on.
Media Types Provides a list of the media types and APIs that you use to access the functionality
of the various media types in Director, such as RealMedia, DVD, Animated GIF, and so on, that
are added to movies as cast members.
Scripting Objects Provides a list of the scripting objects, also known as Xtra extensions, and
APIs that you use to extend core Director functionality. Xtra extensions provide capabilities such
as importing filters and connecting to the Internet.
3D Objects Provides a list of the objects you use to add 3D functionality to a movie.

8 Chapter 1: Introduction
Constants Provides a list of the constants that are available in Director.
Events and Messages Provides a list of the events that are available in Director.
Keywords Provides a list of the keywords that are available in Director.
Methods Provides a list of the methods that are available in Director.
Operators Provides a list of the operators that are available in Director.
Properties Provides a list of the properties that are available in Director.

9
CHAPTER 2
Director Scripting Essentials
If you are new to scripting in Macromedia Director MX 2004, you may want to take some time
to learn the basic scripting concepts that are essential to understanding how to script in Director
before you begin. Some of these essentials include definitions of important terms, syntax rules,
available data types, and information about the basic elements of scripting in Director—for
example, variables, arrays, operators, and so on.
Types of scripts
A Director movie can contain four types of scripts: behaviors, movie scripts, parent scripts, and
scripts attached to cast members. Behaviors, movie scripts, and parent scripts all appear as
independent cast members in the Cast window. A script attached to a cast member is associated
with that cast member in the Cast window and does not appear independently.
•Behaviors are scripts that are attached to sprites or frames in the Score, and are referred to as
sprite behaviors or frame behaviors. The Cast window thumbnail for each behavior contains a
behavior icon in the lower right corner.
When used in the Director Scripting Reference, the term behavior refers to any script that you
attach to a sprite or a frame. This differs from the behaviors that come in the Director Library
Palette. For more information on these behaviors, which are built into Director, see the Using
Director topics in the Director Help Panel.
All behaviors that have been added to a cast library appear in the Behavior inspector’s Behavior
pop-up menu. Other types of scripts do not appear there.
You can attach the same behavior to more than one location in the Score. When you edit a
behavior, the edited version is applied everywhere the behavior is attached in the Score.
•Movie scripts contain handlers that are available globally, or on a movie level. Event handlers in
a movie script can be called from other scripts in the movie as the movie plays.
A movie script icon appears in the lower right corner of the movie script’s Cast window
thumbnail.
Movie scripts are available to the entire movie, regardless of which frame the movie is in or
which sprites the user is interacting with. When a movie plays in a window or as a linked
movie, a movie script is available only to its own movie.

10 Chapter 2: Director Scripting Essentials
•Parent scripts are special scripts that contain Lingo that is used to create child objects. You can
use parent scripts to generate script objects that behave and respond similarly yet can still
operate independently of each other. A parent script icon appears in the lower right corner of
the Cast window thumbnail.
For information on using parent scripts and child objects, see “Object-oriented programming
with Lingo” on page 55.
JavaScript syntax does not use parent scripts or child objects; it uses regular JavaScript syntax-
style object-oriented programming techniques. For information on object-oriented
programming in JavaScript syntax, see “Object-oriented programming with JavaScript syntax”
on page 65
•Scripts attached to cast members are attached directly to a cast member, independent of the
Score. Whenever the cast member is assigned to a sprite, the cast member’s script is available.
Unlike behaviors, movie scripts, and parent scripts, cast member scripts do not appear in the
Cast window. However, if Show Cast Member Script Icons is selected in the Cast Window
Preferences dialog box, cast members that have a script attached display a small script icon in
the lower left corner of their thumbnails in the Cast window.
Scripting terminology
Both Lingo and JavaScript syntax use some terms that are specific to each language, in addition to
some terms that are shared between each language.
Important scripting terms are listed here in alphabetical order. These terms are used throughout
the Director Scripting Reference, so it will help to understand these terms before moving forward.
•Constants are elements whose values do not change. For example, in Lingo, constants such as
TAB, EMPTY, and RETURN always have the same values, and cannot be modified. In JavaScript
syntax, constants such as Math.PI and Number.MAX_VALUE always have the same values, and
cannot be modified. You can also create your own custom constants in JavaScript syntax by
using the keyword const.
For more information on constants, see “Constants” on page 20.
•Events are actions that occur while a movie is playing. Events occur when a movie stops, a
sprite starts, the playhead enters a frame, the user types at the keyboard, and so on. All events
in Director are predefined, and always have the same meaning.
For more information on events, see “Events” on page 33.
•Expressions are any part of a statement that produces a value. For example, 2 + 2 is
an expression.
•Functions refer to either top-level functions or specific types of JavaScript syntax code.
A top-level function instructs a movie to do something while the movie is playing or returns a
value, but it is not called from any specific object. For example, you would call the top-level
list() function by using the syntax list(). Like a function, a method also instructs a movie
to do something while the movie is playing or returns a value, but it is always called from
an object.
A function is used in JavaScript syntax to represent an event handler, a custom object, a custom
method, and so on. The use of JavaScript functions in these cases is described in the applicable
topics later in this reference.