MACROMEDIA DIRECTOR MX 2004-DIRECTOR SCRIPTING Service manual

DIRECTOR

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.

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

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

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.

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.

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA FLASH MX 2004-ACTIONSCRIPT LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA COLFUSION MX 7 - INSTALLING AND USING COLDFUSION... Guide

MACROMEDIA

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

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA FLASH 8-GETTING STARTED WITH FLASH User manual

MACROMEDIA

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

MACROMEDIA

MACROMEDIA FLEX-CREATING ADVANCED COMPONENTS User manual

MACROMEDIA

MACROMEDIA FLEX-FLEX ACTIONSCRIPT LANGUAGE Service manual

MACROMEDIA

MACROMEDIA CONTRIBUTE-USING CONTRIBUTE Mounting instructions

MACROMEDIA

MACROMEDIA FREEHAND 10-USING FREEHAND Mounting instructions

MACROMEDIA

MACROMEDIA BREEZE Quick reference guide

MACROMEDIA

MACROMEDIA COLDFUSION 5 - INSTALING AND CONFIGURING... User manual

MACROMEDIA

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

MACROMEDIA

MACROMEDIA DREAMWEAVER 8-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA DREAMWEAVER 8-EXTENDING DREAMWEAVER User manual

MACROMEDIA

MACROMEDIA STUDIO 8-EXPLORING STUDIO 8 User manual

MACROMEDIA

MACROMEDIA COLDFUSION STUDIO 4.5-USING COLDFUSION... Mounting instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA CONTRIBUTE 3-DEPLOYING CONTRIBUTE User manual

MACROMEDIA

MACROMEDIA BREEZE-CLUSTERING BREEZE PRESENTATION... User manual

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 5-DEVELOPING User manual

MACROMEDIA

MACROMEDIA BREEZE-FOR MEETING PARTICIPANTS User manual

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual