Macromedia MX 2004 User Guide

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

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

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

4 Contents

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.

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.

6 Chapter 1: Introduction

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.

Finding information about scripting in Director 7

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.

8 Chapter 1: Introduction

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.

• 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 syntaxstyle 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 cannot be modified. You can also create your own custom constants in JavaScript syntax by using the keyword

For more information on constants, see “Constants” on page 20.

Math.PI and Number.MAX_VALUE always have the same values, and

const.

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

10 Chapter 2: Director Scripting Essentials

• Handlers, or event handlers, are sets of statements within a script that run in response to a

specific event and subsequent message. When an event occurs, Director generates and sends a corresponding message to scripts, and a corresponding handler runs in response to the message. The names of handlers are always the same as the events and messages they respond to.

Note: Although in JavaScript syntax an event is actually handled by a function, the term handler is used generically throughout this reference to refer to both Lingo handlers and JavaScript syntax functions that handle events.

For more information on handlers, see “Handlers” on page 35.

• Keywords are reserved words that have a special meaning. For example, in Lingo, the keyword

end indicates the end of a handler. In JavaScript syntax, the keyword var indicates that the

term following it is a variable.

• Lists (Lingo) or Arrays (JavaScript syntax) are ordered sets of values used to track and update

an array of data, such as a series of names or the values assigned to a set of variables. A simple example is a list of numbers such as

[1, 4, 2].

For more information on using lists in both Lingo and JavaScript syntax, see “Linear lists and

property lists” on page 38.

For more information on using JavaScript syntax arrays, see “JavaScript syntax arrays”

on page 45.

• Messages are notices that Director sends to scripts when specific events occur in a movie. For

example, when the playhead enters a specific frame, the Directors sends an

enterFrame message. If a script contains an enterFrame handler, the

statements within that handler will run, because the handler received the If no scripts contain a handler for a message, the message is ignored in script.

For more information on messages, see “Messages” on page 34

enterFrame event occurs and

enterFrame message.

• Methods are terms that either instruct a movie to do something while the movie is playing or

return a value, and are called from an object. For example, you would call the method from the Movie object, using the syntax

_movie.insertFrame(). Although similar in

functionality to top-level functions, methods are always called from an object, and top-level functions are not.

insertFrame()

• Operators are terms that calculate a new value from one or more values. For example, the

addition ( For more information on operators, see “Operators” on page 25.

+) operator adds two or more values together to produce a new value.

• Parameters are placeholders that let you pass values to scripts. Parameters only apply to

methods and event handlers, and not to properties. They are required by some methods and optional for others.

For example, the Movie object’s optionally specifies the name of the movie that frame is in. To perform this task, the method requires at least one parameter, and allows for a second parameter. The first required parameter specifies what frame to send the playhead to, and the second optional parameter specifies what movie the frame is in. Because the first parameter is required, a script error will result if it is not present when the optional, the method will perform its task even if the parameter is not present.

go() method sends the playhead to specific frame, and

go()

go() method is called. Because the second parameter is

Scripting terminology 11

• Properties are attributes that define an object. For example, a sprite in a movie has specific

attributes, such as how wide it is, how tall it is, its background color, and so on. To access the values of these three specific attributes, you would use the Sprite object’s

backColor properties.

width, height, and

For more information on assigning properties to variables, see “Storing and updating values in

variables” on page 21.

• Statements are valid instructions that Director can execute. All scripts are made up of sets of

statements. The following Lingo is a single complete statement.

_movie.go("Author")

For more information on writing script statements, see “Scripting in dot syntax format”

on page 50

• Variables are elements used to store and update values. Variables must start with a letter, an

underscore ( digits (0-9). To assign values to variables or change the values of many properties, you use the equals (

For more information on using variables, see “Variables” on page 21.

_), or the dollar sign ($). Subsequent characters in a variable name can also be

=) operator.

Scripting syntax

The following are general syntax rules that apply to Lingo and JavaScript syntax.

• Comment markers vary between Lingo and JavaScript syntax.

All Lingo comments are preceded by double hyphens ( multiple lines must be preceded by double hyphens.

-- This is a single-line Lingo comment

--). Each line of a comment that covers

-- This is a

-- multiple-line Lingo comment

JavaScript syntax comments on a single line are preceded by a double-slash (//). Comments that cover multiple lines are preceded with a

// This is a single-line JavaScript syntax comment

/* This is a multiple-line JavaScript syntax comment */

You can place a comment on its own line or after any statement. Any text following the comment markers on the same line are ignored.

Comments can consist of anything you want, such as notes about a particular script or handler or notes about a statement whose purpose might not be obvious. Comments make it easier for you or someone else to understand a procedure after you’ve been away from it for a while.

Adding large numbers of comments does not increase the size of your movie file when it is saved as a compressed DCR or DXR file. Comments are removed from the file during the compression process.

Comment markers can also be used to ignore sections of code you want to deactivate for testing or debugging purposes. By adding comment markers rather than removing the code, you can temporarily turn it into comments. Select the code you want to turn on or off, and then use the Comment or Uncomment buttons in the Script window to quickly add or remove comment markers.

12 Chapter 2: Director Scripting Essentials

/* and followed by a */.

• Parentheses are required after all method and function names. For example, when calling the

Sound object’s Otherwise, a script error will occur.

// JavaScript syntax _sound.beep(); // this statement will work properly _sound.beep; // this statement will result in a script error

When you call a method, function, or handler from within another method, function, or handler, you must include parentheses in the calling statement. In the following example, the

modifySprite() method contains a call to a spriteClicked handler. The call to the spriteClicked handler must include parentheses; otherwise, a script error occurs.

// JavaScript syntax function modifySprite() {

spriteClicked(); // this call to the handler will work properly

spriteClicked; // this call to the handler results in a script error } function spriteClicked() {

// handler code here }

You can also use parentheses to override the order of precedence in math operations, or to make your statements easier to read. For example, the first math expression below yields a result of 13, while the second expression yields a result of 5:

5 * 3 - 2 -- yields 13 5 * (3 - 2) -- yields 5

beep() method, you must include the parentheses after the word beep.

• Event handler syntax varies between Lingo and JavaScript syntax. In Lingo, handlers use the

syntax

on handlerName. In JavaScript syntax, handlers are implemented as functions, and use

the syntax

function handlerName(). For example, the following statements comprise a

handler that plays a beep when the mouse button is clicked:

-- Lingo syntax on mouseDown

_sound.beep() end // JavaScript syntax function mouseDown() {

_sound.beep(); }

• Event handler parameter syntax can vary between Lingo and JavaScript syntax. Both Lingo and

JavaScript syntax support enclosing parameters passed to a handler within parentheses. If more than one parameter is passed, each parameter is separated by a comma. In Lingo, you can also pass parameters that are not enclosed by parentheses. For example, the following handler receives the two parameters

-- Lingo syntax on addThem a, b -- without parentheses

c = a + b end

a and b.

addThem

on addThem(a, b) -- with parentheses

c = a + b end

// JavaScript syntax function addThem(a, b) {

c = a + b; }

Scripting syntax 13

• The const keyword can be used in JavaScript syntax to specify a constant whose value does not

change. Lingo has its own predefined set of constants ( keyword

const does not apply to Lingo.

For example, the following statement specifies a constant named to 12. This value will always be 12, and cannot be changed through script.

// JavaScript syntax const intAuthors = 12;

TAB, EMPTY, and so on); therefore, the

intAuthors and sets its value

• The var keyword in JavaScript syntax can be placed in front of a term to specify that the term

is a variable. The following statement creates a variable named

// JavaScript syntax var startValue = 0;

Note: Although using var in JavaScript syntax is optional, it is recommended that you always declare local JavaScript syntax variables, or those inside a function, using var. For more information on using variables, see “Variables” on page 21.

startValue.

• The line continuation symbol (\) in Lingo indicates that a long line of sample code has been

broken into two or more lines. Lines of Lingo that are broken in this way are not separate lines of code. For example, the following code would still run.

-- Lingo syntax tTexture = member("3D").model("box") \

.shader.texture

JavaScript syntax does not include a line continuation symbol. To break multiple lines of JavaScript syntax code, add a carriage return at the end of a line, and then continue the code on the following line.

• Semicolons can be used to specify the end of a statement of JavaScript syntax code. Semicolons

do not apply to Lingo. Using a semicolon is optional. If used, it is placed at the end of a complete statement. For

example, both of the following statements create a variable named

// JavaScript syntax var startValue = 0 var startValue = 0;

startValue.

A semicolon does not necessarily specify the end of a line of JavaScript syntax code, and multiple statements can be placed on one line. However, placing separate statements on separate lines is recommended in order to improve readability. For example, the following three statements occupy only one line of code and function properly, but it is difficult to read the code.

// JavaScript syntax _movie.go("Author"); var startValue = 0; _sound.beep();

• Character spaces within expressions and statements are ignored in both Lingo and JavaScript

syntax. In strings of characters surrounded by quotation marks, spaces are treated as characters. If you want spaces in a string, you must insert them explicitly. For example, the first statement below ignores the spaces between the list items, and the second statement includes the spaces.

-- Lingo syntax myList1 = ["1", "2", "3"] -- yields ["1", "2", "3"] myList2 = [" 1 ", " 2 ", " 3 "] -- yields [" 1 ", " 2 ", " 3 "]

14 Chapter 2: Director Scripting Essentials

• Case-sensitivity can vary between Lingo and JavaScript syntax.

Lingo is not case-sensitive in any circumstance—you can use uppercase and lowercase letters however you want. For example, the following four statements are equivalent:

-- Lingo syntax member("Cat").hilite = true member("cat").hiLite = True MEMBER("CAT").HILITE = TRUE Member("Cat").Hilite = true

Although Lingo is not case-sensitive, it’s a good habit to choose a case convention and use it consistently throughout your scripts. This makes it is easier to identify names of handlers, variables, cast members, and so on.

JavaScript syntax is case-sensitive when referring to objects, the top level properties or methods that refer to objects, or when referring to user-defined variables. For example, the top level

sprite() method returns a reference to a specific Sprite object, and is implemented in

Director with all lowercase letters. The first statement below refers to the name of the first sprite in a movie, while the second and third statements result in a script error.

// JavaScript syntax sprite(1).name // This statement functions normally Sprite(1).name // This statement results in a script error SPRITE(1).name // This statement results in a script error

Literal strings are always case-sensitive in both Lingo and JavaScript syntax. For more information on using strings, see “Strings” on page 18.

Data types

A data type is a set of data with values that have similar, predefined characteristics. Every variable and property value in Director is of a specific data type, and values returned by methods are of a specific data type.

For example, consider the following two statements. In the first statement, variable assigned a whole number value of 14, which is an integer. So, the data type of variable integer. In the second statement, variable which is a string. So, the data type of variable

-- Lingo syntax intX = 14 stringX = "News Headlines"

stringX is assigned a sequence of character values,

stringX is string.

intX is

// JavaScript syntax var intX = 14; var stringX = "News Headlines";

The values that are returned by methods or functions are also of an inherent data type. For example, the Player object’s

windowPresent() method returns a value that specifies whether a

window is present. The returned value is TRUE (1) or FALSE (0).

Data types 15

Some data types are shared between Lingo and JavaScript syntax, and some data types are specific to one language or another. The set of data types that Director supports is fixed and cannot be modified, meaning that new data types cannot be added and existing data types cannot be removed. Director supports the following data types.

Data type Description

# (symbol) A self-contained unit that can be used to represent a condition or flag. For example,

Array (JavaScript syntax only) Although not literally a data type, an Array object can be

Boolean A value that is

Color Represents an object’s color.

Constant A piece of data whose value does not change.

Date Although not literally a data type, in JavaScript syntax a Date object can be used to

Float (Lingo only) A floating-point number. For example, 2.345 or 45.43.

Function (JavaScript syntax only) Although not literally a data type, a Function object can be

Integer (Lingo only) A whole number. For example, 5 or 298.

List A linear or property list made up of values or property names and values,

Math (JavaScript syntax only) Although not literally a data type, a Math object can be

null (JavaScript syntax only) Denotes a variable whose value behaves as 0 in numeric

Number (JavaScript syntax only) Although not literally a data type, a Number object can be

Object Although not literally a data type, an Object object can be used to create a custom

Point A point on the Stage that has both a horizontal and vertical coordinate.

Rect A rectangle on the Stage.

RegExp (JavaScript only) A regular expression pattern that is used to match character

String A contiguous sequence of keyboard symbols or character values. For example,

#list or #word.

used to work with linear lists of values. The functionality of an Array object is similar to that of the List data type in Lingo.

TRUE (1) or FALSE (0). In Lingo, all TRUE or FALSE values are simple

integer constants, 1 for values are by default the actual Boolean simple integer constants automatically when required in Director.

In Lingo, syntax,

work with dates. In Lingo, use the date() method to create a Date object and work with dates.

used to specify a string of code to run.

respectively.

used to perform mathematical functions.

contexts and as

used to represent numerical constants, such as a maximum value, not-a-number (NaN), and infinity.

named container that contains data and methods that act on that data.

combinations in strings.

"Director" or "$5.00".

TRUE and FALSE can be either lowercase or uppercase. In JavaScript

true and false must always be lowercase.

TRUE, 0 for FALSE. In JavaScript syntax, all true or false

true or false values, but are converted to

FALSE in Boolean contexts.

16 Chapter 2: Director Scripting Essentials

Data type Description

undefined (JavaScript syntax only) Denotes a variable that does not have a value.

Vector A point in 3D space.

VOID (Lingo only) Denotes an empty value.

Note: Many of the data types and objects that are specific to JavaScript syntax contain their own set of methods and properties that can be used to further manipulate those types. While the Director Scripting Reference may refer to some of these methods and properties, it does not include complete reference information about them. For more detailed information on these data types and objects, and their methods and properties, see one of the many third-party resources on the subject.

The built-in properties in Director, such as the Cast object’s name property, can only be assigned values that are the same data type as that of the property’s inherent data type. For example, the Cast object’s

News Headlines. If you try to assign a value of a different data type to this property, such as the

name property’s inherent data type is a string, so the value must be a string such as

integer 20, a script error occurs.

If you create your own custom properties, their values can be of any data type, regardless of the data type of the initial value.

Both Lingo and JavaScript syntax are dynamically typed. This means that you do not have to specify the data type of a variable when you declare it, and data types are automatically converted as needed while a script runs.

For example, the following JavaScript syntax initially sets the variable later in the script it is set to a string. When the script runs, the date type of

myMovie to an integer, and

myMovie is converted

automatically.

-- Lingo syntax myMovie = 15 -- myMovie is initially set to an integer ... myMovie = "Animations" -- myMovie is later set to a string

// JavaScript syntax var myMovie = 15; // myMovie is initially set to an integer ... myMovie = "Animations"; // myMovie is later set to a string

Data types 17

Literal values

A literal value is any part of a statement or expression that is to be used exactly as it is, rather than as a variable or a script element. Literal values that you encounter in script are character strings, integers, decimal numbers, cast member names and numbers, frame and movie names and numbers, symbols, and constants.

Each type of literal value has its own rules.

Strings

Strings are words or groups of characters that script treats as regular words instead of as variables. Strings must be enclosed in double quotation marks. For example, you might use strings to give messages to the user of your movie or to name cast members. In the following statement, and Greeting are both strings. Hello is the literal text being put into the text cast member;

Greeting is the name of the cast member.

-- Lingo syntax member("Greeting").text = "Hello"

Similarly, if you test a string, double quotation marks must surround each string, as in the following example:

-- Lingo syntax if "Hello Mr. Jones" contains "Hello" then soundHandler

Both Lingo and JavaScript syntax treat spaces at the beginning or end of a string as a literal part of the string. The following expression includes a space after the word to:

// JavaScript syntax trace("My thoughts amount to ");

Although Lingo does not distinguish between uppercase and lowercase when referring to cast members, variables, and so on, literal strings are case-sensitive. For example, the following two statements place different text into the specified cast member, because literal strings.

-- Lingo syntax member("Greeting").text = "Hello" member("Greeting").text = "HELLO"

In Lingo, the string() function can convert a numerical value into a string. In JavaScript syntax, the

toString() method can convert a numerical value into a string.

Note: Attempting to use the toString() method in JavaScript syntax on a null or undefined value results in a script error. This is in contrast with Lingo, in which the values, including those that are

VOID.

Hello and HELLO are

string() function works on all

Hello

Numbers

In Lingo, there are two types of numbers: integers and decimals.

An integer is a whole number, without any fractions or decimal places, in the range of

-2,147,483,648 and +2,147,483,647. Enter integers without using commas. Use a minus ( for negative numbers.

18 Chapter 2: Director Scripting Essentials

-) sign

A decimal number, also called a floating-point number, or float, is any number that includes a decimal point. In Lingo, the

floatPrecision property controls the number of decimal places

used to display these numbers. Director always uses the complete number, up to 15 significant digits, in calculations; Director rounds any number with more than 15 significant digits in calculations.

JavaScript syntax does not distinguish between integers and floating-point numbers, and merely uses numbers. For example, the following statements illustrate that the number 1 is an integer in Lingo and a number in JavaScript syntax, and that the decimal number 1.05 is a float in Lingo and a number in JavaScript syntax:

-- Lingo syntax put(ilk(1)) -- #integer put(ilk(1.05)) -- #float

// JavaScript syntax trace(typeof(1)) // number trace(typeof(1.05)) // number

In Lingo, you can convert a decimal to an integer by using the integer() function. You can also convert an integer to a decimal by performing a mathematical operation on the integer, for example, by multiplying an integer by a decimal. In JavaScript syntax, you can convert a string or a decimal number to a whole number by using the

integer() function, parseInt() rounds down. For example, the following statement rounds

parseInt() function. As opposed to Lingo’s

off the decimal number 3.9 and converts it to the integer 4 (Lingo) and the number 3 (JavaScript syntax).

-- Lingo syntax theNumber = integer(3.9) -- results in a value of 4

// JavaScript syntax var theNumber = parseInt(3.9); // results in a value of 3

In Lingo, the value() function can convert a string into a numerical value.

You can also use exponential notation with decimal numbers: for example, -

123.4e+9.

In Lingo, you can convert an integer or string to a decimal number by using the

1.1234e-100 or

float()

function. In JavaScript syntax, you can convert a string to a decimal number by using the

parseFloat() function. For example, the following statement stores the value 3.0000 (Lingo)

and 3 (JavaScript syntax) in the variable

-- Lingo syntax theNumber = float(3) -- results in a value of 3.0000

theNumber.

// JavaScript syntax var theNumber = parseFloat(3) // results in a value of 3

Literal values 19

Constants

A constant is a named value whose content never changes.

In Lingo, the predefined terms are always the same. The predefined terms

TRUE, FALSE, VOID, and EMPTY are constants because their values

BACKSPACE, ENTER, QUOTE, RETURN, SPACE, and TAB

are constants that refer to keyboard characters. For example, to test whether the last key pressed was the Space bar, use the following statement:

-- Lingo syntax if _key.keyPressed() = SPACE then beep()

In JavaScript syntax, you can access predefined constants using some of the data types that are unique to JavaScript syntax. For example, the Number object contains constants such as

Number.MAX_VALUE and Number.NaN, the Math object contains constants such as Math.PI and Math.E, and so on.

Note: This reference does not provide in-depth information about the predefined constants in JavaScript syntax. For more information on these constants, see one of the many third-party resources on the subject.

In JavaScript syntax, you can also define your own custom constants by using the const keyword. For example, the following statement creates a constant named

items, and assigns it a value of 20.

This value cannot be changed after it has been created.

// JavaScript syntax const items = 20;

For more information on constants, see Chapter 9, “Constants,” on page 151.

Symbols

A symbol is a string or other value in Lingo that begins with the pound (

#) sign.

Symbols are user-defined constants. Comparisons using symbols can usually be performed very quickly, providing more efficient code.

For example, the first statement below runs more quickly than the second statement:

-- Lingo syntax userLevel = #novice userLevel = "novice"

Symbols cannot contain spaces or punctuation.

In both Lingo and JavaScript syntax, convert a string to a symbol by using the

-- Lingo syntax x = symbol("novice") -- results in #novice

symbol() method.

// JavaScript syntax var x = symbol("novice"); // results in #novice

Convert a symbol back to a string by using the string() function (Lingo) or the toString() method (JavaScript syntax).

-- Lingo syntax x = string(#novice) -- results in "novice"

// JavaScript syntax var x = symbol("novice").toString(); // results in "novice"

20 Chapter 2: Director Scripting Essentials

In JavaScript syntax, you cannot compare symbols of the same name to determine whether they refer to the same symbol. To compare symbols of the same name, you must first convert them to strings by using the

toString() method, and then perform the comparison.

Variables

Director uses variables to store and update values. As the name implies, a variable contains a value that can be changed or updated as a movie plays. By changing the value of a variable as the movie plays, you can do things such as store a URL, track the number of times a user takes part in an online chat session, record whether a network operation is complete, and many more options.

It is a good idea always to assign a variable a known value the first time you declare the variable. This is known as initializing a variable. Initializing variables makes it easier to track and compare the variable’s value as the movie plays.

Variables can be global or local. A local variable exists only as long as the handler in which it is defined is running. A global variable can exist and retain its value as long as Director is running, including when a movie branches to another movie. A variable can be global within an individual handler, a specific script, or an entire movie; the scope depends on how the global variable is initialized.

If you want a variable to be available throughout a movie, it is good practice to declare it in an

prepareMovie

ensures that the variable is available from the very start of the movie.

For more information on using both global and local variables, see “Using global variables”

on page 22 and “Using local variables” on page 24.

Storing and updating values in variables

Variables can hold data for any of the data types found in Director, such as integers, strings, or

FALSE values, symbols, lists, or the result of a calculation. Use the equals (=) operator to store

the values of properties and variables.

As mentioned in the Data types section of this reference, variables in both Lingo and JavaScript syntax are dynamically typed, which means that they can contain different types of data at different times. (The ability to change a variable’s type distinguishes Lingo from other languages such as Java and C++, in which a variable’s type cannot be changed.)

For example, the statement assigned the variable an integer. If you subsequently use the statement becomes a string variable, because the variable now contains a string.

You can convert a string to a number by using the method (JavaScript syntax), or a number to a string by using the string() function (Lingo) or the

toString() method (JavaScript syntax).

The values of some properties can be both set (the value is assigned) and returned (the value is retrieved), and some property values can only be returned. Properties whose values can be both set and returned are called read/write, and those that can only be returned are called read-only.

Often these are properties that describe some condition that exists outside the control of Director. For example, you cannot set the of channels within a movie that contains Macromedia Shockwave content. However, you can return the number of channels by referring to the

(Lingo) or a function prepareMovie() (JavaScript syntax) handler. This

x = 1 creates the variable x, which is an integer variable because you

x = "one", the variable x

value() function (Lingo) or the parseInt()

numChannels cast member property, which indicates the number

numChannels property of a cast member.

TRUE

Variables 21

To assign a value to a variable:

• Use the equals (=) operator.

For example, the following statement assigns a URL to the variable

// JavaScript syntax var placesToGo = "http://www.macromedia.com";

Variables can also hold the results of mathematical operations. For example, the following statement adds the result of an addition operation to the variable

-- Lingo syntax mySum = 5 + 5 -- this sets mySum equal to 10

As another example, the following statement returns the cast member assigned to sprite 2 by retrieving the value of the sprite’s

-- Lingo syntax textMember = sprite(2).member

member property and places it into the variable textMember.

It is good practice to use variable names that indicate what the variable is used for. This makes your scripts easier to read. For example, the variable

mySum indicates that the variable contains a

sum of numbers.

To test the values of properties or variables:

placesToGo:

mySum:

• Use the put() or the trace() functions in the Message window or check the values in the

Watch er wi ndow ; ( both Lingo and JavaScript syntax).

For example, the following statement displays the value assigned to the variable Message window.

-- Lingo syntax myNumber = 20 * 7 put(myNumber) -- displays 140 in the Message window

put() and trace() provide identical functionality and are available to

myNumber in the

// JavaScript syntax var myNumber = 20 * 7; trace(myNumber) // displays 140 in the Message window

Using global variables

Global variables can be shared among handlers, scripts, or movies. A global variable exists and retains its value as long as Director is running or until you call the

clearGlobals() method.

In Macromedia Shockwave Player, global variables persist among movies displayed by the

goToNetMovie() method, but not among those displayed by the goToNetPage() method.

Every handler that declares a variable as global can use the variable’s current value. If the handler changes the variable’s value, the new value is available to every other handler that treats the variable as global.

It is good practice to start the names of all global variables with a lowercase g. This helps identify which variables are global when you examine your code.

Director provides a way to display all current global variables and their current values and to clear the values of all global variables.

22 Chapter 2: Director Scripting Essentials

To display all current global variables and their current values:

• Use the Global object’s showGlobals() method in the Message window.

For more information on the Message window, see “Debugging in the Message window”

on page 87.

To clear all current global variables:

• Use the Global object’s clearGlobals() method in the Message window to set the value of all

global variables to

To monitor the values of global variables during movie playback, use the Object inspector. For more information on the Object inspector, see “Debugging in the Object inspector” on page 91.

Global variables in Lingo

In Lingo, variables are considered local by default, and you do not need to precede the variable name with any keyword. To declare a global variable, you must precede the variable with the keyword

global.

If you declare a global variable at the top of a script and before any handlers, the variable is available to all handlers in that specific script. If you declare a global variable within a handler, the variable is available only to that handler; however, if you declare a global variable with the same name within two separate handlers, an update to the variable’s value in one handler will also be reflected in the variable in the other handler.

The following example illustrates working with two global variables: to all handlers in the script, and other handlers that declare it on the first line of the handler.

-- Lingo syntax global gScript -- gScript is available to all handlers

VOID (Lingo) or undefined (JavaScript syntax).

gScript, which is available

gHandler, which is available within its defining handler and any

on mouseDown

global gHandler gScript = 25 gHandler = 30

end

on mouseUp

global gHandler trace(gHandler) -- displays 30

end

In Lingo, when you use the term global to define global variables, the variables automatically have

VOID as their initial value.

Global variables in JavaScript syntax

In JavaScript syntax, variables are considered global by default. The scope of a global variable can be determined by how and where it is declared.

• If you declare a variable within a JavaScript syntax function without preceding the variable

name with the keyword script.

var, the variable is available to all functions within its containing

• If you declare a variable outside a JavaScript syntax function, with or without the keyword var,

the variable is available to all functions within its containing script.

Variables 23

• If you declare a variable inside or outside a JavaScript syntax function by using the syntax

_global.varName, the variable is available to all scripts within a movie.

The following example uses the syntax

gMovie as global. This variable is available to all scripts within the movie.

// JavaScript syntax _global.gMovie = 1; // Declare gMovie in one script

// Create a function in a separate script that operates on gMovie function mouseDown() {

_global.gMovie++; return(_global.gMovie);

}

The following example declares the global variable gScript in one script. This variable is available only to functions within that script.

// JavaScript syntax var gScript = 1; // Declare gScript in a script

// gScript is available only to functions in the script that defines it function mouseDown() {

gScript++; return(gScript);

}

In JavaScript syntax, when you define variables before any handlers, the variables automatically have

undefined as their initial value.

Using local variables

A local variable exists only as long as the handler in which it is defined is running. However, after a local variable is created, you can use the variable in other expressions or change its value while a script is still within the handler that defined the variable.

Treating variables as local is a good idea when you want to use a variable only temporarily in one handler. This helps you avoid unintentionally changing the value in another handler that uses the same variable name.

_global.gMovie in one script to declare the variable

To create a local variable:

• In Lingo, assign the variable a value using the equals (=) operator.

• In JavaScript syntax, inside a function precede the variable name with the keyword var, and

then assign the variable a value using the equals operator.

Note: Because JavaScript syntax variables are global by default, if you attempt to declare a local variable inside a function without using the keyword behavior. Therefore, although using local JavaScript syntax variables using

To display all current local variables in the handler:

var is optional, it is strongly recommended that you declare all

var to avoid any unexpected behavior.

var, your script could produce unexpected

• In Lingo only, use the showLocals() function.

In Lingo, you can use this method in the Message window or in handlers to help with debugging. The result appears in the Message window. The JavaScript syntax.

To monitor the values of local variables during movie playback, use the Object inspector. For more information on the Object inspector, see “Debugging in the Object inspector” on page 91.

24 Chapter 2: Director Scripting Essentials

showLocals() method does not apply to

Operators

Operators are elements that tell Lingo and JavaScript syntax scripts how to combine, compare, or modify the values of an expression. Many of the operators in Director are shared between Lingo and JavaScript syntax, and some are unique to each language.

Some types of operators include the following:

• Arithmetic operators (such as +, -, /, and *)

• Comparison operators (such as <, >, and >=), which compare two arguments

• Logical operators (not, and, or), which combine simple conditions into compound ones

• String operators (such as &, &&, and +), which join, or concatenate, strings of characters

Note: There are many more types of operators in JavaScript syntax than there are in Lingo, and not all of them are covered in this reference. For more information on additional operators in JavaScript 1.5, see one of the many third-party resources on the subject.

The items that operators act upon are called operands. In Lingo, there are only binary operators. In JavaScript syntax, there are both binary and unary operators. A binary operator requires two operands, one before the operator and one after the operator. A unary operator requires a single operand, either before or after the operator.

In the following example, the first statement illustrates a binary operator, where the variables and

y are operands and the plus (+) sign is the operator. The second statement illustrates a unary

operator, where the variable

// JavaScript syntax x + y; // binary operator i++; // unary operator

For reference information on operators, see Chapter 13, “Operators,” on page 595.

i is the operand and ++ is the operator.

Understanding operator precedence

When two or more operators are used in the same statement, some operators take precedence over others in a precise hierarchy to determine which operators to execute first. This is called the operators’ precedence order. For example, multiplication is always performed before addition. However, items in parentheses take precedence over multiplication. In the following example, without parentheses the multiplication in this statement occurs first:

-- Lingo syntax total = 2 + 4 * 3 -- results in a value of 14

When parentheses surround the addition operation, addition occurs first:

-- Lingo syntax total = (2 + 4) * 3 -- results in a value of 18

Descriptions of the types of operators and their precedence order follow. Operators with higher precedence are performed first. For example, an operator whose precedence order is 5 is performed before an operator whose precedence order is 4. Operations that have the same order of precedence are performed left to right.

Operators 25

Arithmetic operators

Arithmetic operators add, subtract, multiply, divide, and perform other arithmetic operations. Parentheses and the minus sign are also arithmetic operators.

Operator Effect Precedence

( )

mod

Note: In Lingo, when only integers are used in an operation, the result is an integer. Using integers and floating-point numbers in the same calculation results in a floating-point number. In JavaScript syntax, all calculations essentially result in floating-point numbers.

Groups operations to control precedence order. 5

When placed before a number, reverses the sign of a number. 5

Performs multiplication. 4

(Lingo only) Performs modulo operation. 4

Performs division. 4

(JavaScript syntax only) Returns the integer remainder of dividing two operands.

(JavaScript syntax only) Adds one to its operand. If used as a prefix operator ( as a postfix operator ( adding one.

(JavaScript syntax only) Subtracts one from its operand. The return value is analogous to that of the increment operator.

When placed between two numbers, performs addition. 3

When placed between two numbers, performs subtraction. 3

++x), returns the value of its operand after adding one. If used

x++), returns the value of its operand before

When dividing one integer by another does not result in a whole number, Lingo rounds the result down to the nearest integer. For example, the result of

4/3 is 1. In JavaScript syntax, the actual

floating-point value, 1.333, is returned.

To force Lingo to calculate a value without rounding the result, use values in an expression. For example, the result of

4/float(3) is 1.333.

float() on one or more

Comparison operators

Comparison operators compare two values and determine whether the comparison is true or false.

Operator Meaning Precedence

===

26 Chapter 2: Director Scripting Essentials

(JavaScript syntax only) Two operands are equal. If the operands are not of the same data type, JavaScript syntax attempts to convert the operands to an appropriate data type for the comparison.

(JavaScript syntax only) Two operands are equal and of the same data type

(JavaScript syntax only) Two operands are not equal. If the operands are not of the same data type, JavaScript syntax attempts to convert the operands to an appropriate data type for the comparison.

Operator Meaning Precedence

!==

(JavaScript syntax only) Two operands are not equal and/or not of the same type

(Lingo only) Two operands are not equal 1

The left operand is less than the right operand 1

The left operand is less than or equal to the right operand 1

The left operand is greater than the right operand 1

The left operand is great than or equal to the right operand 1

(Lingo only) Two operands are equal 1

Assignment operators

Assignment operators assign a value to its left operand based on the value of its right operand. With the exception of the basic assignment operator, equal (

=), all of the following shortcut

assignment operators apply only to JavaScript syntax.

Operator Meaning Precedence

= Equal 1

x += y (JavaScript syntax only) x = x + y 1

x -= y (JavaScript syntax only) x = x - y 1

x *= y (JavaScript syntax only) x = x * y 1

x /= y (JavaScript syntax only) x = x / y 1

x %= y (JavaScript syntax only) x = x % y 1

Logical operators

Logical operators test whether two logical expressions are true or false.

Use care when using logical operators and string operators in Lingo and JavaScript syntax. For example, in JavaScript syntax true, but in Lingo,

&& is a string operator that concatenates two strings and inserts a space

&& is a logical operator that determines whether two expressions are

between the two expressions.

Operator Effect Precedence

and

not

(Lingo only) Determines whether both expressions are true 4

(JavaScript syntax only) Determines whether both expressions are true 4

(Lingo only) Determines whether either or both expressions are true 4

(JavaScript syntax only) Determines whether either or both expressions are true

(Lingo only) Negates an expression 5

(JavaScript syntax only) Negates an expression 5

Operators 27

The not (Lingo) or ! (JavaScript syntax) operator is useful for toggling a TRUE or FALSE value to its opposite. For example, the following statement turns on the sound if it’s currently off and turns off the sound if it’s currently on:

-- Lingo syntax _sound.soundEnabled = not (_sound.soundEnabled)

// JavaScript syntax _sound.soundEnabled = !(_sound.soundEnabled);

String operators

String operators combine and define strings.

Use care when using logical operators and string operators in Lingo and JavaScript syntax. For example, in JavaScript syntax true, but in Lingo,

&& is a string operator that concatenates two strings and inserts a space

&& is a logical operator that determines whether two expressions are

between the two expressions.

Operator Effect Precedence

& (Lingo only) Concatenates two strings 2

+ (JavaScript syntax only) Concatenates two string values and returns a

third string that is the union of the two operands

+= (JavaScript syntax only) Concatenates one string variable and one

string value, and assigns the returned value to the string variable

&& (Lingo only) Concatenates two strings and inserts a space between

the two

" Marks the beginning or end of a string. 1

Conditional constructs

By default, Director always executes script statements starting with the first statement and continuing in order until it reaches the final statement or a statement that instructs a script to go somewhere else.

The order in which statements are executed affects the order in which you should place statements. For example, if you write a statement that requires some calculated value, you need to put the statement that calculates the value first.

The first statement in the following example adds two numbers, and the second statement assigns a string representation of the sum to a field cast member named Stage. The second statement could not be placed before the first statement because the variable has not yet been defined.

-- Lingo syntax x = 2 + 2 member("Answer").text = string(x)

// JavaScript syntax var x = 2 + 2; member("Answer").text = x.toString();

28 Chapter 2: Director Scripting Essentials

Answer, which appears on the

Both Lingo and JavaScript syntax provide conventions for altering the default execution order or script statements, and for performing actions depending on specific conditions. For example, you may want to do the following in your scripts:

• Execute a set of statements if a logical condition is true, or execute alternate statements if the

logical condition is false.

• Evaluate an expression and attempt to match the expression’s value to a specific condition.

• Execute a set of statements repeatedly until a specific condition is met.

Testing for logical conditions

To execute a statement or set of statements if a specified condition is true or false, you use the

if...then...else (Lingo) or if...else (JavaScript syntax) structures. For example, you can

create an

if...then...else or if...then structure that tests whether text has finished

downloading from the Internet and, if it has, then attempts to format the text. These structures use the following pattern to test for logical conditions:

• In both Lingo and JavaScript syntax, statements that check whether a condition is true or false

begin with the term

if.

• In Lingo, if the condition exists, the statements following the term then are executed. In

JavaScript syntax, curly brackets ( surround each individual

if, else, or else if statement.

{ }) take the place of the Lingo term then, and must

• In both Lingo and JavaScript syntax, if the condition does not exist, scripts skip to the next

statement in the handler using the term

else or else if.

• In Lingo, the term end if specifies the end of the if test. In JavaScript syntax, the if test ends

automatically, so there is no term that explicitly ends the test.

To optimize your script’s performance, test for the most likely conditions first.

The following statements test several conditions. The term perform if previous conditions are false:

-- Lingo syntax if _mouse.mouseMember = member(1) then

_movie.go("Cairo")

else if _mouse.mouseMember = member(2) then

_movie.go("Nairobi")

else

_player.alert("You’re lost.")

end if

else if specifies alternative tests to

// JavaScript syntax if (_mouse.mouseMember = member(1)) {

_movie.go("Cairo");

} else if (_mouse.mouseMember = member(2)) {

_movie.go("Nairobi");

} else {

_player.alert("You’re lost.");

}

Conditional constructs 29

When writing if...then structures in Lingo, you can place the statement or statements following carriage return after

then in the same line as then, or you can place them on their own line by inserting a

then. If you insert a carriage return, you must also include an end if

statement at the end of the if...then structure.

When writing following carriage return after

if structures in JavaScript syntax, you can place the statement or statements

if in the same line as if, or you can place them on their own line by inserting a

if.

For example, the following statements are equivalent:

-- Lingo syntax if _mouse.mouseMember = member(1) then _movie.go("Cairo")

if _mouse.mouseMember = member(1) then

_movie.go("Cairo")

end if

// JavaScript syntax if (_mouse.mouseMember = member(1)) { _movie.go("Cairo"); }

if (_mouse.mouseMember = member(1)) {

_movie.go("Cairo");

}

For reference information on using the if...then...else and if...else structures, see “if”

on page 209.

Evaluating and matching expressions

case (Lingo) or switch...case (JavaScript syntax) structures are shorthand alternatives to

The using

if...then...else or if...then structures when setting up multiple branching

structures. The than many

In Lingo, the condition to test for follows the term

case and switch...case structures are often more efficient and easier to read

if...then...else or if...then structures.

case in the first line of the case structure.

The comparison goes through each line in order until Lingo encounters an expression that matches the test condition. When a matching expression is found, Director executes the Lingo that follows the matching expression.

In JavaScript syntax, the condition to test for follows the term structure. Each comparison in the test follows the term Each

case comparison can be ended by using the optional term break. Including the term break

breaks the program out of the

switch structure and executes any statements following the

switch in the first line of the

case for each line that contains a test.

structure. If break is omitted, the following case comparison is executed.

case or switch...case structure can use comparisons as the test condition.

For example, the following case and switch...case structures test which key the user pressed most recently and responds accordingly.

• If the user pressed A, the movie goes to the frame labeled Apple.

• If the user pressed B or C, the movie performs the specified transition and then goes to the

frame labeled Oranges.

30 Chapter 2: Director Scripting Essentials

+ 1100 hidden pages

Macromedia MX 2004 User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

Introduction

Intended audience

What’s new with Director scripting

Dot syntax scripting format

JavaScript syntax compatibility

New ways to access the scripting APIs

What’s new in this documentation

Finding information about scripting in Director

Director Scripting Essentials

Types of scripts

Scripting terminology

Scripting syntax

Data types

Literal values

Strings

Numbers

Constants

Symbols

Variables

Storing and updating values in variables

Using global variables

Global variables in Lingo

Global variables in JavaScript syntax

Using local variables

Operators

Understanding operator precedence

Arithmetic operators

Comparison operators

Assignment operators

Logical operators

String operators

Conditional constructs

Testing for logical conditions

Evaluating and matching expressions