Lingo Dictionary

Macromedia Director MX

Trademarks
Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware,
Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage
Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Contribute, Design in Motion, Director, Director Multimedia
Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash,
Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developers Studio, Generator Dynamic Graphics Server,
Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects, Macromedia, Macromedia M Logo & Design,
Macromedia Contribute, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker, Object
Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave, Shockmachine, Shockwave, Shockwave
Remote, Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and
Xtra are 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, servicemarks, or
tradenames of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.
This guide contains links to third-party Web sites 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 Web site 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 2002 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.
Third Party Software Notices and/or Additional Terms and Conditions can be found at http://www.macromedia.com/go/thirdparty/.
Part Number ZDR90M200
Acknowledgments
Writing: Jay Armstrong, George Brown, Stephanie Gowin, and, Tim Statler
Editing: Rosana Francescato, Mary Ferguson, Mary Kraemer, and Noreen Maher
Project Management: Stuart Manning
Production: Chris Basmajian, Caroline Branch, John Francis, and Patrice ONeill
Multimedia: Aaron Begley and Benjamin Salles
First Edition: December 2002
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

CHAPTER 1
Lingo by Feature

This chapter lists various Macromedia Director MX features and the corresponding Lingo
elements that you can use to implement those features.

Accessibility
These terms are useful for making movies accessible to the disabled:
Text-to-speech
voiceCount()

voiceSet()

voiceGet()

voiceSetPitch()

voiceGetPitch()

voiceSetRate()

voiceGetRate()

voiceSetVolume()

voiceGetVolume()

voiceSpeak()

voiceInitialize()

voiceState()

voicePause()

voiceStop()

voiceResume()

voiceWordPos()

Keyboard navigation
autoTab

selection (cast property)

hilite (command)

selectedText

keyboardFocusSprite

selEnd

selection (text cast member property)

selStart

selection() (function)

Animated GIFs
These terms are useful for working with animated GIFs:
directToStage

pause (movie playback)

frameRate

playBackMode

linked

resume sprite

moviePath

rewind sprite

Animation
These terms are useful for creating animation with Lingo:
blend

locV

ink

member (sprite property)

loc

regPoint

locH

tweened

Behaviors
The terms in this section are useful for authoring behaviors and using behaviors while the
movie plays.
Authoring behaviors
Use these terms to set up behaviors and the behaviors Parameters dialog box:
ancestor

on getBehaviorDescription

on runPropertyDialog

on getPropertyDescriptionList

on getBehaviorTooltip

property

on isOKToAttach

Sending messages to behaviors

Use these commands to send messages to behaviors attached to sprites:
call

sendSprite

callAncestor

sendAllSprites

Identifying behaviors
Use these terms to identify the behaviors attached to sprites:

currentSpriteNum

scriptInstanceList

me

spriteNum

Chapter 1

Bitmaps
The terms in this section are useful for working with bitmaps.
Bitmap properties
Use these terms to check and set bitmap properties:
alphaThreshold

foreColor

backColor

palette

blend

picture (cast member property)

depth

pictureP()

dither

rect (member)

trimWhiteSpace (property)

imageCompression

imageQuality

movieImageCompression

movieImageQuality

Alpha channel
Use these terms to control alpha channel effects:
alphaThreshold

dither

depth

useAlpha

createMask()

createMatte()

extractAlpha()

setAlpha()

Image objects
Use these terms to create and control image objects:
copyPixels()

fill()

crop() (image object command)

image

draw()

image()

duplicate() (image function)

rect (image)

getPixel()

setPixel()

Buttons
See Buttons and check boxes in the Interface Elements section.

Lingo by Feature

Cast members
The terms in this section are useful for working with cast members.
Creating cast members
Use importFileInto and new() to create cast members.
Authoring
Use duplicate member, erase
during authoring.

member,

and pasteClipBoardInto to work with cast members

Graphic cast members

Use these terms to check and set the images assigned to graphic cast members:
center

palette

crop (cast member property)

picture (cast member property)

depth

pictureP()

media

regPoint

General cast member properties

Use these terms to check and set cast member properties:
fileName (cast member property)

number (cast member property)

media

preLoadMode

modified

type (cast member property)

name (cast member property)

URL

Graphic cast member dimensions

Use height, rect

(member),

and width to check and set dimensions for graphic cast members.

Casts
The terms in this section are useful for working with casts.
Loading casts
Use preLoadMode to check and set when Director preloads a cast.
Cast properties
Use these terms to specify cast properties:
castLib

number (cast property)

fileName (cast property)

number (system property)

name (cast property)

Chapter 1

Cast management
Use these terms to manage casts:
activeCastLib

number of members

duplicate member

pasteClipBoardInto

erase member

save castLib

findEmpty()

selection (cast property)

move member

Computer and operating system

Use these terms to check and control the computer:
beep

freeBlock()

beepOn

freeBytes()

cpuHogTicks

maxInteger

emulateMultiButtonMouse

multiSound

floatPrecision

romanLingo

Operating system control

Use restart and shutDown to control the operating system.

Data types
These terms are useful for specifying data types:
# (symbol)

string()

float()

stringP()

floatP()

symbol()

integer()

symbolP()

integerP()

VOID

objectP()

voidP()

Digital video
These terms are useful for working with AVI and QuickTime digital video:
controller

trackNextSampleTime

digitalVideoTimeScale

trackPreviousKeyTime

digitalVideoType

trackPreviousSampleTime

directToStage

trackStartTime (sprite property)

duration

trackStartTime (cast member property)

frameRate

trackStopTime (sprite property)

loop (cast member property)

trackStopTime (cast member property)

movieRate

trackText

Lingo by Feature

movieTime

trackType (cast member property)

pausedAtStart (Flash, digital video)

trackType (sprite property)

quickTimeVersion()

trackCount (cast member property)

timeScale

trackCount (sprite property)

trackEnabled

video (QuickTime, AVI)

trackNextKeyTime

videoForWindowsPresent

QuickTime
Use these terms to work with QuickTime:
enableHotSpot

nodeType

fieldOfView

nudge

getHotSpotRect()

pan (QTVR property)

hotSpotExitCallback

ptToHotSpotID()

hotSpotEnterCallback

quickTimeVersion()

invertMask

rotation

isVRMovie

scale

loopBounds

swing()

mask

staticQuality

motionQuality

tilt

mouseLevel

translation

node

triggerCallback

nodeEnterCallback

warpMode

nodeExitCallback

RealMedia video
Use these terms to with RealMedia video:
audio (RealMedia)

play

currentTime (RealMedia)

realPlayerNativeAudio()

displayRealLogo

realPlayerPromptToInstall()

duration (RealMedia)

realPlayerVersion()

image (RealMedia)

seek

lastError

soundChannel (RealMedia)

mediaStatus

state (RealMedia)

password

stop (RealMedia)

pause (RealMedia)

userName (RealMedia)

pausedAtStart (RealMedia)

video (RealMedia)

percentBuffered

Chapter 1

Events
Use these event handlers for Lingo that runs when a specific event occurs:
activeCastLib

on moveWindow

close window

on mouseWithin

on cuePassed

open window

on deactivateWindow

on prepareFrame

on enterFrame

on prepareMovie

on EvalScript

on resizeWindow

on exitFrame

on mouseUpOutside

on idle

on rightMouseDown (event handler)

on keyDown

on rightMouseUp (event handler)

on keyUp

on startMovie

on mouseDown (event handler)

on stepFrame

on mouseEnter

on streamStatus

on mouseLeave

on timeOut

on mouseUp (event handler)

on zoomWindow

on stopMovie

on beginSprite

on endSprite

on hyperlinkClicked

Use the pass and stopEvent commands to override the way that Director passes messages along
the message hierarchy.

External files
The terms in this section are useful for working with external files.
Path names and filenames
Use these terms to check and set path names and filenames:
@ (pathname)

getNthFileNameInFolder()

applicationPath

moviePath

fileName (cast property)

searchCurrentFolder

fileName (cast member property)

URL

Obtaining external media

Use these terms to obtain external media:
downloadNetThing

preloadNetThing()

importFileInto

Lingo by Feature

Managing external files

Use these terms to manage external files:
closeXlib

showXlib

open

sound playFile

openXlib

Flash
These terms are useful for working with Flash cast members:

10

actionsEnabled

originV

broadcastProps

pathName (movie property)

bufferSize

pausedAtStart (Flash, digital video)

buttonsEnabled

percentStreamed

bytesStreamed

play

callFrame()

playBackMode

centerRegPoint

playing

clearError

posterFrame

clickMode

print()

defaultRect

printAsBitmap()

defaultRectMode

quality

directToStage

rewind sprite

endTellTarget() See tellTarget()

rotation

eventPassMode

scale

findLabel()

scaleMode

fixedRate

on sendXML

flashRect

setCallback()

flashToStage()

settingsPanel()

frame() (function)

setFlashProperty()

frame (sprite property)

setVariable()

frameCount

showProps()

frameRate

sound

frameReady()

the soundMixMedia

getError()

sourceFileName

getFlashProperty()

stageToFlash()

getFrameLabel()

state (Flash, SWA)

getVariable()

static

goToFrame

stop (Flash)

Chapter 1

hitTest()

stream

hold

streamMode

imageEnabled

streamSize

linked

tellTarget()

loop (keyword)

URL

mouseOverButton

viewH

newObject()

viewPoint

obeyScoreRotation

viewScale

originH

viewV

originMode

volume (cast member property)

originPoint

These terms are useful for working with global Flash objects, which do not require a Flash
cast member:
clearAsObjects()

setCallback()

newObject()

Frames
The Lingo terms in this section let you work with frames.
Frame events
Use the on enterFrame, on exitFrame, and on
that runs at specific events within a frame.

prepareFrame event handlers to contain Lingo

Frame properties
Use these Lingo terms to check and set frame properties:
frameLabel

frameTempo

framePalette

frameTransition

frameScript

label()

frameSound1

labelList

frameSound2

marker()

markerList

Interface elements
The Lingo terms in this section are useful for working with interface elements.

Lingo by Feature

11

Menus
Use these terms to create menus:
enabled

name (menu item property)

installMenu

number (menu items)

menu

number (menus)

name (menu property)

script

Buttons and check boxes

Use these terms to specify buttons and check boxes:
alert

checkBoxType

buttonStyle

checkMark

buttonType

hilite (cast member property)

checkBoxAccess

Keys
The Lingo terms in this section are related to using the keyboard.
Identifying keys
Use these terms to identify keys:
charToNum()

keyPressed()

commandDown

mouseChar

controlDown

numToChar()

key()

optionDown

keyCode()

shiftDown

Keyboard interaction
Use keyPressed(), lastEvent(), and lastKey to detect what the user types at the keyboard.
Keyboard events
Use these terms to set up handlers that respond to pressing keys:
on keyDown

keyDownScript

on keyUp

keyUpScript

flushInputEvents

Lingo
The Lingo terms in this section are important language elements that you use to construct scripts.

12

Chapter 1

Boolean values
Use these terms to test whether a condition exists:

FALSE (0
TRUE (1

is the numerical equivalent of FALSE).

is the numerical equivalent of TRUE).

not
or

Script control
Use these terms to control how a script executes:
abort

pass

do

result

exit

scriptsEnabled

halt

scriptText

nothing

stopEvent

Code structures
Use if to create if..then statements.
Use case, end

case,

and otherwise in case statements.

Use these terms for repeat loops:

end repeat

repeat with

exit repeat

repeat with...down to

next repeat

repeat with...in list

repeat while

Syntax elements
Use these terms as part of Lingos syntax:
# (symbol)

member (keyword)

" (string)

of

(continuation)

or

-- (comment)

property

() (parentheses)

sprite

castLib

the

end

window

global

Lingo by Feature

13

Lists
The terms in this section are useful for working with lists.
Creating lists
Use [

] (list), duplicate() (list function),

or list() to create a list.

Adding list items

Use these terms to add items to a list:
[ ] (bracket access)

addVertex

add

append

addVertex

Deleting list items

Use these terms to delete items from a list:
deleteAll

deleteOne

deleteAt

deleteProp

Retrieving values from a list

Use these terms to retrieve values from a list:
[ ] (bracket access)

getOne()

deleteProp

getPos()

deleteProp

getProp()

getLast()

getPropAt()

Getting information about lists

Use these terms to get information about lists:
count()

max()

findPos

min

findPosNear

param()

ilk()

paramCount()

listP()

Setting values in a list

Use these terms to set values in a list:

14

[ ] (bracket access)

setAt

setaProp

setProp

Chapter 1

Media synchronization
Use these terms to synchronize animation and sound:
cuePointNames

on cuePassed

cuePointTimes

isPastCuePoint()

mostRecentCuePoint

Memory management
The terms in this section are useful for determining memory requirements and controlling when
the movie loads and unloads cast members.
Idle events
Use the on

idle

event handler for Lingo that runs when the movie is idle.

Idle loading
Use these terms to control idle loading:
cancelIdleLoad

idleLoadPeriod

finishIdleLoad

idleLoadTag

idleHandlerPeriod

idleReadChunkSize

idleLoadDone()

netThrottleTicks

Preloading and querying media

Use these terms to load media into memory and check whether media are available:
frameReady()

preloadNetThing()

loaded

preLoadMember

mediaReady

preLoadMovie

preLoad (command)

preLoadRAM

preLoad (cast member property)

purgePriority

preLoadBuffer member

unLoad

preLoadEventAbort

unLoadMember

preLoadMode

unloadMovie

Available memory
Use these terms to check how much memory is available:
freeBlock()

movieFileFreeSize

freeBytes()

movieFileSize

memorySize

Lingo by Feature

15

Memory requirements
Use ramNeeded() and size to determine how much memory required for a cast member or a
range of frames.

Menus
See Menus in the Interface elements section.

Message window
Use these terms to work in the Message window:
put

traceLoad

showXlib

traceLogFile

trace

appMinimize

Monitor
Use colorDepth, deskTopRectList, and switchColorDepth to check and control the monitor.

Mouse interaction
The terms in this section are useful for Lingo related to using the mouse.
Mouse clicks
Use these terms to detect what the user does with the mouse:

16

clickOn

mouseLine

doubleClick

mouseLoc

emulateMultiButtonMouse

mouseMember

lastClick()

mouseOverButton

lastEvent()

on mouseUp (event handler)

lastRoll

mouseV

mouseChar

mouseWord

on mouseDown (event handler)

on rightMouseDown (event handler)

mouseH

on rightMouseUp (event handler)

mouseItem

rollOver()

mouseLevel

stillDown

Chapter 1

Mouse events
Use these terms to set up handlers that respond to mouse events:
mouseDownScript

on mouseUp (event handler)

mouseUpScript

on mouseUpOutside

on mouseDown (event handler)

on mouseWithin

on mouseEnter

on rightMouseDown (event handler)

on mouseLeave

on rightMouseUp (event handler)

Cursor control
Use cursor (command), cursor
pointer (cursor).

(sprite property),

and cursorSize to control the

Movies in a window
The terms in this section are useful for working with movies in a window.
Movie in a window events
Use these event handlers to contain Lingo that you want to run in response to events in a movie
in a window:
activeCastLib

on openWindow

on closeWindow

on resizeWindow

on moveWindow

on zoomWindow

Opening and closing movies in a window

Use these terms for opening and closing windows:
close window

open window

forget

windowList

Window appearance
Use these terms to check and set the appearance of a movies window:
drawRect

sourceRect

fileName (window property)

tell

frontWindow

title

modal

titleVisible

moveToBack

visible (window property)

moveToFront

windowPresent()

name (window property)

windowType

rect (window)

appMinimize

Lingo by Feature

17

Communication between movies

Use the tell command to send messages between movies.

Movies
The terms in this section are useful for managing movies.
Stopping movies
Use these terms to stop or quit the movie or projector:
exitLock

quit

halt

restart

pauseState

shutDown

Movie information
Use these terms to obtain information about the movie and the movies environment:
environment

moviePath

lastFrame

number (system property)

movie

runMode

movieFileFreeSize

safePlayer

movieFileSize

version

movieName

movieFileVersion

Source control
Use these terms to manage Director projects being worked on by more than one person:
comments

creationDate

modifiedBy

modifiedDate

linkAs()

seconds

Saving movies
Use saveMovie and updateMovieEnabled to save changes to a movie.
Error checking
Use the alertHook event to post alerts that describe errors in a projector.
Movie events
Use the on prepareMovie, on
responds to movie events.

18

Chapter 1

startMovie,

and on

stopMovie

event handlers for Lingo that

Multiuser server
Director MX users should use Macromedia Flash Communication Server MX for
communication among Director movies and with application servers. For more information
about using Flash Communication Server MX, see Using Flash Communication Server MX in
Using Director.

Navigation
Use these terms to jump to different locations:
delay

goToFrame

go

gotoNetMovie

go loop

gotoNetPage

go next

play

go previous

play done

Network Lingo
The terms in this section are useful for working with the network.
Downloading and streaming media
Use these terms to obtain or stream media from the network:
downloadNetThing (For projectors and
authoring only)

gotoNetPage

getNetText()

postNetText

gotoNetMovie

preloadNetThing()

Checking availability
Use frameReady() and mediaReady to check whether specific media are
completely downloaded.
Using network operations
Use these terms to check the progress of a network operation or get information regarding
network media:
getStreamStatus()

netMIME()

getLatestNetID

netTextResult()

netAbort

on streamStatus

netDone()

proxyServer

netError()

tellStreamStatus()

netPresent

URLEncode

netLastModDate()

Lingo by Feature

19

Working with the local computer

Use these terms to work with the users computer:
browserName()

clearCache (For projectors and

authoring only)

cacheDocVerify() (For projectors and

authoring only)

getPref()

cacheSize() (For projectors and

authoring only)

setPref

Browsers
Use on EvalScript, externalEvent, and netStatus to interact with browsers. For additional
information about browser scripting using languages such as JavaScript, see Shockwave
Publishing on the Director Support Center at www.macromedia.com/support/director/
internet.html.
Accessing EMBED and OBJECT tag parameters
Use externalParamCount(), externalParamName(),
EMBED and OBJECT parameter tags:

and externalParamValue() to access

Operators
The terms in this section are operators available in Lingo.
Math operators
Use these terms for math statements:
* (multiplication)

<> (not equal)

/ (division)

> (greater than)

+ (addition)

>= (greater than or equal to)

- (minus)

< (less than)

= (equals)

<= (less than or equal to)

Comparison operators
Use and, not, and or to compare expressions.

Palettes and color

Use these terms to check and set palettes for movies and for cast members:

20

color()

paletteMapping

depth

puppetPalette

palette

rgb()

Chapter 1

Parent scripts
Use these terms to work with parent scripts and child objects:
actorList

property

ancestor

on stepFrame

new()

handler()

handlers()

rawNew()

Points and rectangles

These terms are useful for checking and setting points and rectangles.
inflate

quad

inside()

rect (camera)

intersect()

rect (sprite)

map()

sourceRect

offset() (rectangle function)

union()

point()

For Lingo that controls a sprites bounding rectangle, see Sprite dimensions.

Projectors
These terms are useful for working with projectors:
alertHook

platform

environment

runMode

editShortCutsEnabled

Puppets
Use these terms to control the puppet property of sprites and effects channels:
puppet

puppetTempo

puppetPalette

puppetTransition

puppetSound

updateStage

puppetSprite

Random numbers
Use random() and randomSeed to generate random numbers.

Lingo by Feature

21

Score
The following terms let you work with the Score.
Score properties
Use lastFrame, score, and scoreSelection to work with the movies Score.
Score generation
Use these terms to create Score content from Lingo:
beginRecording

scoreSelection

clearFrame

scriptNum

deleteFrame

scriptType

duplicateFrame

tweened

endRecording

updateFrame

insertFrame

updateLock

scoreColor

Shapes
Use these Lingo terms to work with shapes:
filled

pattern

lineDirection

shapeType

lineSize

Shockwave audio
Use these terms to check, stream, and play Shockwave audio sounds:

22

bitRate

play member

bitsPerSample

preLoadBuffer member

copyrightInfo

preLoadTime

duration

sampleRate

getError()

soundChannel (SWA)

getErrorString()

state (Flash, SWA)

numChannels

stop member

pause (movie playback)

streamName

percentPlayed

URL

percentStreamed

volume (cast member property)

Chapter 1

Sound
The terms in this section are useful for playing sounds.
Sound information
Use these terms to get information about a sound:
channelCount

soundEnabled

sound

volume (sprite property)

soundBusy()

isBusy()

sampleCount

status

Playing sound
Use these terms to control how sound plays:
puppetSound

sound fadeOut

sound close

sound playFile

sound fadeIn

sound stop

breakLoop()

elapsedTime

endTime

fadeIn()

fadeOut()

fadeTo()

getPlaylist()

setPlaylist()

loopCount

loopEndTime

loopStartTime

loopsRemaining

member (sound property)

pan (sound property)

pause() (sound playback)

playNext()

queue()

rewind()

stop() (sound)

play() (sound)

RealMedia sound
See Digital video.

Sprites
The Lingo terms in this section are for sprites.
Sprite events
Use the on beginSprite and on
run when a sprite begins or ends.

endSprite

event handlers to contain Lingo that you want to

Assigning cast members to sprites

Use castLibNum, member

(sprite property),

or memberNum to specify a sprites cast member.

Lingo by Feature

23

Rotating sprites
Use the rotation sprite property to rotate sprites.
Dragging sprites
Use these terms to set how the user can drag sprites:
constrainH()

moveableSprite

constrainV()

sprite...intersects

constraint

sprite...within

Sprites and Lingo

Use these terms to manage how Lingo controls sprites:
puppetSprite

spriteNum

puppet

sendSprite

scriptNum

sendAllSprites

scriptInstanceList

Drawing sprites on the Stage

Use these terms to control how Director draws a sprite on the Stage:
blend

skew

flipH

trails

flipV

tweened

ink

updateStage

quad

visible (sprite property)

rotation

Sprite dimensions
Use these terms to check and set the size of a sprites bounding rectangle:
bottom

right

height

top

left

width

quad

zoomBox

You can also manipulate a sprites bounding rectangle with Lingo for rectangles. See Points and
rectangles.
Sprite locations
Use the loc, locH, and locV sprite properties to check and set sprite locations.

24

Chapter 1

Sprite color
Use these terms to check and set a sprites color:
backColor

color (sprite and cast member property)

bgColor

foreColor

Stage
These terms are useful for controlling the Stage and determining its size and location:
centerStage

stageColor

fixStageSize

stageLeft

picture (window property)

stageRight

stage

stageTop

stageBottom

updateStage

Tempo
Use the puppetTempo command to control a movies tempo.

Text
The terms in this section are useful for working with text, strings, and fields.
Manipulating strings
Use these terms to manipulate strings:
& (concatenator)

put...before

&& (concatenator)

put...into

delete

string()

hilite (cast member property)

stringP()

put...after

text

Chunk expressions
Use these terms to identify chunks of text:
char...of

number (words)

chars()

offset() (string function)

contains

paragraph

EMPTY

ref

item...of

selection (text cast member property)

itemDelimiter

selectedText

last()

selEnd (fields only)

length()

selStart (fields only)

Lingo by Feature

25

line...of

string()

number (characters)

stringP()

number (items)

value()

number (lines)

word...of

Editable text
Use the editable property to specify whether text is editable.
Shocked fonts
Use these terms to include Shocked fonts with downloaded text:
recordFont

bitmapSizes

originalFont

characterSet

Character formatting
Use these terms to format text:
backColor

fontf

bgColor

fontSize

charSpacing

fontStyle

color()

foreColor

dropShadow

Paragraph formatting
Use these terms to format paragraphs:
alignment

rightIndent

bottomSpacing

tabCount

firstIndent

tabs

fixedLineSpace

top (3D)

leftIndent

wordWrap

margin

Text cast member properties

Use these terms to work with the entire text content of a text cast member:
antiAlias

kerning

antiAliasThreshold

kerningThreshold

autoTab

picture (cast member property)

HTML

RTF

Lingo that applies to chunk expressions is also available to the text within a text cast member.

26

Chapter 1

Mouse pointer position in text

Use these terms to detect where the mouse pointer is within text:
pointInHyperlink()

pointToParagraph()

pointToChar()

pointToWord()

pointToItem()

Text boxes for field cast members

Use these terms to set up the box for a field cast member:
border

lineHeight() (function)

boxType

lineHeight (cast member property)

lineCount

pageHeight

Scrolling text
Use these terms to work with scrolling text:
linePosToLocV()

scrollByLine

locToCharPos()

scrollByPage

locVToLinePos()

scrollTop

Constants
Use these terms to work with constants:
BACKSPACE

RETURN (constant)

EMPTY

VOID

ENTER

Time
The terms in this section are useful for working with time.
Current date and time
Use these terms to determine the current date and time:
abbr, abbrev, abbreviated

short

date() (system clock)

systemDate

long

Lingo by Feature

27

Measuring time
Use these terms to measure time in a movie:
framesToHMS()

ticks

HMStoFrames()

time()

milliseconds

timer

startTimer

Timeouts
Use these terms to handle timeouts:
timeoutKeyDown

timeoutMouse

timeoutLapsed

timeoutPlay

timeoutLength

timeoutScript

name (timeout property)

period

persistent

target

time()

timeout()

timeoutHandler

timeoutList

Transitions
Use these terms to work with transitions:
changeArea

puppetTransition

chunkSize

transitionType

duration

Variables
The terms in this section are useful for creating and changing variables:
Creating variables
Use these terms to create variables:
= (equals)

property

global

Testing and changing variables

Use these terms to check and change the values assigned to variables:

28

= (equals)

put

clearGlobals

set...to, set...=

globals

showGlobals

ilk()

showLocals

Chapter 1

Vector shapes
Use these Lingo terms to work with vector shapes:
addVertex

gradientType

antiAlias

imageEnabled

backgroundColor

moveVertex()

broadcastProps

moveVertexHandle()

centerRegPoint

originH

closed

originMode

defaultRect

originPoint

defaultRectMode

originV

deleteVertex()

rotation

directToStage

scale

endColor

scaleMode

fillColor

showProps()

fillCycles

skew

fillDirection

static

fillMode

strokeColor

fillOffset

strokeWidth

fillScale

vertexList

flashRect

viewPoint

flipH

viewScale

flipV

viewV

curve

newCurve()

regPointVertex

XML parsing
The following Lingo is useful for XML parsing within Director.
attributeName

ignoreWhiteSpace()

attributeValue

makeList()

child (XML)

makeSubList()

count()

name (XML property)

doneParsing()

parseString()

getError() (XML)

parseURL()

Lingo by Feature

29

Xtra extensions
Use these terms to work with Xtra extensions:

30

movieXtraList

xtra

name (system property)

xtraList

number of xtras

xtras

Chapter 1

CHAPTER 2
3D Lingo by Feature

This chapter lists the various 3D features of Macromedia Director MX and the corresponding
Lingo elements that you can use to implement those features.

Animation
Use these terms to work with 3D animation. See also the lists of terms for the Keyframe player
and Bones player modifiers.
animationEnabled

pause() (3D)

autoblend

play() (3D)

blendTime

playing (3D)

cloneMotionFromCastmember

playlist

count

playNext() (3D)

currentLoopState

playRate

currentTime (3D)

positionReset

deleteMotion

queue() (3D)

lockTranslation

removeLast()

motion

rotationReset

name

type (motion)

newMotion()

Anti-aliasing
Use these terms to work with anti-aliasing:
antiAliasingEnabled

antiAliasingSupported

31

Backdrops and overlays

Use these terms to manipulate backdrops and overlays in 3D cast members:
addBackdrop

regPoint (3D)

addOverlay

removeBackdrop

blend (3D)

removeOverlay

count

rotation (backdrop and overlay)

insertBackdrop

scale (backdrop and overlay)

insertOverlay

source

loc (backdrop and overlay)

Bones player modifier

Use these terms to control the functionality of the Bones player modifier:
autoblend

play() (3D)

blendTime

playing (3D)

bonesPlayer (modifier)

playlist

count

playNext() (3D)

currentTime (3D)

playRate

getBoneID

queue() (3D)

currentLoopState

removeLast()

getWorldTransform()

rootLock

lockTranslation

rotationReset

positionReset

transform (property)

pause() (3D)

Cameras
Use these terms to work with cameras and camera properties:

32

addCamera

orthoHeight

addToWorld

pointAt

autoCameraPosition

pointAtOrientation

boundingSphere

position (transform)

camera

projection

cameraCount()

projectionAngle

cameraPosition

rect (camera)

cameraRotation

removeFromWorld

clone

rootNode

cloneDeep

rotate

Chapter 2

count

scale (transform)

deleteCamera

transform (property)

fieldOfView (3D)

translate

hither

userData

isInWorld()

worldPosition

name

yon

newCamera

Child and parent nodes

Use these terms to control parent-child relationships between models:
addChild

count

child

parent

Collision detection
These terms are useful for detecting and responding to collisions between models:
collision (modifier)

pointOfContact

collisionData

registerForEvent()

collisionNormal

registerScript()

enabled (collision)

resolve

immovable

resolveA

window("Tool Panel").modal = FALSE

resolveB

modelA

setCollisionCallback()

modelB

Creating and removing objects

Use these terms to create and remove objects:
add (3D texture)

deleteShader

addBackdrop

deleteTexture

addModifier

duplicate

addOverlay

insertBackdrop

addToWorld

insertOverlay

camera

newLight

child

newMesh

clone

newModel

cloneDeep

newModelResource

cloneModelFromCastmember

newMotion()

3D Lingo by Feature

33

cloneMotionFromCastmember

newShader

deleteCamera

newTexture

deleteGroup

removeModifier

deleteLight

removeBackdrop

deleteModel

removeFromWorld

deleteModelResource

removeOverlay

deleteMotion

Fog
Use these terms to work with fog:
color (fog)

far (fog)

decayMode

fog

enabled (fog)

near (fog)

Groups
Use these terms to work with groups:
addChild

newGroup

addToWorld

pointAt

boundingSphere

pointAtOrientation

child

position (transform)

clone

removeFromWorld

cloneDeep

rotate

count

scale (transform)

deleteGroup

transform (property)

group

translate

isInWorld()

userData

name

worldPosition

Inker modifier
Use these terms to control the functionality of the Inker modifier:

34

boundary

lineColor

creaseAngle

lineOffset

creases

silhouettes

inker (modifier)

useLineOffset

Chapter 2

Keyframe player modifier

Use these terms to control the functionality of the Keyframe player modifier:
autoblend

playing (3D)

blendFactor

playlist

blendTime

playNext() (3D)

count

playRate

currentLoopState

positionReset

currentTime (3D)

queue() (3D)

keyframePlayer (modifier)

removeLast()

lockTranslation

rootLock

pause() (3D)

rotationReset

play() (3D)

update

Level of detail modifier

Use these terms to control the functionality of the level of detail (LOD) modifier:
auto

level

bias

lod (modifier)

Lights
Use these terms to work with lights and light properties:
addToWorld

pointAt

ambientColor

pointAtOrientation

attenuation

position (transform)

boundingSphere

removeFromWorld

color (light)

rotate

count

scale (transform)

clone

specular (light)

cloneDeep

spotAngle

deleteLight

spotDecay

directionalColor

transform (property)

directionalPreset

translate

isInWorld()

type (light)

light

userData

name

worldPosition

newLight

3D Lingo by Feature

35

Mesh deform modifier

Use these terms to control the functionality of the mesh deform modifier:
add (3D texture)

normalList

face

textureCoordinateList

mesh (property)

textureLayer

meshDeform (modifier)

vertexList (mesh deform)

neighbor

Miscellaneous
clearAtRender

resetWorld

clearValue

revertToWorldDefaults

directToStage

sendEvent

loadFile()

setCollisionCallback()

registerForEvent()

unregisterAllEvents

registerScript()

revertToWorldDefaults

Model resources
Use these terms to work with 3D model resources:
count

newModelResource

deleteModelResource

resolution

modelResource

resource

name

type (model resource)

Models
Use these terms to work with 3D models:

36

addToWorld

position (transform)

boundingSphere

removeFromWorld

clone

renderStyle

cloneDeep

resource

cloneModelFromCastmember

rotate

count

scale (transform)

deleteModel

shadowPercentage

isInWorld()

shaderList

model

transform (property)

modifier

translate

Chapter 2

name

userData

newModel

visibility

pointAt

worldPosition

pointAtOrientation

Modifiers
These terms are useful for applying modifiers to models and model resources. See the name of the
specific modifier you are using for a list of terms that work with that modifier.
addModifier

modifiers

count

removeModifier

modifier

Movie and system properties

Use these terms to determine the 3D capabilities of the playback computer:
active3dRenderer

getRendererServices()

colorBufferDepth

preferred3DRenderer

depthBufferDepth

renderer

getHardwareInfo()

rendererDeviceList

Nodes
Use these terms to manage nodes. A node is any object that exists in the world, including lights,
cameras, models, and groups.
addToWorld

isInWorld()

clone

name

cloneDeep

removeFromWorld

count

userData

Particle systems
See Primitives.

Picking
See Selecting models.

3D Lingo by Feature

37

Primitives
The following sections list the terms used to work with each type of primitive.
Use the primitives property to determine which types of primitives are supported by the
current 3D renderer.
Boxes
Use these terms to control properties of 3D boxes:
back

length (3D)

bottom (3D)

lengthVertices

front

right (3D)

height (3D)

top (3D)

heightVertices

width (3D)

left (3D)

widthVertices

Cylinders
Use these terms to control properties of 3D cylinders:
bottomCap

resolution

bottomRadius

state (3D)

endAngle

topCap

height (3D)

topRadius

numSegments

Meshes
Use these terms to control properties of 3D meshes:
build()

normalList

colorList

shadowPercentage

count

textureCoordinateList

face

textureCoordinates

generateNormals()

vertexList (mesh deform)

newMesh

Particle systems
Use these terms to control properties of 3D particle systems:

38

angle

minSpeed

blendRange

window("Tool Panel").modal = FALSE

colorRange

numParticles

direction

path

Chapter 2

distribution

pathStrength

drag

region

gravity

sizeRange (contains end and start)

lifetime

texture

loop (emitter)

tweenMode

maxSpeed

wind

Planes
Use these terms to control properties of 3D planes:
length (3D)

width (3D)

lengthVertices

widthVertices

Spheres
Use these terms to control properties of 3D spheres:
endAngle

resolution

radius

state (3D)

Selecting models
Use these terms to enable individual models in a 3D cast member to be selected and respond to
mouse clicks. This is also known as picking.
modelsUnderLoc

spriteSpaceToWorldSpace

modelsUnderRay

worldSpaceToSpriteSpace

modelUnderLoc

Shaders
Use these terms to work with shaders:
ambient

renderStyle

blend (3D)

shadowPercentage

blendConstant

shaderList

blendConstantList

shadowPercentage

blendFunction

shadowStrength

blendFunctionList

silhouettes

blendSource

specular (shader)

blendSourceList

specularColor

count

specularLightMap

deleteShader

style

diffuse

textureMode

3D Lingo by Feature

39

diffuseColor

textureModeList

diffuseLightMap

textureRepeat

emissive

textureRepeatList

flat

textureTransform

glossMap

textureTransformList

name

transparent

newShader

type (shader)

renderStyle

useDiffuseWithTexture

region

wrapTransformList

reflectivity

Engraver shader
Use these terms to work with the Engraver shader:
density

rotation (engraver shader)

brightness

Newsprint shader
Use these terms to work with the Newsprint shader:
density

brightness

Painter shader
Use these terms to work with the Painter shader:
colorSteps

shadowPercentage

highlightPercentage

shadowStrength

highlightStrength

style

Sprites (3D)
rect (camera)

registerForEvent()

Use these terms to control properties of 3D sprites:

Streaming
Use these terms to control the streaming of 3D cast members:

40

bytesStreamed (3D)

state (3D)

preLoad (3D)

streamSize (3D)

Chapter 2

Subdivision surfaces modifier

Use these terms to control the functionality of the subdivision surfaces (SDS) modifier:
depth (3D)

sds (modifier)

enabled (sds)

subdivision

error

tension

Text (3D)
Use these terms to control the appearance of 3D text:
autoCameraPosition

displayMode

bevelDepth

extrude3D

bevelType

smoothness

displayFace

tunnelDepth

Textures
Use these terms to work with textures:
compressed

newTexture

count

quality (3D)

deleteTexture

renderFormat

height (3D)

texture

member

textureRenderFormat

name

textureType

nearFiltering

type (texture)

Toon modifier
Use these terms to control the functionality of the Toon modifier:
boundary

lineOffset

colorSteps

shadowPercentage

creaseAngle

shadowStrength

creases

silhouettes

highlightPercentage

style

highlightStrength

toon (modifier)

lineColor

useLineOffset

3D Lingo by Feature

41

Transforms
Use these terms to work with transforms:
duplicate

preRotate

getWorldTransform()

preScale()

identity()

preTranslate()

interpolate()

rotate

interpolateTo()

rotation (transform)

inverse()

scale (transform)

invert()

transform (property)

multiply()

translate

pointAt

worldPosition

pointAtOrientation

xAxis

position (transform)

yAxis

preMultiply

zAxis

Vector math
Use these terms to perform vector math operations:

42

angleBetween

getNormalized

axisAngle

magnitude

cross

normalize

crossProduct()

randomVector

distanceTo()

vector()

dot()

x (vector property)

dotProduct()

y (vector property)

duplicate

z (vector property)

Chapter 2

CHAPTER 3
Lingo Dictionary

This dictionary describes the syntax and use of Lingo elements in Macromedia Director MX.
Nonalphabetical operators are presented first, followed by all other operators in alphabetical order.
The entries in this dictionary are the same as those in Director Help. To use examples in a script,
copy the example text from Director Help and paste it in the Script window.

# (symbol)
Syntax

#symbolName
Description

Symbol operator; defines a symbol, a self-contained unit that can be used to represent a condition
or flag. The value symbolName begins with an alphabetical character and may be followed by any
number of alphabetical or numerical characters.
A symbol can do the following:

Assign a value to a variable.

Compare strings, integers, rectangles, and points.
Pass a parameter to a handler or method.
Return a value from a handler or method.

A symbol takes up less space than a string and can be manipulated, but unlike a string it does not
consist of individual characters. You can convert a symbol to a string for display purposes by using
the string function.
The following are some important points about symbol syntax:

Symbols are not case-sensitive.

Symbols cant start with a number.
Spaces may not be used, but you can use underscore characters to simulate them.
Symbols use the 128 ASCII characters, and letters with diacritical or accent marks are treated
as their base letter.

Periods may not be used in symbols.

43

All symbols, global variables, and names of parameters passed to global variables are stored in a
common lookup table.
Example

This statement sets the state variable to the symbol #Playing:

state = #Playing
See also

ilk(), string(), symbol(), symbolP()

. (dot operator)
Syntax

objectReference.objectProperty
textExpression.objectProperty
object.commandOrFunction()
Description

Operator; used to test or set properties of objects, or to issue a command or execute a function of
the object. The object may be a cast member, a sprite, a property list, a child object of a parent
script, or a behavior.
Examples

This statement displays the current member contained by the sprite in channel 10:
put sprite(10).member

To use the alternate syntax and call a function, you can use this form:
myColorObject = color(#rgb, 124, 22, 233)
put myColorObject.ilk()
-- #color

- (minus)
Syntax

(Negation): -expression
Description

Math operator; reverses the sign of the value of expression.

This is an arithmetic operator with a precedence level of 5.
Syntax

(Subtraction): expression1 - expression2

Description

Math operator; performs an arithmetic subtraction on two numerical expressions, subtracting

expression2 from expression1. When both expressions are integers, the difference is an
integer. When either or both expressions are floating-point numbers, the difference is a
floating-point number.
This is an arithmetic operator with a precedence level of 3.

44

Chapter 3

Examples

(Negation): This statement reverses the sign of the expression 2 + 3:

put -(2 + 3)

The result is -5.

(Subtraction): This statement subtracts the integer 2 from the integer 5 and displays the result in
the Message window:
put 5 - 2

The result is 3, which is an integer.

(Subtraction): This statement subtracts the floating-point number 1.5 from the floating-point
number 3.25 and displays the result in the Message window:
put 3.25 - 1.5

The result is 1.75, which is a floating-point number.

-- (comment)
Syntax

-- comment
Description

Comment delimiter; indicates the beginning of a script comment. On any line, anything that
appears between the comment delimiter (double hyphen) and the end-of-line return character is
interpreted as a comment rather than a Lingo statement.
The Director player for Java accepts Lingo that uses this delimiter, but comments do not appear
in the final Java code.
Example

This handler uses a double hyphen to make the second, fourth, and sixth lines comments:
on resetColors
-- This handler resets the sprites colors.
sprite(1).forecolor = 35
-- bright red
sprite(1).backcolor = 36
-- light blue
end

& (concatenator)
Syntax

expression1 & expression2

Description

String operator; performs a string concatenation of two expressions. If either expression1 or

expression2 is a number, it is first converted to a string. The resulting expression is a string.
This is a string operator with a precedence level of 2.
Be aware that Lingo allows you to use some commands and functions that take only one argument
without parentheses surrounding the argument. When an argument phrase includes an operator,
Lingo interprets only the first argument as part of the function, which may confuse Lingo.

Lingo Dictionary

45

For example, the open window command allows one argument that specifies which window to
open. If you use the & operator to define a pathname and filename, Director interprets only the
string before the & operator as the filename. For example, Lingo interprets the statement open
window the applicationPath & "theMovie" as (open window the applicationPath) &
("theMovie"). Avoid this problem by placing parentheses around the entire phrase that includes
an operator, as follows:
open window (the applicationPath & "theMovie")

The parentheses clear up Lingos confusion by changing the precedence by which Lingo deals with
the operator, causing Lingo to treat the two parts of the argument as one complete argument.
Examples

This statement concatenates the strings abra and cadabra and displays the resulting string in
the Message window:
put "abra" & "cadabra"

The result is the string abracadabra.

This statement concatenates the strings $ and the content of the price variable and then
assigns the concatenated string to the Price field cast member:
member("Price").text = "$" & price

&& (concatenator)
Syntax

expression1 && expression2

Description

String operator; concatenates two expressions, inserting a space character between the original
string expressions. If either expression1 or expression2 is a number, it is first converted to a
string. The resulting expression is a string.
This is a string operator with a precedence level of 2.
Examples

This statement concatenates the strings abra and cadabra and inserts a space between the two:
put "abra" && "cadabra"

The result is the string abra cadabra.

This statement concatenates the strings Today is and todays date in the long format and inserts
a space between the two:
put "Today is" && the long date

If todays date is Tuesday, July 30, 2000, the result is the string Today is Tuesday, July 30, 2000.

46

Chapter 3

() (parentheses)
Syntax

(expression)
Description

Grouping operator; performs a grouping operation on an expression to control the order of

execution of the operators in an expression. This operator overrides the automatic precedence
order so that the expression within the parentheses is evaluated first. When parentheses are nested,
the contents of the inner parentheses are evaluated before the contents of the outer ones.
This is a grouping operator with a precedence level of 5.
Be aware that Lingo allows you to use some commands and functions that take only one argument
without parentheses surrounding the argument. When an argument phrase includes an operator,
Lingo interprets only the first argument as part of the function, which may confuse Lingo.
For example, the open window command allows one argument that specifies which window to
open. If you use the & operator to define a pathname and filename, Director interprets only the
string before the & operator as the filename. For example, Lingo interprets the statement open
window the applicationPath & "theMovie" as (open window the applicationPath) &
("theMovie"). Avoid this problem by placing parentheses around the entire phrase that includes
an operator, as follows:
open window (the applicationPath & "theMovie")
Example

These statements use the grouping operator to change the order in which operations occur (the
result appears below each statement):
put (2 + 3) * (4 + 5)
-- 45
put 2 + (3 * (4 + 5))
-- 29
put 2 + 3 * 4 + 5
-- 19

* (multiplication)
Syntax

expression1 * expression2
Description

Math operator; performs an arithmetic multiplication on two numerical expressions. If both

expressions are integers, the product is an integer. If either or both expressions are floating-point
numbers, the product is a floating-point number.
This is an arithmetic operator with a precedence level of 4.
Examples

This statement multiplies the integers 2 and 3 and displays the result in the Message window:
put 2 * 3

The result is 6, which is an integer.

Lingo Dictionary

47

This statement multiplies the floating-point numbers 2.0 and 3.1414 and displays the result in
the Message window:
put 2.0 * 3.1416

The result is 6.2832, which is a floating-point number.

+ (addition)
Syntax

expression1 + expression2
Description

Math operator; performs an arithmetic sum on two numerical expressions. If both expressions are
integers, the sum is an integer. If either or both expressions are floating-point numbers, the sum is
a floating-point number.
This is an arithmetic operator with a precedence level of 4.
Examples

This statement adds the integers 2 and 3 and then displays the result, 5, an integer, in the
Message window:
put 2 + 3

This statement adds the floating-point numbers 2.5 and 3.25 and displays the result, 5.7500, a
floating-point number, in the Message window:
put 2.5 + 3.25

+ (addition) (3D)
Syntax

vector1 + vector2
vector + scalar
Description

3D vector operator; adds the components of two vectors, or adds the scalar value to each
component of the vector and returns a new vector.
vector1
vector2

+ vector2 adds the components of vector1 to the corresponding to components of

and returns a new vector.

vector + scalar adds the scalar value to each of the components of the vector and returns a
new vector.

- (subtraction)
Syntax

vector1 - vector2
vector - scalar
Description

3D vector operator; subtracts the components of vector2 from the corresponding components
of vector1, or subtracts the scalar value from each of the components and returns a new vector.

48

Chapter 3

vector1
vector1

- vector2 subtracts the values of vector2 from the corresponding components in

and returns a new vector.

- scaler subtracts the value of the scalar from each of the components in the vector and
returns a new vector.

vector

* (multiplication)
Syntax

vector1 * vector2
vector * scalar
transform * vector
Description

3D vector operator; multiplies the components of vector1 by the corresponding components in

vector2, and returns the dot product, or multiplies each of the components the vector by the
scalar value and returns a new vector.
* vector2 returns the dot product of the two vectors, which is not a new vector. This
operation is the same as vector1.dotproduct.vector2.

vector1

vector * scalar multiplies each of the components in the vector by the scalar value and returns
a new vector.
transform * vector multiplies the transform by the vector and returns a new vector. The new
vector is the result of applying the positional and rotational changes defined by transform to the
vector. Note that vector * transform is not supported.
See also

dotProduct()

/ (division)
Syntax

expression1 / expression2
Description

Math operator; performs an arithmetic division on two numerical expressions, dividing

expression1 by expression2. If both expressions are integers, the quotient is an integer. If
either or both expressions are floating-point numbers, the quotient is a floating-point number.
This is an arithmetic operator with a precedence level of 4.
Examples

This statement divides the integer 22 by 7 and then displays the result in the Message window:
put 22 / 7

The result is 3. Because both numbers in the division are integers, Lingo rounds the answer down
to the nearest integer.
This statement divides the floating-point number 22.0 by 7.0 and then displays the result in the
Message window:
put 22.0 / 7.0

The result is 3.1429, which is a floating-point number.

Lingo Dictionary

49

/ (division) (3D)
Syntax

vector / scalar
Description

3D vector operator; divides each of the vector components by the scalar value and returns a
new vector.

< (less than)

Syntax

expression1 < expression2

Description

Comparison operator; compares two expressions and determines whether expression1 is less than
expression2 (TRUE), or whether expression1 is greater than or equal to expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, and points. Be aware
that comparisons performed on rects or points are handled as if the terms were lists, with each
element of the first list compared to the corresponding element of the second list.
This is a comparison operator with a precedence level of 1.

<= (less than or equal to)

Syntax

expression1 <= expression2

Description

Comparison operator; compares two expressions and determines whether expression1 is less than
or equal to expression2 (TRUE), or whether expression1 is greater than expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, and points. Be aware
that comparisons performed on rects or points are handled as if the terms were lists, with each
element of the first list compared to the corresponding element of the second list.
This is a comparison operator with a precedence level of 1.

<> (not equal)

Syntax

expression1 <> expression2

Description

Comparison operator; compares two expressions, symbols, or operators and determines whether
expression1 is not equal to expression2 (TRUE), or whether expression1 is equal to
expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, and points. Be aware
that comparisons performed on rects or points are handled as if the terms were lists, with each
element of the first list compared to the corresponding element of the second list.
This is a comparison operator with a precedence level of 1.

50

Chapter 3

= (equals)
Syntax

expression1 = expression2
Description

Comparison operator; compares two expressions, symbols, or objects and determines whether
expression1 is equal to expression2 (TRUE), or whether expression1 is not equal to
expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, lists, and points.
Lists are compared based on the number of elements in the list. The list with more elements is
considered larger than the than the list with fewer elements.
This is a comparison operator with a precedence level of 1.

> (greater than)

Syntax

expression1 > expression2

Description

Comparison operator; compares two expressions and determines whether expression1 is greater
than expression2 (TRUE), or whether expression1 is less than or equal to expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, and points. Be aware
that comparisons performed on rects or points are handled as if the terms were lists, with each
element of the first list compared to the corresponding element of the second list.
This is a comparison operator with a precedence level of 1.

>= (greater than or equal to)

Syntax

expression1 >= expression2

Description

Comparison operator; compares two expressions and determines whether expression1 is greater
than or equal to expression2 (TRUE), or whether expression1 is less than expression2 (FALSE).
This operator can compare strings, integers, floating-point numbers, rects, and points. Be aware
that comparisons performed on rectangles or points are handled as if the terms were lists, with
each element of the first list compared to the corresponding element of the second list.
This is a comparison operator with a precedence level of 1.

Lingo Dictionary

51

[ ] (bracket access)
Syntax

textExpression[chunkNumberBeingAddressed]
textExpression[firstChunk..lastChunk]
Description

Operator; allows a chunk expression to be addressed by number. Useful for finding the nth
chunk in the expression. The chunk can be a word, line, character, paragraph, or other Text cast
member chunk.
Example

This outputs the first word of the third line in the text cast member First Names:
put member("First Names").text.line[3].word[1]

[ ] (list)
Syntax

[entry1, entry2, entry3, ...]

Description

List operator; specifies that the entries within the brackets are one of four types of lists:

Unsorted linear lists

Sorted linear lists
Unsorted property lists
Sorted property lists

Each entry in a linear list is a single value that has no other property associated with it. Each entry
in a property list consists of a property and a value. The property appears before the value and is
separated from the value by a colon. You cannot store a property in a linear list. When using
strings as entries in a list, enclose the string in quotation marks.
For example, [6, 3, 8] is a linear list. The numbers have no properties associated with them.
However, [#gears:6, #balls:3, #ramps:8] is a property list. Each number has a propertyin this
case, a type of machineryassociated with it. This property list could be useful for tracking the
number of each type of machinery currently on the Stage in a mechanical simulation. Properties
can appear more than once in a property list.
Lists can be sorted in alphanumeric order. A sorted linear list is ordered by the values in the list. A
sorted property list is ordered by the properties in the list. You sort a list by using the appropriate
command for a linear list or property list.

In linear lists, symbols and strings are case sensitive.

In property lists, symbols arent case sensitive, but strings are case sensitive.
A linear list or property list can contain no values at all. An empty list consists of two square
brackets ([ ]). To create or clear a linear list, set the list to [ ]. To create or clear a property list, set
the list to [:].
You can modify, test, or read items in a list.

52

Chapter 3

Lingo treats an instance of a list as a reference to the list. This means each instance is the same
piece of data, and changing it will change the original. Use the duplicate command to create
copies of lists.
Lists are automatically disposed when they are no longer referred to by any variable. When a list is
held within a global variable, it persists from movie to movie.
You can initialize a list in the on prepareMovie handler or write the list as a field cast member,
assign the list to a variable, and then handle the list by handling the variable.
Not all PC keyboards have square brackets. If square brackets arent available, use the list
function to create a linear list.
For a property list, create the list pieces as a string before converting them into a useful list.
myListString = numToChar(91) & ":" & numToChar(93)
put myListString
-- "[:]"
myList = myListString.value
put myList
-- [:]
put myList.listP
-- 1
myList[#name] = "Brynn"
put myList
-- [#name: "Brynn"]
Examples

This statement defines a list by making the machinery variable equal to the list:
set machinery = [#gears:6, #balls:3, #ramps:8]

This handler sorts the list aList and then displays the result in the Message window:
on sortList aList
alist.sort()
put aList
end sortList

If the movie issues the statement sortList machinery, where machinery is the list in the
preceding example, the result is [#balls:3, #gears:6, #ramps:8].
This statement creates an empty linear list:
set x = [ ]

This statement creates an empty property list:

set x = [:]
See also

add, addVertex, append, count(), deleteAt, duplicate() (list function), findPos,

findPosNear, getProp(), getAt, getLast(), getPos(), ilk(), list(), max(), min, setAt,
setaProp, sort

Lingo Dictionary

53

" (string)
Syntax

"
Description

String constant; when used before and after a string, quotation marks indicate that the string is a
literalnot a variable, numerical value, or Lingo element. Quotation marks must always
surround literal names of cast members, casts, windows, and external files.
Example

This statement uses quotation marks to indicate that the string San Francisco is a literal string,
the name of a cast member:
put member("San Francisco").loaded
See also

QUOTE

(continuation)
Description

The symbol is obsolete. Use the \ character instead. See \ (continuation). It is recommended
that you replace this symbol with the \ symbol in your older scripts.

\ (continuation)
Syntax

first part of a statement on this line \

second part of the statement \
third part of the statement
Description

Continuation symbol; when used as the last character in a line, indicates that the statement
continues on the next line. Lingo then interprets the lines as one continuous statement.
Example

This statement uses the \ character to wrap the statement onto two lines:
set the memberNum of sprite mySprite \
to member "This is a long cast name."

@ (pathname)
Syntax

@pathReference
Description

Pathname operator; defines the path to the current movies folder and is valid on both Windows
and Macintosh computers.

54

Chapter 3

Identify the current movies folder by using the @ symbol followed by one of these pathname
separators:

(forward slash)

(backslash)

(colon)

When a movie is queried to determine its location, the string returned will include the @ symbol.
Be sure to use only the @ symbol when navigating between Director movies or changing the
source of a linked media cast member. The @ symbol does not work when the FileIO Xtra or
other functions are used outside those available within Director.
You can build on this pathname to specify folders that are one or more levels above or below the
current movies folder. Keep in mind that the @ portion represents the current movies location,
not necessarily the location of the projector.

Add an additional pathname separator immediately after the @ symbol to specify a folder one
level up in the hierarchy.

Add folder names and filenames (separated by /, \, or :) after the current folder name to
specify subfolders and files within folders.
You can use relative pathnames in Lingo to indicate the location of a linked file in a folder
different than the movies folder.
Examples

These are equivalent expressions that specify the subfolder bigFolder, which is in the current
movies folder:
@/bigFolder
@:bigFolder
@\bigFolder

These are equivalent expressions that specify the file linkedFile, in the subfolder bigFolder, which
is in the current movies folder:
@:bigFolder:linkedFile
@\bigFolder\linkedFile
@/bigFolder/linkedFile
Examples

This expression specifies the file linkedFile, which is located one level up from the current
movies folder:
@//linkedFile

This expression specifies the file linkedFile, which is located two levels up from the current
movies folder:
@:::linkedFile

These are equivalent expressions that specify the file linkedFile, which is in the folder otherFolder.
The otherFolder folder is in the folder one level up from the current movies folder.
@::otherFolder:linkedFile
@\\otherFolder\linkedFile
@//otherFolder/linkedFile
See also

searchPath, fileName (cast property), fileName (cast member property), fileName

(window property)
Lingo Dictionary

55

abbr, abbrev, abbreviated

These elements are used by the date and time functions.
See also

date() (system clock)

abort
Syntax

abort
Description

Command; tells Lingo to exit the current handler and any handler that called it without
executing any of the remaining statements in the handler. This differs from the exit keyword,
which returns to the handler from which the current handler was called.
The abort command does not quit Director.
Example

This statement instructs Lingo to exit the handler and any handler that called it when the amount
of free memory is less than 50K:
if the freeBytes < 50*1024 then abort
See also

exit, halt, quit

abs()
Syntax

abs (numericExpression)
Description

Math function; calculates the absolute value of a numerical expression. If numericExpression is

an integer, its absolute value is also an integer. If numericExpression is a floating-point number,
its absolute value is also a floating-point number.
The abs function has several uses. It can simplify the tracking of mouse and sprite movement by
converting coordinate differences (which can be either positive or negative numbers) into
distances (which are always positive numbers). The abs function is also useful for handling
mathematical functions, such as sqrt and log.
Example

This statement determines whether the absolute value of the difference between the current
mouse position and the value of the variable startV is greater than 30 (since you wouldnt want
to use a negative number for distance). If it is, the foreground color of sprite 6 is changed.
if (the mouseV - startV).abs > 30 then sprite(6).forecolor = 95

56

Chapter 3

actionsEnabled
Syntax

the actionsEnabled of sprite whichFlashSprite

the actionsEnabled of member whichFlashMember
sprite whichFlashSprite.actionenabled
member whichFlashMember.actionenabled
Description

Cast member property and sprite property; controls whether the actions in a Flash movie are
enabled (TRUE, default) or disabled (FALSE).
This property can be tested and set.
Example

This handler accepts a sprite reference as a parameter, and then toggles the sprites
actionsEnabled property on or off.
Dot syntax:
on ToggleActions whichSprite
sprite (whichSprite).actionsEnabled = not sprite
(whichSprite).actionsEnabled
end

Verbose syntax:
on ToggleActions whichSprite
set the actionsEnabled of sprite whichSprite = not the actionsEnabled of
sprite whichSprite
end

activateApplication
Syntax

on activateApplication
Description

Built-in handler; runs when the projector is brought to the foreground. This handler is useful
when a projector runs in a window and the user can send it to the background to work with other
applications. When the projector is brought back to the foreground, this handler runs. Any
MIAWs running in the projector can also make use of this handler.
During authoring, this handler is called only if Animate in Background is turned on in
General Preferences.
On Windows, this handler is not called if the projector is merely minimized and no other
application is brought to the foreground.
Example

This handler plays a sound each time the user brings the projector back to the foreground:
on activateApplication
sound(1).queue(member("openSound"))
sound(1).play()
end
See also

deactivateApplication, activeCastLib, on deactivateWindow

Lingo Dictionary

57

on activateWindow
Syntax

on activateWindow
statement(s)
end
Description

System message and event handler; contains statements that run in a movie when the user clicks
the inactive window and the window comes to the foreground.
You can use an on activateWindow handler in a script that you want executed every time the
movie becomes active.
Clicking the main movie (the main Stage) does not generate an on

activateWindow

handler.

Example

This handler plays the sound Hurray when the window that the movie is playing in becomes active:
on activateWindow
puppetSound 2, "Hurray"
end
See also

activeWindow, close window, on deactivateWindow, frontWindow, on moveWindow, open

active3dRenderer
Syntax

the active3dRenderer
Description

3D Lingo movie property; indicates the renderer currently in use by the movie for drawing 3D
sprites. This property is equivalent to the getRendererServices().renderer property.
The possible values of the active3DRenderer property are #openGL, #directX7_0,
#directX5_2, and #software. The values #openGL, #directX7_0, and #directX5_2, which are
video card drivers, will lead to much faster performance than #software, a software renderer used
when none of the first three options are available.
The active3dRenderer property can be tested, but not set.
getRendererServices().renderer to set this property.

Use

Examples

These examples show the two ways to determine which renderer is currently in use.
put the active3dRenderer
-- #openGL
put getRendererServices().renderer
-- #openGL
See also

renderer, rendererDeviceList, getRendererServices()

58

Chapter 3

activeCastLib
Syntax

the activeCastLib
Description

System property; indicates which cast was most recently activated. The activeCastLib propertys
value is the casts number.
The activeCastLib property is useful when working with the selection
Use it to determine which cast the selection refers to.

castLib

property.

This property can be tested but not set.

Example

These statements assign the selected cast members in the most recently selected cast to the
variable selectedMembers:
castLibOfInterest = the activeCastLib
selectedMembers = castLib(castLibOfInterest).selection

An equivalent way to write this is:

selectedMembers = castLib(the activeCastLib).selection

activeWindow
Syntax

the activeWindow
Description

Movie property; indicates which movie window is currently active. For the main movie,
activeWindow is the Stage. For a movie in a window, activeWindow is the movie in the window.
Example

This example places the word Active in the title bar of the clicked window and places the word
Inactive in the title bar of all other open windows:
on activateWindow
set clickedWindow = (the windowlist).getPos(the activeWindow)
set windowCount = (the windowlist).count
repeat with x = 1 to windowCount
if x = clickedWindow then
(the activeWindow).title = "Active"
else
(the windowlist[x]).title = "Inactive"
end if
end repeat
end
See also

activeCastLib, windowList

actorList
Syntax

the actorList

Lingo Dictionary

59

Description

Movie property; a list of child objects that have been explicitly added to this list. Objects in
actorList receive a stepFrame message each time the playhead enters a frame.
To add an object to the actorList, use add actorList, theObject. The objects on stepFrame
handler in its parent or ancestor script will then be called automatically at each frame advance.
To clear objects from the

actorList,

set actorList to [ ], which is an empty list.

Director doesnt clear the contents of actorList when branching to another movie, which can
cause unpredictable behavior in the new movie. To prevent child objects in the current movie
from being carried over to the new movie, insert the statement set the actorList = [ ] in the
on prepareMovie handler of the new movie.
Unlike previous versions of Director, actorList is now supported in the Director player for Java.
Examples

This statement adds a child object created from the parent script Moving Ball. All three values are
parameters that the script requires.
add the actorList, new(script "MovingBall", 1, 200,200)

This statement displays the contents of actorList in the Message window:

put the actorList

This statement clears objects from actorList.

the actorList = [ ]
See also

new()

add
Syntax

linearList.add(value)
add linearList, value
Description

List command; for linear lists only, adds the value specified by value to the linear list specified by
linearList. For a sorted list, the value is placed in its proper order. For an unsorted list, the
value is added to the end of the list.
This command returns an error when used on a property list.
Note: Dont confuse the add command with the + operator used for addition or the & operator used to
concatenate strings.

Examples

These statements add the value 2 to the list named bids. The resulting list is [3, 4, 1, 2].
bids = [3, 4, 1]
bids.add(2)

This statement adds 2 to the sorted linear list [1, 4, 5]. The new item remains in alphanumeric
order because the list is sorted.
bids.add(2)

60

Chapter 3

See also

sort

add (3D texture)

Syntax

member(whichCastmember).model(whichModel).meshdeform.mesh[index].\
textureLayer.add()
Description

3D meshdeform modifier command; adds an empty texture layer to the models mesh.
You can copy texture coordinates between layers using the following code:
modelReference.meshdeform.texturelayer[a].texturecoordinatelist =
modelReference.meshdeform.texturelayer[b].texturecoordinatelist
Example

This statement creates a new texture layer for the first mesh of the model named Ear.
member("Scene").model("Ear").meshdeform.mesh[1].\
textureLayer.add()
See also
meshDeform (modifier), textureLayer, textureCoordinateList

addAt
Syntax

list.AddAt(position, value)
addAt list, position, value
Description

List command; for linear lists only, adds a value specified by value to a list at the position
specified by position.
This command returns an error when used with a property list.
Example

This statement adds the value 8 to the fourth position in the list named bids, which is
[3, 2, 4, 5, 6, 7]:
bids = [3, 2, 4, 5, 6, 7]
bids.addAt(4,8)

The resulting value of bids is [3, 2, 4, 8, 5, 6, 7].

addBackdrop
Syntax

sprite(whichSprite).camera{(index)}.addBackdrop(texture, locWithinSprite,
rotation)
member(whichCastmember).camera(whichCamera).addBackdrop(texture,
locWithinSprite, rotation)

Lingo Dictionary

61

Description

3D camera command; adds a backdrop to the end of the cameras list of backdrops. The
backdrop is displayed in the 3D sprite at locWithinSprite with the indicated rotation. The
locWithinSprite parameter is a 2D loc measured from the upper left corner of the sprite.
Examples

The first line of this statement creates a texture named Rough from the cast member named
Cedar and stores it in the variable t1. The second line applies the texture as a backdrop at the
point (220, 220) within sprite 5. The texture has a rotation of 0 degrees. The last line applies the
same texture as a backdrop for camera 1 of the cast member named Scene at the point (20, 20)
with a rotation of 45 degrees.
t1 = member("Scene").newTexture("Rough", #fromCastMember, \
member("Cedar"))
sprite(5).camera.addBackdrop(t1, point(220, 220), 0)
member("Scene").camera[1].addBackdrop(t1, point(20, 20), 45)
See also

removeBackdrop

addCamera
Syntax

sprite(whichSprite).addCamera(whichCamera, index)
Description

3D command; adds the camera whichCamera, at the given index position, to the list of cameras
for the sprite. If index is greater than the value of cameraCount(), the camera is added to the
end of the list. The view from each camera is displayed on top of the view from cameras with
lower index positions. You can set the rect property of each camera to display multiple views
within the sprite.
Example

This statement inserts the camera named FlightCam at the fifth index position of the list of
cameras of sprite 12:
sprite(12).addCamera(member("scene").camera("FlightCam"), 5)
See also

cameraCount(), deleteCamera

62

Chapter 3

addChild
Syntax

member(whichCastmember).node(whichParentNode).addChild(member\
(whichCastmember).node(whichChildNode) {,#preserveWorld})
Description

3D command; adds the node whichChildNode to the list of children of the node
whichParentNode, and removes it from the list of children of its former parent. Either node
argument can be a model, group, camera, or light. An equivalent operation would be to set the
parent property of whichChildNode to whichParentNode.
The optional #preserveWorld parameter has two possible values: #preserveWorld or
#preserveParent. When the child is added with #preserveParent specified, the parent-relative
transform of the child remains unchanged and the child jumps to that transform in the space of its
new parent. The childs world transform is recalculated. When the child is added with
#preserveWorld specified, the world transform of the child remains unchanged and the child does
not jump to its transform in the space of its new parent. Its parent-relative transform is recalculated.
Examples

This statement adds the model named Tire to the list of children of the model named Car.
member("3D").model("Car").addChild(member("3D").model("Tire"))

This statement adds the model named Bird to the list of children of the camera named
MyCamera and uses the #preserveWorld argument to maintain Birds world position.
member("3D").camera("MyCamera").addChild(member("3D").model
("Bird"), #preserveWorld)
See also

parent, addToWorld, removeFromWorld

addModifier
Syntax

member(whichCastmember).model(whichModel).addModifier\
(#modifierType)
Description

3D model command; adds the specified modifier to the model. Possible modifiers are as follows:

#bonesPlayer
#collision
#inker
#keyframePlayer
#lod

(level of detail)

#meshDeform
#sds
#toon

There is no default value for this command.

For more detailed information about each modifier, see the individual modifier entries.

Lingo Dictionary

63

Example

This statement adds the toon modifier to the model named Box.
member("shapes").model("Box").addModifier(#toon)
See also

bonesPlayer (modifier), collision (modifier), inker (modifier), keyframePlayer

(modifier), lod (modifier), meshDeform (modifier), sds (modifier), toon (modifier),
getRendererServices(), removeModifier, modifier, modifier[], modifiers

addOverlay
Syntax

sprite(whichSprite).camera{(index)}.addOverlay(texture, \
locWithinSprite, rotation)
member(whichCastmember).camera(whichCamera).addOverlay(texture, \
locWithinSprite, rotation)
Description

3D camera command; adds an overlay to the end of the cameras list of overlays. The overlay is
displayed in the 3D sprite at locWithinSprite with the indicated rotation. The
locWithinSprite parameter is a 2D loc measured from the upper left corner of the sprite.
Examples

The first line of this statement creates a texture named Rough from the cast member named
Cedar and stores it in the variable t1. The second line applies the texture as an overlay at the point
(220, 220) within sprite 5. The texture has a rotation of 0 degrees. The last line of the statement
applies the same texture as an overlay for camera 1 of the cast member named Scene at the point
(20, 20). The texture has a rotation of 45 degrees.
t1 = member("Scene").newTexture("Rough", #fromCastMember,\
member("Cedar"))
sprite(5).camera.addOverlay(t1, point(220, 220), 0)
member("Scene").camera[1].addOverlay(t1, point(20, 20), 45)
See also

removeOverlay

addProp
Syntax

list.addProp(property, value)
addProp list, property, value
Description

Property list command; for property lists only, adds the property specified by property and its
value specified by value to the property list specified by list. For an unsorted list, the value is
added to the end of the list. For a sorted list, the value is placed in its proper order.
If the property already exists in the list, Lingo creates a duplicate property. You can avoid
duplicate properties by using the setaProp command to change the new entrys property.
This command returns an error when used with a linear list.

64

Chapter 3

Examples

This statement adds the property named kayne and its assigned value 3 to the property list
named bids, which contains [#gee: 4, #ohasi: 1]. Because the list is sorted, the new entry is
placed in alphabetical order:
bids.addProp(#kayne, 3)

The result is the list [#gee: 4, #kayne: 3, #ohasi: 1].

This statement adds the entry kayne: 7 to the list named bids, which now contains [#gee: 4,
#kayne: 3, #ohasi: 1]. Because the list already contains the property kayne, Lingo creates a
duplicate property:
bids.addProp(#kayne, 7)

The result is the list [#gee: 4, #kayne: 3, #kayne: 7, #ohasi: 1].

addToWorld
Syntax

member(whichCastmember).model(whichModel).addToWorld()
member(whichCastmember).group(whichGroup).addToWorld()
member(whichCastmember).camera(whichCamera).addToWorld()
member(whichCastmember).light(whichLight).addToWorld()
Description

3D command; inserts the model, group, camera, or light into the 3D world of the cast member as
a child of the group named World.
When a model, group, camera, or light is created or cloned, it is automatically added to the
world. Use the removeFromWorld command to take a model, group, camera, or light out of the
3D world without deleting it. Use the isInWorld() command to test whether a model, group,
camera, or light has been added or removed from the world.
Example

This statement adds the model named gbCyl to the 3D world of the cast member named Scene.
member("Scene").model("gbCyl").addToWorld()
See also

isInWorld(), removeFromWorld

addVertex
Syntax

member(memberRef).AddVertex(indexToAddAt, pointToAddVertex \
{,[ controlLocH, controlLocV ], [ controlLocH, controlLocV ]})
addVertex(member memberRef, indexToAddAt, pointToAddVertex \
{,[controlLocH, controlLocV], [controlLocH,controlLocV]})
Description

Vector shape command; adds a new vertex to a vector shape cast member in the position specified.
The horizontal and vertical positions are relative to the origin of the vertex shape cast member.
When using the final two optional parameters, you can specify the location of the control handles
for the vertex. The control handle location is offset relative to the vertex, so if no location is
specified, it will be located at 0 horizontal offset and 0 vertical offset.

Lingo Dictionary

65

Example

This line adds a vertex point in the vector shape Archie between the two existing vertex points, at
the position 25 horizontal and 15 vertical:
member("Archie").addVertex(2, point(25, 15))
See also

vertexList, moveVertex(), deleteVertex(), originMode

after
See

put...after

alert
Syntax

alert message
Description

Command; causes a system beep and displays an alert dialog box containing the string specified
by message and an OK button. This command is useful for providing error messages of up to
255 characters in your movie.
The message must be a string. If you want to include a number variable in an alert, use the
function to convert the variable to a string.

string

Examples

The following statement produces an alert stating that there is no CD-ROM drive connected:
alert "There is no CD-ROM drive connected."

This statement produces an alert stating that a file was not found:
alert "The file" && QUOTE & filename & QUOTE && "was not found."
See also

string(), alertHook

alertHook
Syntax

the alertHook
Description

System property; specifies a parent script that contains the on alertHook handler. Use
alertHook to control the display of alerts about file errors or Lingo script errors. When an error
occurs and a parent script is assigned to alertHook, Director runs the on alertHook handler in
the parent script.
Although it is possible to place on alertHook handlers in movie scripts, it is strongly
recommended that you place an on alertHook handler in a behavior or parent script to avoid
unintentionally calling the handler from a wide variety of locations and creating confusion about
where the error occurred.

66

Chapter 3

Because the on alertHook handler runs when an error occurs, avoid using the on alertHook
handler for Lingo that isnt involved in handling an error. For example, the on alertHook
handler is a bad location for a go to movie statement.
The on alertHook handler is passed an instance argument, two string arguments that describe
the error, and an optional argument specifying an additional event that invokes the handler.

Lingo Dictionary

67

The fourth argument can have 1 of these 4 values:

#alert

#script

- causes the handler to be triggered by the alert command.

#movie - causes the handler to be triggered by a file not found error while perforoming a go to
movie command.

- causes the handler to be triggered by a script error.

#safeplayer

- causes the handler to be triggered by a check of the safePlayer property.

Depending on the Lingo within it, the on

another way.

alertHook

handler can ignore the error or report it in

Example

The following statement specifies that the parent script Alert is the script that determines whether
to display alerts when an error occurs. If an error occurs, Lingo assigns the error and message
strings to the field cast member Output and returns the value 1.
on prepareMovie
the alertHook = script "Alert"
end
-- parent script "Alert"
on alertHook me, err, msg
member("Output").text = err && msg
return 1
end
See also

safePlayer

alignment
Syntax

member(whichCastMember).alignment
the alignment of member whichCastMember
Description

Cast member property; determines the alignment used to display characters within the specified
cast member. This property appears only to field and text cast members containing characters, if
only a space.
For field cast members, the value of the property is a string consisting of one of the following: left,
center, or right.
For text cast members, the value of the property is a symbol consisting of one of the following:
#left, #center, #right, or #full.
The parameter whichCastMember can be either a cast name or a cast number.
This property can be tested and set. For text cast members, the property can be set on a perparagraph basis.
Examples

This statement sets the variable named characterAlign to the current alignment setting for the
field cast member Rokujo Speaks:
Dot syntax:
characterAlign = member("Rokujo Speaks").alignment

68

Chapter 3

Verbose syntax:
set characterAlign = the alignment of member "Rokujo Speaks"

This repeat loop consecutively sets the alignment of the field cast member Rove to left, center,
and then right.
Dot syntax:
repeat with i = 1 to 3
member("Rove").alignment = ("left center right").word[i]
end repeat

Verbose syntax:
repeat with i = 1 to 3
set the alignment of member "Rove" to word i of "left center right"
end repeat
See also

text, font, lineHeight (cast member property), fontSize, fontStyle, &

(concatenator), && (concatenator)

allowCustomCaching
Syntax

the allowCustomCaching
Description

Movie property; will contain information regarding a private cache in future versions of Director.
This property defaults to TRUE, and can be tested and set.
See also

allowGraphicMenu, allowSaveLocal, allowTransportControl, allowVolumeControl,

allowZooming

allowGraphicMenu
Syntax

the allowGraphicMenu
Description

Movie property; sets the availability of the graphic controls in the context menu when playing the
movie in a Shockwave environment.
Set this property to FALSE if you would rather have a text menu displayed than the graphic
context menu.
This property defaults to TRUE, and can be tested and set.
Example

the allowGraphicMenu = 0
See also

allowSaveLocal, allowTransportControl, allowVolumeControl, allowZooming

Lingo Dictionary

69

allowSaveLocal
Syntax

the allowSaveLocal
Description

Movie property; sets the availability of the Save control in the context menu when playing the
movie in a Shockwave environment.
This property is provided to allow for enhancements in future versions of Shockwave.
This property defaults to TRUE, and can be tested and set.
See also

allowGraphicMenu, allowTransportControl, allowVolumeControl, allowZooming

allowTransportControl
Syntax

the allowTransportControl
Description

Movie property; This property is provided to allow for enhancements in future versions
of Shockwave.
This property defaults to TRUE, and can be tested and set.
See also

allowGraphicMenu, allowSaveLocal, allowVolumeControl, allowZooming

allowVolumeControl
Syntax

the allowVolumeControl
Description

Movie property; sets the availability of the volume control in the context menu when playing the
movie in a Shockwave environment.
When set to TRUE one or the other volume control is active, and is disabled when the property is
set to FALSE.
This property defaults to TRUE, and can be tested and set.
See also

allowGraphicMenu, allowSaveLocal, allowTransportControl, allowZooming

70

Chapter 3

allowZooming
Syntax

the allowZooming
Description

Movie property; determines whether the movie may be stretched or zoomed by the user when
playing back in Shockwave and ShockMachine. Defaults to TRUE. This property can be tested and
set. Set this property to FALSE to prevent users from changing the size of the movie in browsers
and ShockMachine.
See also

allowGraphicMenu, allowSaveLocal, allowTransportControl, allowVolumeControl

alphaThreshold
Syntax

member(whichMember).alphaThreshold
the alphaThreshold of member whichMember
Description

Bitmap cast member property; governs how the bitmaps alpha channel affects hit detection. This
property is a value from 0 to 255, that exactly matches alpha values in the alpha channel for a 32bit bitmap image.
For a given alphaThreshold setting, Director detects a mouse click if the pixel value of the alpha
map at that point is equal to or greater than the threshold. Setting the alphaThreshold to 0
makes all pixels opaque to hit detection regardless of the contents of the alpha channel.
See also

useAlpha

ambient
Syntax

member(whichCastmember).shader(whichShader).ambient
member(whichCastmember).model(whichModel).shader.ambient
member(whichCastmember).model(whichModel).shaderList{[index]}.\
ambient
Description

3D #standard shader property; indicates how much of each color component of the ambient
light in the cast member is reflected by the shader.
For example, if the color of the ambient light is rgb(255, 255, 255) and the value of the
ambient property of the shader is rgb(255, 0, 0), the shader will reflect all of the red
component of the light that the shaders colors can reflect. However, it will reflect none of the
blue and green components of the light, regardless of the colors of the shader. In this case, if there
are no other lights in the scene, the blue and green colors of the shader will reflect no light, and
will appear black.
The default value of this property is rgb(63,63,63).

Lingo Dictionary

71

Example

This statement sets the ambient property of the model named Chair to rgb(255, 255, 0).
Chair will fully reflect the red and green components of the ambient light in the scene and
completely ignore its blue component.
member("Room").model("Chair").shader.ambient = rgb(255, 0, 0)
See also

ambientColor, newLight, type (light), diffuse, specular (shader)

ambientColor
Syntax

member(whichCastmember).ambientColor
Description

3D cast member property; indicates the RGB color of the default ambient light of the
cast member.
The default value for this property is rgb(0, 0, 0). This adds no light to the scene.
Example

This statement sets the ambientColor property of the cast member named Room to rgb(255, 0,
0). The default ambient light of the cast member will be red. This property can also be set in the
Property inspector.
member("Room").ambientColor = rgb(255, 0, 0)
See also

directionalColor, directionalPreset, ambient

ancestor
Syntax

property {optionalProperties} ancestor

Description

Object property; allows child objects and behaviors to use handlers that are not contained within
the parent script or behavior.
The ancestor property is typically used with two or more parent scripts. You can use this
property when you want child objects and behaviors to share certain behaviors that are inherited
from an ancestor, while differing in other behaviors that are inherited from the parents.
For child objects, the ancestor property is usually assigned in the on new handler within the
parent script. Sending a message to a child object that does not have a defined handler forwards
that message to the script defined by the ancestor property.
If a behavior has an ancestor, the ancestor receives mouse events such as mouseDown and
mouseWithin.

The ancestor property lets you change behaviors and properties for a large group of objects with
a single command.

72

Chapter 3

The ancestor script can contain independent property variables that can be obtained by child
objects. To refer to property variables within the ancestor script, you must use this syntax:
me.propertyVariable = value

For example, this statement changes the property variable legCount within an ancestor script to 4:
me.legCount = 4

Use the syntax the variableName of scriptName to access property variables that are not
contained within the current object. This statement allows the variable myLegCount within the
child object to access the property variable legCount within the ancestor script:
set myLegCount to the legCount of me
Example

Each of the following scripts is a cast member. The ancestor script Animal and the parent scripts
Dog and Man interact with one another to define objects.
The first script, Dog, sets the property variable breed to Mutt, sets the ancestor of Dog to the
Animal script, and sets the legCount variable that is stored in the ancestor script to 4:
property breed, ancestor
on new me
set breed = "Mutt"
set the ancestor of me to new(script "Animal")
set the legCount of me to 4
return me
end

The second script, Man, sets the property variable race to Caucasian, sets the ancestor of Man
to the Animal script, and sets the legCount variable that is stored in the ancestor script to 2:
property race, ancestor
on new me
set race to "Caucasian"
set the ancestor of me to new(script "Animal")
set the legCount of me to 2
return me
end
See also

new(), me, property

and
Syntax

logicalExpression1 and logicalExpression2

Description

Logical operator; determines whether both logicalExpression1 and logicalExpression2 are

TRUE (1), or whether either or both expressions are FALSE (0).
The precedence level of this logical operator is 4.
Examples

This statement determines whether both logical expressions are TRUE and displays the result in the
Message window:
put 1 < 2 and 2 < 3

Lingo Dictionary

73

The result is 1, which is the numerical equivalent of TRUE.

The first logical expression in the following statement is TRUE; and the second logical expression is
Because both logical expressions are not TRUE, the logical operator displays the result 0,
which is the numerical equivalent of FALSE.

FALSE.

put 1 < 2 and 2 < 1

-- 0
See also

not, or

angle
Syntax

member(whichCastmember).modelResource(whichModelResource).\
emitter.angle
Description

3D emitter property; describes the area into which the particles of a particle system are emitted. A
particle system is a model resource whose type is #particle.
The primary direction of particle emission is the vector set by the emitters direction property.
However, the direction of emission of a given particle will deviate from that vector by a random
angle between 0 and the value of the emitters angle property.
The effective range of this property is 0.0 to 180.0. The default value is 180.0.
Example

This statement sets the angle of emission of the model resource named mrFount to 1, which
causes the emitted particles to form a thin line.
member("fountain").modelResource("mrFount").emitter.angle = 1
See also

emitter, direction

angleBetween
Syntax

vector1.angleBetween(vector2)
Description

3D vector method; returns the angle between two vectors, in degrees.

Example

In this example, pos1 is a vector on the X axis and pos2 is a vector on the Y axis. The angle
between these two vectors is 90. The value returned by pos1.angleBetween(pos2) is 90.0000.
pos1 = vector(100, 0, 0)
pos2 = vector(0, 100, 0)
put pos1.angleBetween(pos2)
-- 90.0000
See also

dot(), dotProduct()

74

Chapter 3

animationEnabled
Syntax

member(whichCastmember).animationEnabled
Description

3D cast member property; indicates whether motions will be executed (TRUE) or ignored (FALSE).
This property can also be set in the Property inspector.
The default value for this property is TRUE.
Example

This statement disables animation for the cast member named Scene.
member("Scene").animationEnabled = FALSE

antiAlias
Syntax

member(whichMember).antiAlias
sprite(whichVectorSprite).antiAlias
Description

Cast member property; controls whether a text, Vector shape, or Flash cast member is rendered
using anti-aliasing to produce high-quality rendering, but possibly slower playback of the movie.
The antiAlias property is TRUE by default.
For vector shapes, TRUE is the equivalent of the #high quality setting for a Flash asset, and FALSE
is the equivalent of #low.
The antiAlias property may also be used as a sprite property only for Vector shape sprites.
This property can be tested and set.
Example

This behavior checks the color depth of the computer on which the movie is playing. If the color
depth is set to 8 bits or less (256 colors), the script sets the antiAlias property of the sprite to FALSE.
property spriteNum
on beginsprite me
if the colorDepth <= 8 then
sprite(spriteNum).antiAlias = FALSE
end if
end
See also

antiAliasThreshold, quality

antiAliasingEnabled
Syntax

sprite(whichSprite).antiAliasingEnabled
Type

3D sprite property.

Lingo Dictionary

75

Description

This property indicates whether the 3D world in the sprite whichSprite is anti-aliased. It can be
tested and set. The default value is FALSE, indicating that anti-aliasing is off. If the
antiAliasingEnabled property is set to TRUE and the 3D renderer changes to a renderer that
does not support anti-aliasing, the property is set to FALSE. The value of this property is not saved
when the movie is saved.
Anti-aliased sprites use more processor power and memory than sprites that are not anti-aliased.
Temporarily turning off anti-aliasing can improve the performance of animations and user
interaction.
Example

This Lingo checks whether the currently running 3D renderer for sprite 2 supports anti-aliasing
with the antiAliasingSupported property. If anti-aliasing is supported, the second statement
turns on anti-aliasing for the sprite with the antiAliasingEnabled property.
if sprite(2).antiAliasingSupported = TRUE then
sprite(2).antiAliasingEnabled = TRUE
end if
See Also

antiAliasingSupported, renderer, rendererDeviceList

antiAliasingSupported
Syntax

sprite(whichSprite).antiAliasingSupported
Type

3D sprite property.
Description

This property indicates whether anti-aliasing is supported by the current 3D renderer. This
property can be tested but not set. This property returns either TRUE or FALSE.
Example

This Lingo checks whether the currently running 3D renderer for sprite 3 supports anti-aliasing.
If anti-aliasing is supported, the second statement turns on anti-aliasing for the sprite with the
antiAliasingEnabled property.
if sprite(3).antiAliasingSupported = TRUE then
sprite(3).antiAliasingEnabled = TRUE
end if
See Also

antiAliasingEnabled, renderer, rendererDeviceList

76

Chapter 3

antiAliasThreshold
Syntax

member(whichTextMember).antiAliasThreshold
Description

Text cast member property; this setting controls the point size at which automatic anti-aliasing
takes place in a text cast member. This has an effect only when the antiAlias property of the text
cast member is set to TRUE.
The setting itself is an integer indicating the font point size at which the anti-alias takes place.
This property defaults to 14 points.
See also

antiAlias

append
Syntax

list.append(value)
append list, value
Description

List command; for linear lists only, adds the specified value to the end of a linear list. This differs
from the add command, which adds a value to a sorted list according to the lists order.
This command returns a script error when used with a property list.
Example

This statement adds the value 2 at the end of the sorted list named bids, which contains [1, 3, 4],
even though this placement does not match the lists sorted order:
set bids = [1, 3, 4]
bids.append(2)

The resulting value of bids is [1, 3, 4, 2].

See also
add (3D texture), sort

applicationPath
Syntax

the applicationPath
Description

System property; determines the path or location of the folder containing the running copy of the
Director application during authoring, or the folder containing the projector during run time.
The property value is a string.
If you use the applicationPath followed by & and a path to a subfolder, enclose the entire
expression in parentheses so that Lingo parses the expression as one phrase.
The Director player for Java doesnt support this property, nor does Shockwave.
This property can be tested but not set.

Lingo Dictionary

77

Examples

This statement displays the pathname for the folder that contains the Director application.
put the applicationPath
--"Z:\Program Files\Macromedia\Director"

This statement opens the movie Sunset Boulevard in a window (on a Windows machine):
open window (the applicationPath & "\Film Noir\Sunset Boulevard")
See also

@ (pathname), moviePath

appMinimize
Syntax

appMinimize
Description

Command; on Windows, appMinimize causes a projector to minimize to the Windows Task Bar.
On the Macintosh, appMinimize causes a projector to be hidden. Once hidden, the projector
may be re-opened from the Macintosh application menu.
This is useful for projectors and MIAWs that play back without a title bar.
See also

windowType

atan()
Syntax

(number).atan
atan (number)
Description

Math function; calculates the arctangent, which is the angle whose tangent is a specified number.
The result is a value in radians between pi/2 and +pi/2.
Examples

This statement displays the arctangent of 1:

(1).atan

The result, to four decimal places, is 0.7854, or approximately pi/4.

Note that most trigonometric functions use radians, so you may want to convert from degrees
to radians.
This handler lets you convert between degrees and radians:
on DegreesToRads degreeValue
return degreeValue * PI/180
end

The handler displays the conversion of 30 degrees to radians in the Message window:
put DegreesToRads(30)
-- 0.5236

78

Chapter 3

See also

cos(), PI, sin()

attenuation
Syntax

member(whichCastMember).light(whichLight).attenuation
Description

3D light property; indicates the constant, linear, and quadratic attenuation factors for spotlights
and point lights.
The default value for this property is vector(1.0, 0.0, 0.0).
Example

This statement sets the attenuation property of the light named HouseLight to the vector (.5, 0,
0), darkening it slightly.
member("3d world").light("HouseLight").attenuation = \
vector(.5, 0, 0)
See also

color (light)

attributeName
Syntax

XMLnode.attributeName[ attributeNumber ]
Description

XML property; returns the name of the specified child node of a parsed XML document.
Example
Beginning with the following XML:
<?xml version="1.0"?>
<e1>
<tagName attr1="val1" attr2="val2"/>
<e2>element 2</e2>
<e3>element 3</e3>
here is some text
</e1>

This Lingo returns the name of the first attribute of the tag called tagName:
put gParserObject.child[1].child[1].attributeName[1]
-- "attr1"
See also

attributeValue

Lingo Dictionary

79

attributeValue
Syntax

XMLnode.attributeValue[ attributeNameOrNumber ]
Description

XML property; returns the value of the specified child node of a parsed XML document.
Example

Beginning with the following XML:

<?xml version="1.0"?>
<e1>
<tagName attr1="val1" attr2="val2"/>
<e2>element 2</e2>
<e3>element 3</e3>
here is some text
</e1>

This Lingo returns the value of the first attribute of the tag called tagName:
put gParserObject.child[1].child[1].attributeValue[1]
-- "val1"
See also

attributeName

audio (RealMedia)
Syntax

sprite(whichSprite).audio
member(whichCastmember).audio
Description

RealMedia sprite or cast member property; allows you to play (TRUE) or mute (FALSE) the audio
in the RealMedia stream. The default setting for this property is TRUE (1). Integer values other
than 1 or 0 are treated as TRUE (1). Setting this property has no effect if the
realPlayerNativeAudio() function is set to TRUE.
If the audio property is set to FALSE when a RealMedia cast member starts playing, a sound
channel is still allocated, which allows you to toggle the sound on and off during playback.
There may be some latency involved in setting this property, which means there may be a slight
delay before the sound toggles on or off.
Examples

The following examples show that the audio properties for sprite 2 and the cast member Real is
set to TRUE, which means that the audio portion of the RealMedia stream will be played.
put sprite(2).audio
-- 1
put member("Real").audio
-- 1

80

Chapter 3

The following Lingo sets the audio property for sprite 2 and the cast member Real to FALSE, which
means that the audio portion of the RealMedia stream will not be played when the movie is played.
sprite(2).audio = FALSE
member("Real").audio = FALSE
See also

soundChannel (RealMedia), video (RealMedia), sound

auto
Syntax

member(whichCastmember).model(whichModel).lod.auto
Description

3D lod modifier property; allows the modifier to manage the reduction of detail in the model as
the distance between the model and the camera changes.
The setting of the modifiers bias property determines how aggressively the modifier removes
detail from the model when the auto property is set to TRUE.
The modifier updates its level property as it adjusts the models level of detail. Setting the level
property has no effect unless the auto property is set to FALSE.
The #lod modifier can only be added to models created outside of Director in 3D modeling
programs. The value of the type property of the model resources used by these models is
#fromFile. The modifier cannot be added to primitives created within Director.
Example

This statement sets the auto property of the lod modifier of the model named Spaceship to TRUE.
The modifier will automatically set the models level of detail.
member("3D World").model("Spaceship").lod.auto = TRUE
See also

lod (modifier), bias, level

autoblend
Syntax

member(whichCastmember).model(whichModel).\
keyframePlayer.autoblend
member(whichCastmember).model(whichModel).bonesPlayer.autoblend
Description

3D keyframePlayer and bonesPlayer modifier property; indicates whether the modifier creates
a linear transition to the currently playing motion from the motion that preceded it (TRUE) or
not (FALSE). If autoBlend is TRUE, the length of the transition is set by the blendTime property
of the modifier. If autoBlend is FALSE, the transition is controlled by the blendFactor property
of the modifier and blendTime is ignored.
Motion blending is completely disabled when blendTime is set to 0 and autoBlend is set to TRUE.
The default value of this property is TRUE.

Lingo Dictionary

81

Example

This statement turns autoblend off for the model named Alien3. The models blendFactor
setting will be used for blending successive motions in the playlist.
member("newaliens").model("Alien3").keyframePlayer.\
autoblend = FALSE
See also

blendFactor, blendTime

autoCameraPosition
Syntax

member(whichTextCastmember).autoCameraPosition
Description

3D camera property; indicates whether the camera of the 3D text cast member is automatically
positioned to show all of the text (TRUE) or not (FALSE). This is useful when changing the text,
font, fontsize, and other properties of the cast member.
This property is not valid with other types of 3D cast members.
Example

This statement sets the autoCameraPosition property of the cast member named Headline to
FALSE. When the cast member is displayed in 3D mode, the camera will not be positioned
automatically.
member("Headline").autoCameraPosition = FALSE
See also

displayMode

autoMask
Syntax

member(whichCursorCastMember).autoMask
the autoMask of member whichCastMember
Description

Cast member property; specifies whether the white pixels in the animated color cursor cast
member whichCursorCastMember are transparent, allowing the background to show through
(TRUE, default), or opaque (FALSE).
Example

In this script, when the custom animated cursor stored in cast member 5 enters the sprite, the
automask is turned on so that the background of the sprite will show through the white pixels.
When the cursor leaves the sprite, the automask is turned off.
Using dot syntax, the script is written as:
on mouseEnter
member 5.autoMask = TRUE
end
on mouseLeave
member 5.autoMask = FALSE
end

82

Chapter 3

Using traditional Lingo syntax, the script is written as:

on mouseEnter
set the autoMask of member 5 = TRUE
end
on mouseLeave
set the autoMask of member 5 = FALSE
end

autoTab
Syntax

member(whichCastMember).autoTab
the autoTab of member whichCastMember
Description

Cast member property; determines the effect that pressing the Tab key has on the editable field or
text cast member specified by whichCastMember. The property can be made active (TRUE) or
inactive (FALSE). Tabbing order depends on sprite number order, not position on the Stage.
This property is always TRUE in an applet created with the Save as Java feature of Director.
Example

This statement causes the cast member Comments to automatically advance the insertion point
to the next editable field or text sprite after the user presses Tab.
Dot syntax:
member ("Comments").autotab = TRUE

Verbose Lingo syntax:

set the autoTab of member "Comments" to TRUE

axisAngle
Syntax

member(whichCastmember).model(whichModel).transform.axisAngle
member(whichCastmember).camera(whichCamera).transform.axisAngle
member(whichCastmember).light(whichLight).transform.axisAngle
member(whichCastmember).group(whichGroup).transform.axisAngle
transformReference.axisAngle
Description

3D transform property; describes the transforms rotation as an axis/angle pair.

The axisAngle property is a linear list containing a vector (the axis) and a float (the angle).
The vector is the axis around which the transform is rotated. The float is the amount, in degrees,
of rotation.
The default value of this property is [vector(

1.0000, 0.0000, 0.0000 ), 0.0000].

Examples

This statement shows the rotation of the model named Mailbox as an axisAngle. The model is
rotated 145.5 degrees counterclockwise about the y axis.
put member("Yard").model("Mailbox").transform.axisAngle
-- [vector( 0.0000, 1.0000, 0.0000 ), -145.5000]

Lingo Dictionary

83

See also

rotation (transform)

back
Syntax

member(whichCastmember).modelResource(whichModelResource).back
Description

3D #box model resource property; indicates whether the side of the box intersected by its +Z axis
is sealed (TRUE) or open (FALSE).
The default value for this property is TRUE.
Example

This statement sets the back property of the model resource named Crate to FALSE, meaning the
back of this box will be open.
member("3D World").modelResource("Crate").back = FALSE
See also

bottom (3D), front, top (3D), left (3D), right (3D)

backColor
Syntax

member(whichCastMember).backColor = colorNumber
set the backColor of member whichCastMember to colorNumber
sprite(whichSprite).backColor
the backColor of sprite whichSprite
Description

Cast member and sprite property; sets the background color of the specified cast member or sprite
according to the color value assigned.

For cast members: it affects field or button cast member displays.

For sprites: setting the backColor of a sprite is the same as choosing the background color
from the tool palette when the sprite is selected on the Stage. For the value that Lingo sets to
last beyond the current sprite, the sprite must be a puppet. The background color applies only
to 1-bit bitmap and shape cast members.
The backColor value ranges from 0 to 255 for 8-bit color and from 0 to 15 for 4-bit color. The
numbers correspond to the index number of the background color in the current palette. (A
colors index number appears in the color palettes lower left corner when you click the color.)
You should not apply this property to bitmap cast members deeper than 1-bit, as the results are
difficult to predict.
For a movie that plays back as an applet created with the Save as Java feature of Director, specify
colors for backColor using the decimal equivalent of the 24-bit hexadecimal values used in an
HTML document.
For example, the hexadecimal value for pure red, FF0000, is equivalent to 16711680 in decimal
numbers. This statement specifies pure red as a cast members background color:
set the backColor of member = 16711680

84

Chapter 3

This property can be tested and set.

Note: It is recommended that the newer bgColor property be used instead of the backColor property.

Examples

This statement changes the color of the characters in cast member 1 to the color in palette
entry 250.
Dot syntax:
member(1).backColor = 250

Verbose Lingo syntax:

set the backColor of member 1 to 250

The following statement sets the variable oldColor to the background color of sprite 5:
oldColor = sprite (5).backColor

The following statement randomly changes the background color of a random sprite between
sprites 11 and 13 to color number 36:
sprite(10 + random(3)).backColor = 36
See also

bgColor, color (sprite and cast member property)

backdrop
Syntax

sprite(whichSprite).camera{(index)}.backdrop[index].loc
member(whichCastmember).camera(whichCamera).backdrop[index].loc
sprite(whichSprite).camera{(index)}.backdrop[index].source
member(whichCastmember).camera(whichCamera).backdrop[index].source
sprite(whichSprite).camera{(index)}.backdrop[index].scale
member(whichCastmember).camera(whichCamera).backdrop[index].scale
sprite(whichSprite).camera{(index)}.backdrop[index].rotation
member(whichCastmember).camera(whichCamera).\
backdrop[index].rotation
sprite(whichSprite).camera{(index)}.backdrop[index].regPoint
member(whichCastmember).camera(whichCamera).\
backdrop[index].regPoint
sprite(whichSprite).camera{(index)}.backdrop[index].blend
member(whichCastmember).camera(whichCamera).backdrop[index].blend
sprite(whichSprite).camera{(index)}.backdrop.count
member(whichCastmember).camera(whichCamera).backdrop.count
Description

3D camera property; a 2D image that is rendered on the cameras projection plane. All models in
the cameras view appear in front of the backdrop.
Backdrops have the following properties:
Note: These properties can also be used to get, set, and manipulate overlays. See the individual property entries for
detailed information.

loc (backdrop and overlay) indicates the 2D location of the backdrop, as measured from

the upper

left corner of the sprite.

source

indicates the texture used by the backdrop.

Lingo Dictionary

85

is the number by which the height and width of the texture are
multiplied to determine the dimensions of the backdrop.

scale (backdrop and overlay)

rotation (backdrop and overlay) is the amount by which the backdrop is rotated about its regPoint.
regPoint (3D)
blend (3D)
count

indicates the registration point of the backdrop.

indicates the opacity of the backdrop.

indicates the number of items in the cameras list of backdrops.

Use the following commands to create and remove backdrops:

addBackdrop creates a backdrop from a texture and adds it to the end of the cameras list of backdrops.

creates a backdrop from a texture and adds it to the cameras list of backdrops at a
specific index position.

insertBackdrop

removeBackdrop

deletes the backdrop.

See also

overlay

backgroundColor
Syntax

member(whichVectorMember).backgroundColor
the backgroundColor of member whichVectorMember
Description

Vector shape cast member property; sets the background color of the specified cast member or
sprite to the RGB color value assigned.
This property can be both tested and set.
Example

member("Archie").backgroundColor= rgb(255,255,255)
See also

bgColor

BACKSPACE
Syntax

BACKSPACE
Description

Constant; represents the Backspace key. This key is labeled Backspace in Windows and Delete on
the Macintosh.
Example

This on keyDown handler checks whether the Backspace key was pressed and, if it was, calls the
handler clearEntry:
on keyDown
if the key = BACKSPACE then clearEntry
stopEvent
end keyDown

86

Chapter 3

beep
Syntax

beep {numberOfTimes}
Description

Command; causes the computers speaker to beep the number of times specified by
numberOfTimes. If numberOfTimes is missing, the beep occurs once.

In Windows, the beep is the sound assigned in the Sounds Properties dialog box.
For the Macintosh, the beep is the sound selected from Alert Sounds on the Sound control
panel. If the volume on the Sound control panel is set to 0, the menu bar flashes instead.
Example

This statement causes two beeps if the Answer field is empty:

if field "Answer" = EMPTY then beep 2

beepOn
Syntax

the beepOn
Description

Movie property; determines whether the computer automatically beeps when the user clicks on
anything except an active sprite (TRUE), or not (FALSE, default).
Scripts that set beepOn should be placed in frame or movie scripts.
This property can be tested and set.
Examples

This statement sets beepOn to TRUE:

the beepOn = TRUE

This statement sets beepOn to the opposite of its current setting:

the beepOn = not the beepOn

before
See

put...before

beginRecording
Syntax

beginRecording
Description

Keyword; starts a Score generation session. Only one update session in a movie can be active at a time.
Every beginRecording keyword must be matched by an endRecording keyword that ends the
Score generation session.

Lingo Dictionary

87

Example

When used in the following handler, the beginRecording keyword begins a Score generation
session that animates the cast member Ball by assigning the cast member to sprite channel 20 and
then moving the sprite horizontally and vertically over a series of frames. The number of frames is
determined by the argument numberOfFrames.
on animBall numberOfFrames
beginRecording
horizontal = 0
vertical = 100
repeat with i = 1 to numberOfFrames
go to frame i
sprite(20).member = member "Ball"
sprite(20).locH = horizontal
sprite(20).locV = vertical
sprite(20).type = 1
sprite(20).foreColor = 255
horizontal = horizontal + 3
vertical = vertical + 2
updateFrame
end repeat
endRecording
end
See also

endRecording, updateFrame, scriptNum, tweened

on beginSprite
Syntax

on beginSprite
statement(s)
end
Description

System message and event handler; contains statements that run when the playhead moves to a
frame that contains a sprite that was not previously encountered. Like endSprite, this event is
generated only one time, even if the playhead loops on a frame, since the trigger is a sprite not
previously encountered by the playhead. The event is generated before prepareFrame.
Director creates instances of any behavior scripts attached to the sprite when the beginSprite
message is sent.
The object reference me is passed to this event if it is used in a behavior. The message is sent to
behaviors and frame scripts.
If a sprite begins in the first frame that plays in the movie, the beginSprite message is sent after
the prepareMovie message but before the prepareFrame and startMovie messages.
Note: Be aware that some sprite properties, such as the rect sprite property, may not be accessible in a
beginSprite handler. This is because the property needs to be calculated, which is not done until the sprite is drawn.

The go, play, and updateStage commands are disabled in an on

88

Chapter 3

beginSprite

handler.

Example

This handler plays the sound cast member Stevie Wonder when the sprite begins:
on beginSprite me
puppetSound "Stevie Wonder"
end
See also

on endSprite, on prepareFrame, scriptInstanceList

bevelDepth
Syntax

member(whichTextCastmember).bevelDepth
member(which3DCastmember).modelResource(whichModelResource).\
bevelDepth
Description

3D text property; indicates the degree of beveling on the 3D text.

For text cast members, this property has no effect unless the members displayMode property is
set to #mode3D and its bevelType property is set to #miter or #round.
For extruded text in a 3D cast member, this property has no effect unless the model resources
property is set to #miter or #round.

bevelType

The range of this property is 0.0 to 10.0, and the default setting is 10.0.
Example

In this example, the cast member named Logo is a text cast member. This statement sets the
bevelDepth of logo to 5.5. When logo is displayed in 3D mode, if its bevelType property is set
to #miter or #round, the edges of its letters will exhibit dramatic beveling.
member("Logo").bevelDepth = 5.5

In this example, the model resource of the model named Slogan is extruded text. This statement
sets the bevelDepth of Slogans model resource to 5. If the bevelType property of Slogan is set to
#miter or #round, the edges of its letters will exhibit dramatic beveling.
member("scene").model("Slogan").resource.bevelDepth = 5
See also

bevelType, extrude3D, displayMode

bevelType
Syntax

member(whichTextCastmember).bevelType
member(which3DCastmember).modelResource(whichModelResource).\
bevelType
Description

3D text property; indicates the style of beveling applied to the 3D text.

For text cast members, this is a member property. For extruded text in a 3D cast member, this is a
model resource property.

Lingo Dictionary

89

The bevelType property has the following possible values:

#none
#miter

(the default)

#round

Example

In this example, the cast member named Logo is a text cast member. This statement sets the
bevelType of Logo to #round.
member("logo").beveltype = #round

In this example, the model resource of the model named Slogan is extruded text. This statement
sets the bevelType of Slogans model resource to #miter.
member("scene").model("Slogan").resource.bevelType = #miter
See also

bevelDepth, extrude3D, displayMode

bgColor
Syntax

sprite(whichSpriteNumber).bgColor
the bgColor of sprite whichSpriteNumber
the bgColor of the stage
(the stage).bgColor
member(which3dMember).bgcolor
Description

Sprite property, system property, and 3D cast member property; determines the background color
of the sprite specified by whichSprite, the color of the Stage, or the background color of the 3D
cast member. Setting the bgColor sprite property is equivalent to choosing the background color
from the Tools window when the sprite is selected on the Stage. Setting the bgColor property for
the Stage is equivalent to setting the color in the Movie Properties dialog box.
The sprite property has the equivalent functionality of the backColor sprite property, but the
color value returned is a color object of whatever type has been set for that sprite.
This property can be tested and set.
Example

This example sets the color of the Stage to an RGB value.

Dot syntax:
(the stage).bgColor = rgb(255, 153, 0)

Verbose Lingo syntax:

set the bgColor of the stage = rgb(255, 153, 0)
See also

color(), backColor, backgroundColor, stageColor

90

Chapter 3

bias
Syntax

member(whichCastmember).model(whichModel).lod.bias
Description

3D lod modifier property; indicates how aggressively the modifier removes detail from the model
when its auto property is set to TRUE. This property has no effect when the modifiers auto
property is set to FALSE.
The range for this property is from 0.0 (removes all polygons) to +100.0 (removes no polygons).
The default setting is 100.0.
The #lod modifier can only be added to models created outside of Director in 3D modeling
programs. The value of the type property of the model resources used by these models is
#fromFile. The modifier cannot be added to primitives created within Director.
Example

This statement sets the bias property of the lod modifier of the model named Spaceship to 10. If
the lod modifiers auto property is set to TRUE, the modifier will very aggressively lower the level
of detail of Spaceship as it moves away from the camera.
member("3D World").model("Spaceship").lod.bias = 10
See also

lod (modifier), auto, level

bitAnd()
Syntax

bitAnd(integer1, integer2)
Description

Function; converts the two specified integers to 32-bit binary numbers and returns a binary
number whose digits are 1s in the positions where both numbers had a 1, and 0s in every other
position. The result is the new binary number, which Lingo displays as a base 10 integer.
Integer

Binary number (abbreviated)

00110

00111

Result

00110

Example

This statement compares the binary versions of the integers 6 and 7 and returns the result as an
integer:
put bitAnd(6, 7)
-- 6
See also

bitNot(), bitOr(), bitXor()

Lingo Dictionary

91

bitmapSizes
Syntax

member(whichFontMember).bitmapSizes
the bitmapSizes of member whichFontMember
Description

Font cast member property; returns a list of the bitmap point sizes that were included when the
font cast member was created.
Example

This statement displays the bitmap point sizes that were included when cast member 11 was created:
put member(11).bitmapSizes
-- [12, 14, 18]
See also

recordFont, characterSet, originalFont

bitNot()
Syntax

(integer).bitNot
bitNot(integer)
Description

Function; converts the specified integer to a 32-bit binary number and reverses the value of each
binary digit, replacing 1s with 0s and 0s with 1s. The result is the new binary number, which
Lingo displays as a base 10 integer.
Integer

Binary number

00000000000000000000000000000001

Result

-2

11111111111111111111111111111110

Example

This statement inverts the binary representation of the integer 1 and returns a new number.
put (1).bitNot
-- -2
See also

bitAnd(), bitOr(), bitXor()

92

Chapter 3

bitOr()
Syntax

bitOr(integer1, integer2)
Description

Function; converts the two specified integers to 32-bit binary numbers and returns a binary
number whose digits are 1s in the positions where either number had a 1, and 0s in every other
position. The result is the new binary number, which Lingo displays as a base 10 integer.
Integer

Binary number (abbreviated)

0101

0110

Result

0111

Example

This statement compares the 32-bit binary versions of 5 and 6 and returns the result as an integer:
put bitOr(5, 6)
-- 7
See also

bitNot(), bitAnd(), bitXor()

bitRate
Syntax

member(whichCastMember).bitRate
the bitRate of member whichCastMember
Description

Shockwave Audio (SWA) cast member property; returns the bit rate, in kilobits per second
(Kbps), of the specified SWA cast member that has been preloaded from the server.
The bitRate member property returns 0 until streaming begins.
Example

This behavior outputs the bit rate of an SWA cast member when the sprite is first encountered.
Dot syntax:
property spriteNum
on beginSprite me
memName = sprite(spriteNum).member.name
put "The bitRate of member"&&memName&&"is"&&member(memName).bitRate
end

Lingo Dictionary

93

Verbose syntax:
property spriteNum
on beginSprite me
memName = sprite(spriteNum).member.name
put "The bitRate of member"&&memName&&"is"&&member(memName).bitRate
end

bitsPerSample
Syntax

member(whichCastMember).bitsPerSample
the bitsPerSample of member whichCastMember
Description

Shockwave Audio (SWA) cast member property; indicates the bit depth of the original file that
has been encoded for Shockwave Audio (SWA). This property is available only after the SWA
sound begins playing or after the file has been preloaded using the preLoadBuffer command.
This property can be tested but not set.
Example

This statement assigns the original bit rate of the file used in SWA streaming cast member Paul
Robeson to the field cast member How Deep.
Dot syntax:
put member "Paul Robeson".bitsPerSample into member "How Deep"

Verbose syntax:
put the bitsPerSample of member "Paul Robeson" into member "How Deep"

bitXor()
Syntax

bitXor(integer1, integer2)
Description

Function; converts the two specified integers to 32-bit binary numbers and returns a binary
number whose digits are 1s in the positions where the given numbers digits do not match, and
0s in the positions where the digits are the same. The result is the new binary number, which
Lingo displays as a base 10 integer.
Integer

Binary number (abbreviated)

0101

0110

Result

94

Chapter 3

0011

Example

This statement compares the 32-bit binary versions of 5 and 6 and returns the result as an integer:
put bitXor(5, 6)
-- 3
See also

bitNot(), bitOr(), bitAnd()

blend
Syntax

sprite(whichSprite).blend
the blend of sprite whichSprite
Description

Sprite property; sets or determines a sprites blend value, from 0 to 100, corresponding to the
blend values in the Sprite Properties dialog box.
The possible colors depend on the colors available in the palette, regardless of the monitors
color depth.
The Director player for Java supports the blend sprite property for bitmap sprites only.
For best results, use the blend ink with images that have a color depth greater than 8-bit.
Examples

The following statement sets the blend value of sprite 3 to 40 percent.

Dot syntax:
sprite(3).blend = 40

Verbose syntax:
set the blend of sprite 3 to 40

This statement displays the blend value of sprite 3 in the Message window:
put the blend of sprite 3
See also

blendLevel

blend (3D)
Syntax

sprite(whichSprite).camera{(index)}.backdrop[index].blend
member(whichCastmember).camera(whichCamera).backdrop[index].blend
sprite(whichSprite).camera{(index)}.overlay[index].blend
member(whichCastmember).camera(whichCamera).overlay[index].blend
member(whichCastmember).shader(whichShader).blend
member(whichCastmember).model(whichModel).shader.blend
member(whichCastmember).model(whichModel).shaderList{[index]}.blend

Lingo Dictionary

95

Description

3D backdrop, overlay, and #standard shader property; indicates the opacity of the backdrop,
overlay, or shader.
Setting the blend property of a shader will have no effect unless the shaders transparent
property is set to TRUE.
The range of this property is 0 to 100, and the default value is 100.
Example

This statement sets the blend property of the shader for the model named Window to 80. If the
transparent property of Windows shader is set to TRUE, the model will be slightly transparent.
member("House").model("Window").shader.blend = 80
See also

bevelDepth, overlay, shadowPercentage, transparent

blendConstant
Syntax

member(whichCastmember).shader(whichShader).blendConstant
member(whichCastmember).model(whichModel).shader.blendConstant
member(whichCastmember).model(whichModel).shaderList{[index]}.\
blendConstant
Description

3D #standard shader property; indicates the blending ratio used for the first texture layer of
the shader.
If the shaders useDiffuseWithTexture property is set to TRUE, the texture blends with the color set
by the shaders diffuse property. If useDiffuseWithTexture is FALSE, white is used for blending.
Each of the other texture layers blends with the texture layer below it. Use the
property to control blending in those texture layers.

blendConstantList

The blendConstant property works only when the shaders blendSource property is set to
#constant. For more information, see blendSource and blendSourceList.
The range of this property is 0 to 100; the default is 50.
Example

In this example, the shader list of the model named MysteryBox contains six shaders. This
statement sets the blendConstant property of the second shader to 20. This property is affected
by the settings of the blendFunction, blendFunctionList, blendSource, and
blendSourceList properties.
member("Level2").model("MysteryBox").shaderList[2].\
blendConstant = 20
See also

blendConstantList, blendFunction, blendFunctionList, blendSource, blendSourceList,

useDiffuseWithTexture, diffuse, diffuseColor

96

Chapter 3

blendConstantList
Syntax

member(whichCastmember).shader(whichShader).blendConstantList
member(whichCastmember).model(whichModel).shader.blendConstant\
List{[index]}
member(whichCastmember).model(whichModel).shaderList{[index]}.\
blendConstantList{[index]}
Description

3D #standard shader property; indicates the ratio used for blending a texture layer of the shader
with the texture layer below it.
The shaders texture list and the blend constant list both have eight index positions. Each index
position in the blend constant list controls blending for the texture at the corresponding index
position in the texture list. You can set all index positions of the list to the same value at one time
by not specifying the optional index parameter. Use the index parameter to set the list one index
position at a time.
The blendConstantList property works only when the blendSource property of the
corresponding texture layer is set to #constant.
The range of this property is 0 to 100; the default is 50.
Example

In this example, the shader list of the model named MysteryBox contains six shaders. This
statement shows the blendConstant property of each of the textures used by the second shader.
This property is affected by the settings of the blendFunction, blendFunctionList,
blendSource, and blendSourceList properties.
put member("Level2").model("MysteryBox").shaderList[2].\
blendConstantList
-- [20.0000, 50.0000, 50.0000, 50.0000, 20.0000, 50.0000, \
50.0000, 50.0000]
See also

blendConstant, blendFunction, blendFunctionList, blendSource, blendSourceList,

useDiffuseWithTexture, diffuse, diffuseColor

blendFactor
Syntax

member(whichCastmember).model(whichModel).keyframePlayer.\
blendFactor
member(whichCastmember).model(whichModel).bonesPlayer.blendFactor
Description

3D keyframePlayer and bonesPlayer modifier property; indicates the amount by which a

motion is combined with the motion that preceded it.
The range of this property is 0 to 100, and the default value is 0.

Lingo Dictionary

97

BlendFactor is used only when the autoblend property of the modifier is set to FALSE. If
value of the blendFactor property is 100, the current motion will have none of the
characteristics of the motion that preceded it. If the value of blendFactor is 0, the current

the

motion will have all of the characteristics of the motion that preceded it and none of its own. If
the value of blendFactor is 50, the current motion will be a synthesis equally composed of its
own characteristics and those of the motion that preceded it. The value blendFactor can be
varied over time to create transitions unlike the linear transition created when the modifiers
autoblend property is set to TRUE.
Example

This statement sets the blendFactor property of model Alien3 to 50. If the modifiers
autoblend property is FALSE, each motion in the playlist of the keyframePlayer for Alien3 will
be an even mixture of itself and the motion that preceded it.
member("newaliens").model("Alien3").keyframePlayer.blendFactor = 50
See also

autoblend, keyframePlayer (modifier)

blendFunction
Syntax

member(whichCastmember).shader(whichShader).blendFunction
member(whichCastmember).model(whichModel).shader.blendFunction
member(whichCastmember).model(whichModel).shaderList{[index]}.\
blendFunction
Description

3D #standard shader property; indicates the type of blending used by the first texture layer of
the shader.
If the shaders useDiffuseWithTexture property is set to TRUE, the texture blends with the color set
by the shaders diffuse property. If useDiffuseWithTexture is FALSE, white is used for blending.
Each of the other texture layers blends with the texture layer below it. Use the
property to control blending in those texture layers.

blendFunctionList

The blendFunction property can have the following values:

#multiply

multiplies the RGB values of the texture layer by the color being used for blending

(see above).
adds the RGB values of the texture layer to the color being used for blending, and then
clamps to 255.

#add

#replace prevents
diffuse property.

the texture from being blended with the color set by the shaders

#blend combines the colors of the texture layer with the color being used for blending in the ratio
set by the blendConstant property.

The default value of this property is #multiply.

98

Chapter 3

Example

In this example, the shader list of the model named MysteryBox contains six shaders. This statement
sets the blendFunction property of the second shader to #blend. This enables the settings of the
blendSource, blendSourceList, blendConstant, and blendConstantList properties.
member("Level2").model("MysteryBox").shaderList[2].\
blendFunction = #blend
See also

blendConstant, blendConstantList, blendFunctionList, blendSource, blendSourceList,

useDiffuseWithTexture, diffuse, diffuseColor

blendFunctionList
Syntax

member(whichCastmember).shader(whichShader).\
blendFunctionList{[index]}
member(whichCastmember).model(whichModel).shader.\
blendFunctionList{[index]}
member(whichCastmember).model(whichModel).shaderList{[index]}.\
blendFunctionList{[index]}
Description

3D #standard shader property; a linear list that indicates the manner in which each texture layer
blends with the texture layer below it.
The shaders texture list and blend function list both have eight index positions. Each index
position in the blend function list controls blending for the texture at the corresponding index
position in the texture list. You can set all index positions of the list to the same value at one time
by not specifying the optional index parameter. Use the index parameter to set the list one index
position at a time.
Each index position of the blend function list can have one of the following values:
#multiply

multiplies the RGB values of the texture layer by the RGB values of the texture layer

below it.
#add adds the RGB values of the texture layer to the RGB values of the texture layer below it, and

then clamps to 255.

#replace

causes the texture to cover the texture layer below it. No blending occurs.

causes blending to be controlled by the value of the blendSource property, which allows
alpha blending.

#blend

The default value of this property is #multiply.

Example

In this example, the shaderList property of the model named MysteryBox contains six shaders. This
statement shows that the value of the fourth index position of the blendFunctionList property of
the second shader is set to #blend. Blending of the fourth texture layer of the second shader of the
model will be controlled by the settings of the blendSource, blendSourceList, blendConstant,
blendConstantList, diffuse, diffuseColor, and useDiffuseWithTexture properties.
put member("Level2").model("MysteryBox").shaderList[2].\
blendFunctionList[4]
-- #blend

Lingo Dictionary

99

See also

blendConstant, blendConstantList, blendFunction, blendSource, blendSourceList,

diffuse, diffuseColor, useDiffuseWithTexture

blendLevel
Syntax

sprite(whichSpriteNumber).blendLevel
the blendLevel of sprite whichSpriteNumber
Description

Sprite property; allows the current blending value of a sprite to be set or accessed. The possible
range of values is from 0 to 255. This differs from the Sprite Inspector, which shows values in the
range 0 to 100. The results are the same, the scales simply differ.
This property is the equivalent of the blend sprite property.
Example

sprite(3).blendlevel = 99
See also

blend

blendRange
Syntax

member(whichCastmember).modelResource(whichModelResource)\
.blendRange.start
modelResourceObjectReference.blendRange.end
member(whichCastmember).modelResource(whichModelResource)\
.blendRange.start
modelResourceObjectReference.blendRange.end
Description

3D property; when used with a model resource whose type is #particle, allows you to get or set
the start and end of the model resources blend range.
The opacity of particles in the system is interpolated linearly between blendRange.start and
over the lifetime of each particle.

blendRange.end

This propertys value must be greater than or equal to 0.0 and less than or equal to 100.0. The
default value for this property is 100.0.
Example

This statement sets the blendRange properties of model resource ThermoSystem, which is of the
type #particle.
The first line sets the start value to 100, and the second line sets the end value to 0. The effect of
this statement is that the particles of ThermoSystem are fully opaque when they first appear, and
then gradually fade to transparent during their lifetime.
member("Heater").modelResource("ThermoSystem").blendRange.\
start = 100.0
member("Heater").modelResource("ThermoSystem").blendRange.\
end = 0.0

100 Chapter 3

blendSource
Syntax

member(whichCastmember).shader(whichShader).blendSource
member(whichCastmember).model(whichModel).shader.blendSource
member(whichCastmember).model(whichModel).shaderList{[index]}.\
blendSource
Description

3D #standard shader property; indicates whether blending of the first texture layer in the
shaders texture list is based on the textures alpha information or a constant ratio.
If the shaders useDiffuseWithTexture property is set to TRUE, the texture blends with the color
set by the shaders diffuse property. If useDiffuseWithTexture is FALSE, white is used for
blending.
Each of the other texture layers blends with the texture layer below it. Use the blendSourceList
property to control blending in those texture layers.
The blendSource
#blend.

property works only when the shaders blendFunction property is set to

The possible values of this property are as follows:

causes the alpha information in the texture to determine the blend ratio of each pixel of
the texture with the color being used for blending (see above).

#alpha

#constant causes the value of the shaders blendConstant

property to be used as the blend ratio

for all the pixels of the texture.

The default value of this property is #constant.
Example

In this example, the shader list of the model named MysteryBox contains six shaders. This
statement sets the blendSource property of the first texture used by the second shader to
#constant. This enables the settings of the blendConstant and blendConstantList properties.
member("Level2").model("MysteryBox").shaderList[2].\
blendSource = #constant
See also

blendSourceList, blendFunction, blendFunctionList, blendConstant,

blendConstantList, useDiffuseWithTexture, diffuse, diffuseColor

blendSourceList
Syntax

member(whichCastmember).shader(whichShader).\
blendSourceList[index]
member(whichCastmember).model(whichModel).shader.\
blendSourceList{[index]}
member(whichCastmember).model(whichModel).\
shaderList{[index]}.blendSourceList{[index]}

Lingo Dictionary

101

Description

3D #standard shader property; indicates whether blending of a texture layer with the texture
layers below it is based on the textures alpha information or a constant ratio.
The shaders texture list and the blend source list both have eight index positions. Each index
position in the blend source list controls blending for the texture at the corresponding index
position in the texture list. You can set all index positions of the list to the same value at one time
by not specifying the optional index parameter. Use the index parameter to set the list one index
position at a time.
The blendSourceList property only works when the blendFunction property of the
corresponding texture layer is set to #blend. See blendFunction and blendFunctionList for
more information.
The possible values of this property are as follows:
causes the alpha information in the texture to determine the blend ratio of each pixel of
the texture layer with the layer below it.

#alpha

#constant causes the value of the blendConstant property of the corresponding texture layer to
be used as the blend ratio for all of the pixels of the texture layer. See blendConstant and
blendConstantList for more information.

The default value of this property is #constant.

Example

In this example, the shader list of the model MysteryBox contains six shaders. Each shader has a
texture list that contains up to eight textures. This statement shows that the blendSource
property of the fourth texture used by the second shader is set to #constant. This enables the
settings of the blendConstant, blendConstantList, and useDiffuseWithTexture properties.
member("Level2").model("MysteryBox").shaderList[2].\
blendSourceList[4] = #constant
See also

blendSource, blendFunction, blendFunctionList, blendConstant, blendConstantList,

useDiffuseWithTexture, diffuse, diffuseColor

blendTime
Syntax

member(whichCastmember).model(whichModel).keyframePlayer.\
blendTime
member(whichCastmember).model(whichModel).bonesPlayer.blendTime
Description

3D keyframePlayer and bonesPlayer modifier property; determines the duration, in

milliseconds, of the transition between motions in the playlist of the modifier for the model.
The blendTime property works in conjunction with the modifiers autoBlend property. When
autoBlend is set to TRUE, the modifier creates a linear transition to the models currently playing
motion from the motion that preceded it. The value of the blendTime property is the length of
that transition. The blendTime property is ignored if autoBlend is set to FALSE.
The default setting of this property is 500.

102 Chapter 3

Example

This statement sets the length of the transition between motions in the playlist of the modifier for
the model named Alien5 to 1200 milliseconds.
member("newaliens").model("Alien5").keyframePlayer.\
blendTime = 1200
See also

autoblend, blendFactor

bone
Syntax

member(whichCastmember).modelResource(whichModelResource).\
bone.count
member(whichCastmember).model(whichModel).bonesPlayer.\
bone[index].transform
member(whichCastmember).model(whichModel).bonesPlayer.\
bone[index].worldTransform
Description

3D element; a bone is structural element of a model resource authored in a 3D modeling

program. Bones cannot be created, deleted, or rearranged in Director.
Bones (#bones) motions, which also must be scripted in a 3D modeling program, act upon the
bone structure of a model resource, and are managed in Director by the bonesPlayer modifier.
See the entries for count, bonesPlayer
for more details.

(modifier), transform (property),

and

worldTransform
See also

count, bonesPlayer (modifier), transform (property), worldTransform

bonesPlayer (modifier)
Syntax

member(whichCastmember).model(whichModel).
bonesPlayer.whichBonesPlayerProperty
Description

3D modifier; manages the use of motions by models. The motions managed by the bonesPlayer
modifier animate segments, called bones, of the model.
Motions and the models that use them must be created in a 3D modeling program, exported as
W3D files, and then imported into a movie. Motions cannot be applied to model primitives
created within Director.
Adding the bonesPlayer modifier to a model by using the addModifier command allows access
to the following bonesPlayer modifier properties:
playing (3D)

indicates whether a model is executing a motion.

is a linear list of property lists containing the playback parameters of the motions that
are queued for a model.

playlist

currentTime (3D)

indicates the local time, in milliseconds, of the currently playing or

paused motion.

Lingo Dictionary 103

is a number that is multiplied by the scale parameter of the play() or queue()

command to determine the playback speed of the motion.

playRate

playlist.count
rootLock

returns the number of motions currently queued in the playlist.

indicates whether the translational component of the motion is used or ignored.

currentLoopState

indicates whether the motion plays once or repeats continuously.

blendTime indicates the length of the transition created by the modifier between motions when
the modifiers autoblend property is set to TRUE.
autoblend indicates whether the modifier creates a linear transition to the currently playing
motion from the motion that preceded it.

indicates the degree of blending between motions when the modifiers autoBlend
property is set to FALSE.

blendFactor

bone[boneId].transform indicates the transform of the bone relative to the parent bone. You
can find the boneId value by testing the getBoneID property of the model resource. When you
set the transform of a bone, it is no longer controlled by the current motion, and cannot be
returned to the control of the motion. Manual control ends when the current motion ends.
bone[boneId].getWorldTransform
lockTranslation

returns the world-relative transform of the bone.

indicates whether the model can be displaced from the specified planes.

positionReset indicates whether the model returns to its starting position after the end of a
motion or each iteration of a loop.
rotationReset indicates the rotational element of a transition from one motion to the next, or
the looping of a single motion.
Note: For more detailed information about these properties, see the individual property entries.

The bonesPlayer modifier uses the following commands:

pause() (3D)
play() (3D)

halts the motion currently being executed by the model.

initiates or unpauses the execution of a motion.

playNext() (3D)
queue() (3D)

initiates playback of the next motion in the playlist.

adds a motion to the end of the playlist.

The bonesPlayer modifier generates the following events, which are used by handlers declared in
the registerForEvent() and registerScript() commands. The call to the declared handler
includes three arguments: the event type (either #animationStarted or #animationEnded), the
name of the motion, and the current time of the motion. For detailed information about
notification events, see registerForEvent().
#animationStarted is sent when a motion begins playing. If blending is used between motions,
the event is sent when the transition begins.
#animationEnded is sent when a motion ends. If blending is used between motions, the event is
sent when the transition ends.
See also

keyframePlayer (modifier), addModifier, modifiers, modifier

104 Chapter 3

border
Syntax

member(whichFieldCastmember).border
the border of member whichFieldCastmember
Description

Field cast member property; indicates the width, in pixels, of the border around the specified field
cast member.
Example

This statement makes the border around the field cast member Title 10 pixels wide.
Dot syntax:
member("Title").border = 10

Verbose syntax:
set the border of member "Title" to 10

bottom
Syntax

sprite(whichSprite).bottom
the bottom of sprite whichSprite
Description

Sprite property; specifies the bottom vertical coordinate of the bounding rectangle of the sprite
specified by whichSprite.
When a movie plays back as an applet, this propertys value is measured from the upper left corner
of the applet.
This property can be tested and set.
Example

This statement assigns the vertical coordinate of the bottom of the sprite numbered (i + 1) to the
variable named lowest.
Dot syntax:
set lowest = sprite (i + 1).bottom

Verbose syntax:
set lowest = the bottom of sprite (i + 1)
See also

height, left, locH, locV, right, top, width

bottom (3D)
Syntax

member(whichCastmember).modelResource(whichModelResource).bottom

Lingo Dictionary 105

Description

3D #box model resource property; indicates whether the side of the box intersected by its -Y axis
is sealed (TRUE) or open (FALSE).
The default value for this property is TRUE.
Example

This statement sets the bottom property of the model resource named GiftBox to TRUE, meaning
the bottom of this box will be closed.
member("3D World").modelResource("GiftBox").bottom = TRUE
See also

back, front, top (3D), left (3D), right (3D), bottomCap

bottomCap
Syntax

member(whichCastmember).modelResource(whichModelResource).\
bottomCap
Description

3D #cylinder model resource property; indicates whether the end of the cylinder intersected by
its -Y axis is sealed (TRUE) or open (FALSE).
The default value for this property is TRUE.
Example

This statement sets the bottomCap property of the model resource named Tube to FALSE,
meaning the bottom of this cylinder will be open.
member("3D World").modelResource("Tube").bottomCap = FALSE
See also

topCap, bottomRadius, bottom (3D)

bottomRadius
Syntax

member(whichCastmember).modelResource(whichModelResource).\
bottomRadius
Description

3D #cylinder model resource property; indicates the radius, in world units, of the end of the
cylinder that is intersected by its -Y axis.
The default value for this property is 25.
Example

This statement sets the bottomRadius property of the model resource named Tube to 38.5.
member("3D World").modelResource("Tube").bottomRadius = 38.5
See also

topRadius, bottomCap

106 Chapter 3

bottomSpacing
Syntax

chunkExpression.bottomSpacing
Description

Text cast member property; enables you to specify additional spacing applied to the bottom of
each paragraph in the chunkExpression portion of the text cast member.
The value itself is an integer, where less than 0 indicates less spacing between paragraphs and
greater than 0 indicates more spacing between paragraphs.
The default value is 0, which results in default spacing between paragraphs.
Note: This property, like all text cast member properties, supports only dot syntax.

Example

This example adds spacing after the first paragraph in cast member News Items.
member("News Items").paragraph[1].bottomSpacing=20
See also

top (3D)

boundary
Syntax

member(whichCastmember).model(whichModel).inker.boundary
member(whichCastmember).model(whichModel).toon.boundary
Description

3D inker and toon modifier property; allows you to set whether a line is drawn at the edges
of a model.
The default setting for this property is TRUE.
Example

This statement sets the boundary property of the inker modifier applied to the model named Box
to TRUE. Lines will be drawn at the edges of the surface of the model.
member("shapes").model("Box").inker.boundary = TRUE
See also

lineColor, lineOffset, silhouettes, creases

boundingSphere
Syntax

member(whichCastmember).model(whichModel).boundingSphere
member(whichCastmember).group(whichGroup).boundingSphere
member(whichCastmember).light(whichLight).boundingSphere
member(whichCastmember).camera(whichCamera).boundingSphere
Description

3D model, group, light, and camera property; describes a sphere that contains the model, group,
light, or camera and its children.

Lingo Dictionary 107

The value of this property is a list containing the vector position of the center of the sphere and
the floating-point length of the spheres radius.
This property can be tested but not set.
Example

This example displays the bounding sphere of a light in the message window.
put member("newAlien").light[5].boundingSphere
-- [vector(166.8667, -549.6362, 699.5773), 1111.0039]
See also

debug

boxDropShadow
Syntax

member(whichCastMember).boxDropShadow
the boxDropShadow of member whichCastMember
Description

Cast member property; determines the size, in pixels, of the drop shadow for the box of the field
cast member specified by whichCastMember.
Example

This statement makes the drop shadow of field cast member Title 10 pixels wide.
Dot syntax:
member("Title").boxDropShadow = 10

Verbose syntax:
set the boxDropShadow of member "Title" to 10

boxType
Syntax

member(whichCastMember).boxType
the boxType of member whichCastMember
Description

Cast member property; determines the type of text box used for the specified cast member. The
possible values are #adjust, #scroll, #fixed, and #limit.
Example

This statement makes the box for field cast member Editorial a scrolling field.
Dot syntax:
member("Editorial").boxType = #scroll

Verbose syntax:
set the boxType of member "Editorial" to #scroll

108 Chapter 3

breakLoop()
Syntax

sound(channelNum).breakLoop()
Description

This function causes the currently looping sound in channel channelNum to stop looping and
play through to its endTime. If there is no current loop, this function has no effect.
Example

This handler causes the background music looping in sound channel 2 to stop looping and play
through to its end:
on continueBackgroundMusic
sound(2).breakLoop()
end
See also

end, loopCount, loopEndTime, loopsRemaining, loopStartTime

brightness
Syntax

member(whichCastmember).shader(whichShader).brightness
member(whichCastmember).model(whichModel).shader.brightness
member(whichCastmember).model(whichModel).shaderList{[index]}.\
brightness
Description

3D #newsprint and #engraver shader property; indicates the amount of white blended into
the shader.
The range of this property is 1 to 100; the default value is 0.
Example

This statement sets the brightness of the shader used by the model named gbCyl2 to half of its
maximum value.
member("scene").model("gbCyl2").shader.brightness = 50
See also

newShader

broadcastProps
Syntax

member(whichVectorOrFlashMember).broadcastProps
the broadcastProps of member whichVectorOrFlashMember
Description

Cast member property; controls whether changes made to a Flash or Vector shape cast member
are immediately broadcast to all of its sprites currently on the Stage (TRUE) or not (FALSE).
When this property is set to FALSE, changes made to the cast member are used only as defaults for
new sprites and dont affect sprites on the Stage.
The default value for this property is TRUE, and it can be both tested and set.

Lingo Dictionary 109

Example

This frame script assumes that a Flash movie cast member named Navigation Movie has been set
up with its broadcastProps property set to FALSE. The script momentarily allows changes to a
Flash movie cast member to be broadcast to its sprites currently on the Stage. It then sets the
viewScale property of the Flash movie cast member, and that change is broadcast to its sprite.
The script then prevents the Flash movie from broadcasting changes to its sprites.
Dot syntax:
on enterFrame
member("Navigation Movie").broadcastProps = TRUE
member("Navigation Movie").viewScale = 200
member("Navigation Movie").broadcastProps = FALSE
end

Verbose syntax:
on enterFrame
set the broadcastProps of member "Navigation Movie" = TRUE
set the viewScale of member "Navigation Movie" = 200
set the broadcastProps of member "Navigation Movie" = FALSE
end

browserName()
Syntax

browserName pathName
browserName()
browserName(#enabled, trueOrFalse)
Description

System property, command, and function; specifies the path or location of the browser. You can
use the FileIO Xtra to display a dialog box that allows the user to search for a browser. The
displayOpen() method of the FileIO Xtra is useful for displaying an Open dialog box.
The form browserName() returns the name of the currently specified browser. Placing a
pathname, like one found using the FileIO Xtra, as an argument in the form
browserName(fullPathToApplication) allows the property to be set. The form
browserName(#enabled, trueOrFalse) determines whether the specified browser launches
automatically when the goToNetPage command is issued.
This command is only useful playing back in a projector or in Director, and has no effect when
playing back in a browser.
This property can be tested and set.
Examples

This statement refers to the location of the Netscape browser:

browserName "My Disk:My Folder:Netscape"

This statement displays the browser name in a Message window:

put browserName()

110

Chapter 3

bufferSize
Syntax

member(whichFlashMember).bufferSize
the bufferSize of member whichFlashMember
Description

Flash cast member property; controls how many bytes of a linked Flash movie are streamed into
memory at one time. The bufferSize member property can have only integer values. This
property has an effect only when the cast members preload property is set to FALSE.
This property can be tested and set. The default value is 32,768 bytes.
Example

This startMovie handler sets up a Flash movie cast member for streaming and then sets its
bufferSize property.
Dot syntax:
on startMovie
member.("Flash Demo").preload = FALSE
member.("Flash Demo").bufferSize = 65536
end

Verbose syntax:
on startMovie
set the preload of member "Flash Demo" = FALSE
set the bufferSize of member "Flash Demo" = 65536
end
See also

bytesStreamed, preLoadRAM, stream, streamMode

build()
Syntax

member(whichCastmember).modelResource(whichModelResource).build()
Description

3D mesh command; constructs a mesh. This command is only used with model resources whose
type is #mesh.
You must use the build() command in the initial construction of the mesh, after changing any
of the face properties of the mesh, and after using the generateNormals() command.
Example

This example creates a simple model resource whose type is #mesh, specifies its properties, and
then creates a new model using the model resource. The process is outlined in the following lineby-line explanation of the example code:
Line 1 creates a mesh called Plane, which has one face, three vertices, and a maximum of three
colors. The number of normals and the number of texture coordinates are not set. The normals
are created by the generateNormals command.
Line 2 defines the vectors that will be used as the vertices for Plane.
Line 3 assigns the vectors to the vertices of the first face of Plane.

Lingo Dictionary

111

Line 4 defines the three colors allowed by the newMesh command.

Line 5 assigns the colors to the first face of Plane. The third color in the color list is applied to the
first vertex of Plane, the second color to the second vertex, and the first color to the third vertex.
The colors will spread across the first face of Plane in gradients.
Line 6 creates the normals of Plane with the generateNormals() command.
Line 7 calls the build() command to construct the mesh.
nm = member("Shapes").newMesh("Plane",1,3,0,3,0)
nm.vertexList = [vector(0,0,0), vector(20,0,0), vector(20, 20, 0)]
nm.face[1].vertices = [1,2,3]
nm.colorList = [rgb(255,255,0), rgb(0, 255, 0), rgb(0,0,255)]
nm.face[1].colors = [3,2,1]
nm.generateNormals(#smooth)
nm.build()
nm = member("Shapes").newModel("TriModel", nm)
See also

generateNormals(), newMesh, face

buttonsEnabled
Syntax

sprite(whichFlashSprite).buttonsEnabled
the buttonsEnabled of sprite whichFlashSprite
member(whichFlashMember).buttonsEnabled
the buttonsEnabled of member whichFlashMember
Description

Flash cast member property and sprite property; controls whether the buttons in a Flash movie
are active (TRUE, default) or inactive (FALSE). Button actions are triggered only when the
actionsEnabled property is set to TRUE.
This property can be tested and set.
Example

This handler accepts a sprite reference and toggles the sprites buttonsEnabled property on or off.
Dot syntax:
on ToggleButtons whichSprite
sprite(whichSprite).buttonsEnabled = not sprite(whichSprite).buttonsEnabled
end

Verbose syntax:
on ToggleButtons whichSprite
set the buttonsEnabled of sprite whichSprite = not the buttonsEnabled of
sprite whichSprite
end
See also

actionsEnabled

112

Chapter 3

buttonStyle
Syntax

the buttonStyle
Description

Movie property; determines the visual response of buttons when the user rolls the pointer off
them. This property applies only to buttons created with the Button tool in the Tool palette.
The buttonStyle property can have these values:

0 (list style: default)Subsequent buttons are highlighted when the pointer passes over them.
Releasing the mouse button activates the script associated with that button.

1 (dialog style)Only the first button clicked is highlighted. Subsequent buttons are not
highlighted. Releasing the mouse button while the pointer is over a button other than the
original button clicked does not activate the script associated with that button.

This property can be tested and set in any type of script.

Examples

The following statement sets the buttonStyle property to 1:

the buttonStyle = 1

This statement remembers the current setting of the buttonStyle property by putting the
current buttonStyle value in the variable buttonStyleValue:
buttonStyleValue = the buttonStyle
See also

checkBoxAccess, checkBoxType

buttonType
Syntax

member(whichCastMember).buttonType
the buttonType of member whichCastMember
Description

Button cast member property; indicates the specified button cast members type. Possible values
are #pushButton, #checkBox, and #radioButton. This property applies only to buttons
created with the button tool in the Tool palette.
Example

This statement makes the button cast member Editorial a check box.
Dot syntax:
member("Editorial").buttonType = #checkBox

Verbose syntax:
set the buttonType of member "Editorial" to #checkBox

Lingo Dictionary

113

bytesStreamed
Syntax

member(whichFlashOrSWAMember).bytesStreamed
the bytesStreamed of member whichFlashOrSWAMember
Description

Flash and Shockwave Audio cast member property; indicates the number of bytes of the specified
cast member that have been loaded into memory. The bytesStreamed property returns a value
only when the Director movie is playing. It returns an integer value.
This property can be tested but not set.
Example

This handler accepts a cast member reference as a parameter, and it then uses the stream
command to load the cast member into memory. Every time it streams part of the cast member
into memory, it uses the bytesStreamed property to report in the Message window how many
bytes have been streamed.
Dot syntax:
on fetchMovie whichFlashMovie
repeat while member(whichFlashMovie).percentStreamed < 100
stream(member whichFlashMovie)
put "Number of bytes streamed:" && member(whichFlashMovie).bytesStreamed
end repeat
end

Verbose syntax:
on fetchMovie whichFlashMovie
repeat while the percentStreamed of member whichFlashMovie < 100
stream(member whichFlashMovie)
put "Number of bytes streamed:" && the bytesStreamed of member
whichFlashMovie
end repeat
end

See also

bufferSize, percentStreamed, stream

bytesStreamed (3D)
Syntax

member(whichCastMember).bytesStreamed
Description

3D cast member property; indicates how much of the initial file import or the last requested file
load has loaded.
Example

This statement shows that 325,300 bytes of the cast member named Scene have been loaded.
put member("Scene").bytesStreamed
-- 325300
See also

streamSize (3D), state (3D)

114

Chapter 3

cacheDocVerify()
Syntax

cacheDocVerify #setting
cacheDocVerify()
Description

Function; sets how often the contents of a page on the Internet are refreshed with information
from the projectors cache. Possible values are #once (default) and #always.
Specifying #once tells a movie to get a file from the Internet once and then use the file from the
cache without looking for an updated version on the Internet.
Specifying #always tells a movie to try to get an updated version of the file each time the movie
calls a URL.
The form cacheDocVerify() returns the current setting of the cache.
The cacheDocVerify function is valid only for movies running in Director or as projectors. This
function is not valid for Shockwave movies because they use the network settings of the browser
in which they run.
on resetCache
current = cacheDocVerify()
if current = #once then
alert "Turning cache verification on"
cacheDocVerify #always
end if
end
See also

cacheSize(), clearCache

cacheSize()
Syntax

cacheSize Size
cacheSize()
Description

Function and command; sets the cache size of Director. The value is in kilobytes.
The cacheSize function is valid only for movies running in Director or as projectors. This
function is not valid for Shockwave movies because they use the network settings of the browser
in which they run.
Example

This handler checks whether the browsers cache setting is less than 1 MB. If it is, the handler
displays an alert and sets the cache size to 1 MB:
on checkCache if
cacheSize()<1000 then
alert "increasing cache to 1MB"
cacheSize 1000
end if
end
See also

cacheDocVerify(), clearCache

Lingo Dictionary

115

call
Syntax

call #handlerName, script, {args...}

call (#handlerName, scriptInstance, {args...})
Description

Command; sends a message that invokes a handler in specified scripts where handlerName is the
name of the handler to be activated, script references the script or a list of scripts, and args are
any optional parameters to be passed to the handler.
If script is a single script instance, an error alert occurs if the handler is not defined in the
scripts ancestor script.
If script is a list of script instances, the message is sent to each item in the list in turn; if the
handler is not defined in the ancestor script, no alert is generated.
The call command can use a variable as the name of the handler. Messages passed using call are
not passed to other scripts attached to the sprite, cast member scripts, frame scripts, or movie scripts.
Examples

This handler sends the message bumpCounter to the first behavior script attached to sprite 1:
on mouseDown me
-- get the reference to the first behavior of sprite 1
set xref = getAt (the scriptInstanceList of sprite 1,1)
-- run the bumpCounter handler in the referenced script,
-- with a parameter
call (#bumpCounter, xref, 2)
end

The following example shows how a call statement can call handlers in a behavior or parent
script and its ancestor.

This is the parent script:

-- script Man
property ancestor
on new me
set ancestor = new(script "Animal", 2)
return me
end
on run me, newTool
put "Man running with "&the legCount of me&" legs"
end

This is the ancestor script:

-- script Animal
property legCount
on new me, newLegCount
set legCount = newLegCount
return me
end
on run me
put "Animal running with "& legCount &" legs"
end
on walk me
put "Animal walking with "& legCount &" legs"
end

116

Chapter 3

 The following statements use the parent script and ancestor script.
This statement creates an instance of the parent script:
set m = new(script "man")

This statement makes the man walk:

call #walk, m
-- "Animal walking with 2 legs"

This statement makes the man run:

set msg = #run
call msg, m
-- "Man running with 2 legs and rock"

This statement creates a second instance of the parent script:

set m2 = new(script "man")

This statement sends a message to both instances of the parent script:

call msg, [m, m2]
-- "Man running with 2 legs "
-- "Man running with 2 legs "

callAncestor
Syntax

callAncestor handlerName, script, {args...}

Description

Command; sends a message to a child objects ancestor script, where handlerName is the name of
the handler to be activated, script references the script instance or a list of script instances, and
args are any optional parameters to be passed to the handler.
If script is a single script instance, an error alert occurs if the handler is not defined in the
ancestor of the script.
If script is a list of script instances, the message is sent to each item in the list in turn. In this
case, if the handler is not defined in an ancestor script, no alert is generated.
Ancestors can, in turn, have their own ancestors.
When you use callAncestor, the name of the handler can be a variable, and you can explicitly
bypass the handlers in the primary script and go directly to the ancestor script.
Example

This example shows how a callAncestor statement can call handlers in the ancestor of a
behavior or parent script.

This is the parent script:

-- script "man"
property ancestor
on new me, newTool
set ancestor = new(script "Animal", 2)
return me
end
on run me
put "Man running with "&the legCount of me&"legs"
end

Lingo Dictionary

117

 This is the ancestor script:

-- script "animal"
property legCount
on new me, newLegCount
set legCount = newLegCount
return me
end
on run me
put "Animal running with "& legCount &" legs"
end
on walk me
put "Animal walking with "& legCount &" legs"
end

The following statements use the parent script and ancestor script.
This statement creates an instance of the parent script:
set m = new(script "man")

This statement makes the man walk:

call #walk, m
-- "Animal walking with 2 legs"

This statement makes the man run:

set msg = #run
callAncestor msg, m
-- "Animal running with 2 legs"

This statement creates a second instance of the parent script:

set m2 = new(script "man")

This statement sends a message to the ancestor script for both men:
callAncestor #run,[m,m2]
-- "Animal running with 2 legs"
-- "Animal running with 2 legs"
See also

ancestor, new()

callFrame()
Syntax

sprite(whichSprite).callFrame("FlashLabel")
sprite(whichSprite).callFrame(FlashFrameNumber)
Definition

Command; used to call a series of actions that reside in a frame of a Flash movie sprite. You can
specify which frame to call using a frame number or a label. This command sends a message to
the Flash ActionScript engine and triggers the actions to execute in the Flash movie.
Example

This Lingo executes the actions that are attached to frame 10 of the Flash movie in sprite 1:
sprite(1).callFrame(10)

118

Chapter 3

camera
Syntax

member(whichCastMember).camera(whichCamera)
member(whichCastMember).camera[index]
member(whichCastMember).camera(whichCamera).whichCameraProperty
member(whichCastMember).camera[index].whichCameraProperty
sprite(whichSprite).camera{(index)}
sprite(whichSprite).camera{(index)}.whichCameraProperty
Description

3D element; an object at a vector position from which the 3D world is viewed.

Each sprite has a list of cameras. The view from each camera in the list is displayed on top of the
view from camera with lower index positions. You can set the rect (camera) property of each
camera to display multiple views within the sprite.
Cameras are stored in the camera palette of the cast member. Use the newCamera and
commands to create and delete cameras in a 3D cast member.

deleteCamera

The camera property of a sprite is the first camera in the list of cameras of the sprite. The camera
referred to by sprite(whichSprite).camera is the same as
sprite(whichSprite).camera(1). Use the addCamera and deleteCamera commands to build
the list of cameras in a 3D sprite.
For a complete list of camera properties and commands, see Chapter 2, 3D Lingo by Feature,
on page 31.
Examples

This statement sets the camera of sprite 1 to the camera named TreeCam of the cast member
named Picnic.
sprite(1).camera = member("Picnic").camera("TreeCam")

This statement sets the camera of sprite 1 to camera 2 of the cast member named Picnic.
sprite(1).camera = member("Picnic").camera[2]
See also

bevelDepth, overlay, modelUnderLoc, spriteSpaceToWorldSpace, fog, clearAtRender

cameraCount()
Syntax

sprite(whichSprite).cameraCount()
Description

3D command; returns the number items in the list of cameras of the sprite.
Example

This statement shows that sprite 5 contains three cameras.

put sprite(5).cameraCount()
-- 3
See also

addCamera, deleteCamera

Lingo Dictionary

119

cameraPosition
Syntax

member(whichCastMember).cameraPosition
sprite(whichSprite).cameraPosition
Description

3D cast member and sprite property; indicates the position of the default camera.
The default value of this property is vector(0, 0, 250). This is the position of the default camera in
a newly created 3D cast member.
Example

This statement shows that the position of the default camera of the cast member named Babyland
is the vector (-117.5992, -78.9491, 129.0254).
member("Babyland").cameraPosition = vector(-117.5992, \
-78.9491, 129.0254)
See also

cameraRotation, autoCameraPosition

cameraRotation
Syntax

member(whichCastMember).cameraRotation
sprite(whichSprite).cameraRotation
Description

3D cast member and sprite property; indicates the position of the default camera.
The default value of this property is vector(0, 0, 0). This is the rotation of the default camera in a
newly created 3D cast member.
Example

This statement shows that the rotation of the default camera of the cast member named Babyland
is the vector (82.6010, -38.8530, -2.4029).
member("babyland").cameraRotation = vector(82.6010, \
-38.8530, -2.4029)
See also

cameraPosition, autoCameraPosition

cancelIdleLoad
Syntax

cancelIdleLoad loadTag
Description

Command; cancels the loading of all cast members that have the specified load tag.
Example

This statement cancels the loading of cast members that have an idle load tag of 20:
cancelIdleLoad 20

120 Chapter 3

See also

idleLoadTag

case
Syntax

case expression of
expression1 : Statement
expression2 :
multipleStatements
.
.
.
expression3, expression4 :
Statement
{otherwise:
statement(s)}
end case
Description

Keyword; starts a multiple branching logic structure that is easier to write than repeated
if...then statements.
Lingo compares the value in case expression to the expressions in the lines beneath it, starting
at the beginning and continuing through each line in order, until Lingo encounters an expression
that matches case expression.
When Lingo finds a matching expression, it executes the corresponding statement or statements
that follow the colon after the matching expression. When only one statement follows the matching
expression, the matching expression and its corresponding statement may appear on the same line.
Multiple statements must appear on indented lines immediately below the matching expression.
When more than one possible match could cause Lingo to execute the same statements, the
expressions must be separated by commas. (The syntax line containing expression3 and
expresssion4 is an example of such a situation.)
After Lingo encounters the first match, it stops testing for additional matches.
If the optional otherwise statement is included at the end of the case structure, the statements
following otherwise are executed if there are no matches.
If a case statement tests cases that arent all integer constants, the Export Xtra for Java converts
the case statement to an if...then statement.
Examples

The following handler tests 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.

Lingo Dictionary

121

 If the user pressed any other key, the computer beeps.

on keyDown
case (the key) of
"A": go to frame "Apple"
"B", "C":
puppetTransition 99
go to frame "Oranges"
otherwise beep
end case
end keyDown

This case statement tests whether the cursor is over sprite 1, 2, or 3 and runs the corresponding
Lingo if it is:
case the rollOver of
1: puppetSound "Horn"
2: puppetSound "Drum"
3: puppetSound "Bongos"
end case

castLib
Syntax

castLib whichCast
Description

Keyword; indicates that the cast specified in whichCast is a cast.

The default cast is cast number 1. To specify a cast member in a cast other than cast 1, set
castLib to specify the alternative cast.
Examples

This statement displays the number of the Buttons cast in the Message window.
Dot syntax:
put castLib("Buttons").number

Verbose syntax:
put the number of castLib "Buttons"

This statement assigns cast member 5 in castLib 4 to sprite 10:

sprite(10).member = member(5, 4)

castLibNum
Syntax

member(whichCastMember).castLibNum
the castLibNum of member whichCastMember
sprite(whichSprite).castLibNum
the castLibNum of sprite whichSprite
Description

Cast member and sprite property; determines the number of the cast that contains the specified
cast member, or which castLib is currently associated with the specified sprite.

122 Chapter 3

If you change the castLibNum sprite property without changing the memberNum sprite property,
Director uses the cast member that has the same cast member number in the new cast. This is
useful for movies that you use as templates and update by supplying new casts. If you organize the
cast contents so that each cast member has a cast member number that corresponds to its role in
the movie, Director automatically inserts the new cast members correctly. To change the cast
member assigned to a sprite regardless of its cast, set the member sprite property.
For a cast member, this property can be tested but not set. It can be both tested and set for a sprite.

Lingo Dictionary 123

Examples

This statement determines the number of the cast to which cast member Jazz is assigned.
Dot syntax:
put member("Jazz").castLibNum

Verbose syntax:
put the castLibNum of member "Jazz"

The following statement changes the cast member assigned to sprite 5 by switching its cast to
Wednesday Schedule.
Dot syntax:
sprite(5).castLibNum = castLib("Wednesday Schedule").number

Verbose syntax:
set the castLibNum of sprite 5 to the number of castLib "Wednesday Schedule"

castMemberList
Syntax

member(whichCursorCastMember).castmemberList
the castmemberList of member whichCursorCastMember
Description

Cursor cast member property; specifies a list of cast members that make up the frames of a cursor.
For whichCursorCastMember, substitute a cast member name (within quotation marks) or a cast
member number. You can also specify cast members from different casts.
The first cast member in the list is the first frame of the cursor, the second cast member is the
second frame, and so on.
If you specify cast members that are invalid for use in a cursor, they will be ignored, and the
remaining cast members will be used.
This property can be tested and set.
Example

This command sets a series of four cast members for the animated color cursor cast member
named myCursor.
Dot syntax:
member("myCursor").castmemberList = \
[member 1, member 2, member 1 of castlib 2, member 2 of castlib 2]

Verbose syntax:
set the castmemberList of member "myCursor" = \
[member 1, member 2, member 1 of castlib 2, member 2 of castlib 2]

124 Chapter 3

center
Syntax

member(whichCastMember).center
the center of member whichCastMember
Description

Cast member property; interacts with the crop cast member property.

When the crop property is FALSE, the center property has no effect.
When crop is TRUE and center is TRUE, cropping occurs around the center of the digital video
cast member.

When crop is TRUE and center is FALSE, the digital videos right and bottom sides are cropped.
This property can be tested and set.
Example

This statement causes the digital video cast member Interview to be displayed in the top left
corner of the sprite.
Dot syntax:
member("Interview").center = FALSE

Verbose syntax:
set the center of member "Interview" to FALSE
See also

crop (cast member property), centerRegPoint, regPoint, scale

centerRegPoint
Syntax

member(whichCastMember).centerRegPoint
the centerRegPoint of member whichCastMember
Description

Flash, vector shape, and bitmap cast member property; automatically centers the registration
point of the cast member when you resize the sprite (TRUE, default); or repositions the
registration point at its current point value when you resize the sprite, set the defaultRect
property, or set the regPoint property (FALSE).
This property can be tested and set.
Example

This script checks to see if a Flash movies centerRegPoint property is set to TRUE. If it is, the
script uses the regPoint property to reposition the sprites registration point to its upper left
corner. By checking the centerRegPoint property, the script ensures that it does not reposition a
registration point that had been previously set using the regPoint property.

Lingo Dictionary 125

Dot syntax:
on beginSprite me
if sprite(the spriteNum of me).member.centerRegPoint = TRUE then
sprite(the spriteNum of me).member.regPoint = point(0,0)
end if
end

Verbose syntax:
on beginSprite me
if the centerRegPoint of member the memberNum of me = TRUE then
set the regPoint of member the memberNum of me = point(0,0)
end if
end
See also

regPoint

centerStage
Syntax

the centerStage
Description

Movie property; determines whether the Stage is centered on the monitor when the movie is
loaded (TRUE, default) or not centered (FALSE). Place the statement that includes this property in
the movie that precedes the movie you want it to affect.
This property is useful for checking the Stage location before a movie plays from a projector.
This property can be tested and set.
Note: Be aware that behavior while playing back in a projector differs between Windows and Macintosh systems.
Settings selected during creation of the projector may override this property.

Examples

This statement sends the movie to a specific frame if the Stage is not centered:
if the centerStage = FALSE then go to frame "Off Center"

This statement changes the centerStage property to the opposite of its current value:
set the centerStage to (not the centerStage)
See also

fixStageSize

changeArea
Syntax

member(whichCastMember).changeArea
the changeArea of member whichCastMember
Description

Transition cast member property; determines whether a transition applies only to the changing
area on the Stage (TRUE) or to the entire Stage (FALSE). Its effect is similar to selecting the
Changing Area Only option in the Frame Properties Transition dialog box.
This property can be tested and set.

126 Chapter 3

Example

This statement makes the transition cast member Wave apply only to the changing area on
the Stage.
Dot syntax:
member("Wave").changeArea = TRUE

Verbose syntax:
set the changeArea of member "Wave" to TRUE

channelCount
Syntax

member(whichCastMember).channelCount
the channelCount of member whichCastMember
sound(channelNum).channelCount
Description

Sound channel and cast member property; for sound channels, determines the number of
channels in the currently playing or paused sound in the given sound channel. For sound cast
members, determines the number of channels in the specified cast member.
This is useful for determining whether a sound is in monaural or in stereo. This property can be
tested but not set.
Examples

This statement determines the number of channels in the sound cast member, Jazz.
Dot syntax:
put member("Jazz").channelCount

Verbose syntax:
put the channelCount of member "Jazz"

This statement determines the number of channels in the sound member currently playing in
sound channel 2:
put sound(2).channelCount

char...of
Syntax

textMemberExpression.char[whichCharacter]
char whichCharacter of fieldOrStringVariable
textMemberExpression.char[firstCharacter..lastCharacter]
char firstCharacter to lastCharacter of fieldOrStringVariable
Description

Keyword; identifies a character or a range of characters in a chunk expression. A chunk expression

is any character, word, item, or line in any source of text (such as field cast members and variables)
that holds a string.

An expression using whichCharacter identifies a specific character.

An expression using firstCharacter and lastCharacter identifies a range of characters.

Lingo Dictionary 127

The expressions must be integers that specify a character or range of characters in the chunk.
Characters include letters, numbers, punctuation marks, spaces, and control characters such as
Tab and Return.
You can test but not set the char...of keyword. Use the put...into command to modify the
characters in a string.
Examples

This statement displays the first character of the string $9.00:

put ("$9.00").char[1..1]
-- "$"

This statement displays the entire string $9.00:

put ("$9.00").char[1..5]
-- "$9.00"

This statement changes the first five characters of the second word in the third line of a text
cast member:
member("quiz").line[3].word[2].char[1..5] = "?????"
See also

mouseMember, mouseItem, mouseLine, mouseWord

characterSet
Syntax

member(whichFontMember).characterSet
the characterSet of member whichFontMember
Description

Font cast member property; returns a string containing the characters included for import when
the cast member was created. If all characters in the original font were included, the result is an
empty string.
Example

This statement displays the characters included when cast member 11 was created. The characters
included during import were numerals and Roman characters.
put member(11).characterSet
-- "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
See also

recordFont, bitmapSizes, originalFont

charPosToLoc()
Syntax

member(whichCastMember).charPosToLoc(nthCharacter)
charPosToLoc(member whichCastMember, nthCharacter)
Description

Field function; returns the point in the entire field cast member (not just the part that appears on
the Stage) that is closest to the character specified by nthCharacter. This is useful for
determining the location of individual characters.

128 Chapter 3

Values for charPosToLoc are in pixels from the top left corner of the field cast member. The
nthCharacter parameter is 1 for the first character in the field, 2 for the second character, and so on.
Example

The following statement determines the point where the fiftieth character in the field cast
member Headline appears and assigns the result to the variable location:
location = charPosToLoc(member "Headline", 50)

chars()
Syntax

chars(stringExpression, firstCharacter, lastCharacter)

Description

Function; identifies a substring of characters in stringExpression. The substring starts at

firstCharacter and ends at lastCharacter. The expressions firstCharacter and
lastCharacter must specify a position in the string.
If firstCharacter and lastCharacter are equal, then a single character is returned from the string.
If lastCharacter is greater than the string length, only a substring up to the length of the string is
identified. If lastCharacter is before firstCharacter, the function returns the value EMPTY.
To see an example of chars() used in a completed movie, see the Text movie in the Learning/
Lingo Examples folder inside the Director application folder.
Examples

This statement identifies the sixth character in the word Macromedia:

put chars("Macromedia", 6, 6)
-- "m"

This statement identifies the sixth through tenth characters of the word Macromedia:
put chars("Macromedia", 6, 10)
-- "media"

The following statement tries to identify the sixth through twentieth characters of the word
Macromedia. Because the word has only 10 characters, the result includes only the sixth through
tenth characters.
put chars ("Macromedia", 6, 20)
-- "media"
See also

char...of, length(), offset() (string function), number (characters)

charSpacing
Syntax

chunkExpression.charSpacing
Description

Text cast member property; enables specifying any additional spacing applied to each letter in the
chunkExpression portion of the text cast member.
A value less than 0 indicates less spacing between letters. A value greater than 0 indicates more
spacing between letters.

Lingo Dictionary 129

The default value is 0, which results in default spacing between letters.

Example

The following handler increases the current character spacing of the third through fifth words
within the text cast member myCaption by a value of 2:
on myCharSpacer
mySpaceValue = member("myCaption").word[3..5].charSpacing
member("myCaption").word[3..5].charSpacing = (mySpaceValue + 2)
end

charToNum()
Syntax

(stringExpression).charToNum
charToNum(stringExpression)
Description

Function; returns the ASCII code that corresponds to the first character of stringExpression.
The charToNum() function is especially useful for testing the ASCII value of characters created by
combining keys, such as the Control key and another alphanumeric key.
Director treats uppercase and lowercase letters the same if you compare them using the equal sign
(=) operator; for example, the statement put ("M" = "m") returns the result 1 or TRUE.
Avoid problems by using charToNum() to return the ASCII code for a character and then use the
ASCII code to refer to the character.
Examples

This statement displays the ASCII code for the letter A:

put ("A").charToNum
-- 65

The following comparison determines whether the letter entered is a capital A, and then navigates
to either a correct sequence or incorrect sequence in the Score:
on CheckKeyHit theKey
if (theKey).charToNum = 65 then
go "Correct Answer"
else
go "Wrong Answer"
end if
end
See also

numToChar()

130 Chapter 3

checkBoxAccess
Syntax

the checkBoxAccess
Description

Movie property; specifies one of three possible results when the user clicks a check box or radio
button created with button tools in the Tools window:

0 (default)Lets the user set check boxes and radio buttons on and off.
1Lets the user set check boxes and radio buttons on but not off.
2Prevents the user from setting check boxes and radio buttons at all; the buttons can be set
only by scripts.
This property can be tested and set.
Examples

This statement sets the checkBoxAccess property to 1, which lets the user click check boxes and
radio buttons on but not off:
the checkBoxAccess to 1

This statement records the current setting of the checkBoxAccess property by putting the value
in the variable oldAccess:
oldAccess to the checkBoxAccess
See also

hilite (cast member property), checkBoxType

checkBoxType
Syntax

the checkBoxType
Description

Movie property; specifies one of three ways to indicate whether a check box is selected:

0 (default)Creates a standard check box that contains an X when the check box is selected.
1Creates a check box that contains a black rectangle when the check box is selected.
2Creates a check box that contains a filled black rectangle when the check box is selected.
This property can be tested and set.
Example

This statement sets the checkBoxType property to 1, which creates a black rectangle in check
boxes when the user clicks them:
the checkBoxType to 1
See also

hilite (cast member property), checkBoxAccess

Lingo Dictionary

131

checkMark
Syntax

the checkMark of menuItem whichItem of menu whichMenu

Description

Menu item property; determines whether a check mark appears next to the custom menu item
(TRUE) or not (FALSE, default).
The whichItem value can be either a menu item name or a menu item number. The whichMenu
value can be either a menu name or a menu number.
This property can be tested and set.
Note: Menus are not available in Shockwave

Example

This handler turns off any items that are checked in the custom menu specified by the argument
theMenu. For example, unCheck ("Format") turns off all the items in the Format menu.
on unCheck theMenu
set n = the number of menuItems of menu theMenu
repeat with i = 1 to n
set the checkMark of menuItem i of menu theMenu to FALSE
end repeat
end unCheck
See also

installMenu, enabled, name (menu item property), number (menu items), script, menu

child
Syntax

member(whichCastmember).model(whichParentNode).\
child(whichChildNodeName)
member(whichCastmember).model(whichParentNode).child[index]
Description

3D model, group, light, and camera property; returns the child node named
whichChildNodeName or at the specified index in the parent nodes list of children. A node is a
model, group, camera, or light.
The transform of a node is parent-relative. If you change the position of the parent, its children
move with it, and their positions relative to the parent are maintained. Changes to the rotation
and scale properties of the parent are similarly reflected in its children.
Use the addChild method of the parent node or set the parent property of the child node to add
to the parents list of children. A child can have only one parent, but a parent can have any
number of children. A child can also have children of its own.
Example

This statement shows that the second child of the model named Car is the model named Tire.
put member("3D").model("Car").child[2]
-- model("Tire")
See also

addChild, parent

132 Chapter 3

child (XML)
Syntax

XMLnode.child[ childNumber ]
Description

XML property; refers to the specified child node of a parsed XML documents nested tag structure.
Example

Beginning with the following XML:

<?xml version="1.0"?>
<e1>
<tagName attr1="val1" attr2="val2"/>
<e2>element 2</e2>
<e3>element 3</e3>
here is some text
</e1>

This Lingo returns the name of the first child node of the preceding XML:
put gParserObject.child[1].name
-- "e1"

chunkSize
Syntax

member(whichCastMember).chunkSize
the chunkSize of member whichCastMember
Description

Transition cast member property; determines the transitions chunk size in pixels from 1 to 128
and is equivalent to setting the smoothness slider in the Frame Properties: Transition dialog box.
The smaller the chunk size, the smoother the transition appears.
This property can be tested and set.
Example

This statement sets the chunk size of the transition cast member Fog to 4 pixels.
Dot syntax:
member("Fog").chunkSize = 4

Verbose syntax:
set the chunkSize of member "Fog" to 4

clearAsObjects()
Help ID:

x5539 | Lingo_FlashClearAsObject

Syntax

clearAsObjects()

Lingo Dictionary 133

Definition

Command; resets the global Flash Player used for ActionScript objects and removes any
ActionScript objects from memory. The command does not clear or reset references to those
objects stored in Lingo. Lingo references will persist but will refer to nonexistent objects. You
must set each reference to VOID individually.
The clearAsObjects() command affects only global objects, such as the array created in
this statement:
myGlobalArray = newObject(#array)

The clearAsObjects() command has no effect on objects created within sprite references, such
as the following:
myArray = sprite(2).newObject(#array)
Example

This statement clears all globally created ActionScript objects from memory:
clearAsObjects()
See also

newObject(), setCallback()

clearAtRender
Syntax

member(whichCastmember).camera(whichCamera).colorBuffer.\
clearAtRender
sprite(whichSprite).camera{(index)}.colorBuffer.clearAtRender
Description

3D property; indicates whether the color buffer is cleared after each frame. Setting the value to
FALSE, which means the buffer is not cleared, gives an effect similar to trails ink effect. The
default value for this property is TRUE.
Example

This statement prevents Director from erasing past images of the view from the camera. Models
in motion will appear to smear across the stage.
sprite(1).camera.colorBuffer.clearAtRender = 0
See also

clearValue

clearCache
Syntax

clearCache
Description

Command; clears the Director network cache.

The clearCache command clears only the cache, which is separate from the browsers cache.
If a file is in use, it remains in the cache until it is no longer in use.

134 Chapter 3

Example

This handler clears the cache when the movie starts:

on startMovie
clearCache
end
See also

cacheDocVerify(), cacheSize()

clearError
Syntax

member(whichFlashMember).clearError()
clearError (member whichFlashMember)
Description

Flash command; resets the error state of a streaming Flash cast member to 0.
When an error occurs while a cast member is streaming into memory, Director sets the cast
members state property to -1 to indicate that an error occurred. When this happens, you can
use the getError function to determine what type of error occurred and then use the
clearError command to reset the cast members error state to 0. After you clear the members
error state, Director tries to open the cast member if it is needed again in the Director movie.
Setting a cast members pathName, linked, and preload properties also automatically clears the
error condition.
Example

This handler checks to see if an out-of-memory error occurred for a Flash cast member named
Dali, which was streaming into memory. If a memory error occurred, the script uses the
unloadCast command to try to free some memory; it then branches the playhead to a frame in
the Director movie named Artists, where the Flash movie sprite first appears, so Director can
again try to play the Flash movie. If something other than an out-of-memory error occurred, the
script goes to a frame named Sorry, which explains that the requested Flash movie cant be played.
on CheckFlashStatus
if member("Dali").getError() = #memory then
member("Dali").clearError()
unloadCast
go to frame "Artists"
else
go to frame "Sorry"
end if
end
See also

state (Flash, SWA), getError()

clearFrame
Syntax

clearFrame
Description

Command; erases everything in the current frames sprite and affects channels during Score
recording only.

Lingo Dictionary 135

Example

The following handler clears the content of each frame before it edits that frame during Score
generation:
on newScore
beginRecording
repeat with counter = 1 to 50
clearFrame
the frameScript to 25
updateFrame
end repeat
endRecording
end
See also

beginRecording, endRecording, updateFrame

clearGlobals
Syntax

clearGlobals
Description

Command; sets all global variables to VOID.

This command can be useful when initializing global variables or when opening a new movie that
requires a new set of global variables.
Example

This statement sets all global variables to VOID:

clearGlobals

clearValue
Syntax

member(whichCastmember).camera(whichCamera).colorBuffer\
.clearValue
sprite(whichSprite).camera{(index)}.colorBuffer.clearValue
Description

3D property; specifies the color used to clear out the color buffer if colorBuffer.clearAtRender
is set to TRUE. The default setting for this property is rgb(0, 0, 0).
Example

This statement sets the clearValue property of the camera to rgb(255, 0, 0). Spaces in the 3d
world which are not occupied by models will appear red.
sprite(1).camera.colorBuffer.clearValue= rgb(255, 0, 0)
See also

clearAtRender

136 Chapter 3

clickLoc
Syntax

the clickLoc
Description

Function; identifies as a point the last place on the screen where the mouse was clicked.
Example

The following on

mouseDown

handler displays the last mouse click location:

on mouseDown
put the clickLoc
end mouseDown

If the click were 50 pixels from the left end of the Stage and 100 pixels from the top of the Stage,
the Message window would display the following:
-- point(50, 100)

clickMode
Syntax

sprite(whichFlashSprite).clickMode
the clickMode of sprite whichFlashSprite
member(whichFlashMember).clickMode
the clickMode of member whichFlashMember
Description

Flash cast member and sprite property; controls when the Flash movie sprite detects mouse click
events (mouseUp and mouseDown) and when it detects rollovers (mouseEnter, mouseWithin, and
mouseLeave). The clickMode property can have these values:

#boundingBoxDetects

#opaque (default)Detects mouse click events only when the pointer is over an opaque
portion of the sprite and detects rollovers at the boundaries of the opaque portions of the sprite
if the sprites ink effect is set to Background Transparent. If the sprites ink effect is not set to
Background Transparent, this setting has the same effect as #boundingBox.

#objectDetects mouse click events when the mouse pointer is over any filled
(nonbackground) area of the sprite and detects rollovers at the boundaries of any filled area.
This setting works regardless of the sprites ink effect.

mouse click events anywhere within the sprites bounding rectangle

and detects rollovers at the sprites boundaries.

This property can be tested and set.

Example

This script checks to see if the sprite, which is specified with an ink effect of Background
Transparent, is currently set to be rendered direct to Stage. If the sprite is not rendered direct to
Stage, the sprites clickMode is set to #opaque. Otherwise (because ink effects are ignored for
Flash movie sprites that are rendered direct to Stage), the sprites clickMode is set to
#boundingBox.

Lingo Dictionary 137

Dot syntax:
on beginSprite me
if sprite(the spriteNum of me).directToStage = FALSE then
sprite(the spriteNum of me).clickMode = #opaque
else
sprite(the spriteNum of me).clickMode = #boundingBox
end if
end

Verbose syntax:
on beginSprite me
if the directToStage of sprite the spriteNum of me = FALSE then
set the clickMode of sprite the spriteNum of me = #opaque
else
set the clickMode of sprite the spriteNum of me = #boundingBox
end if
end

clickOn
Syntax

the clickOn
Description

Function; returns the last active sprite clicked by the user. An active sprite is a sprite that has a
sprite or cast member script associated with it.
When the user clicks the Stage, clickOn returns 0. To detect whether the user clicks a sprite with
no script, you must assign a placeholder script to it (--," for example) so that it can be detected
by the clickOn function.
The clickOn can be checked within a repeat loop. However, neither clickOn nor clickLoc
functions change value when the handler is running. The value that you obtain is the value from
before the handler started.
Examples

This statement checks whether sprite 7 was the last active sprite clicked:
if the clickOn = 7 then alert "Sorry, try again."

This statement sets the foreColor property of the last active sprite that was clicked to a
random color:
sprite(the clickOn).foreColor = random(255)-1
See also

doubleClick, the mouseDown (system property), mouseMember, the mouseUp (system

property)

138 Chapter 3

clone
Syntax

member(whichCastmember).model(whichModel).clone(cloneName)
member(whichCastmember).group(whichGroup).clone(cloneName)
member(whichCastmember).light(whichLight).clone(cloneName)
member(whichCastmember).camera(whichCamera).clone(cloneName)
Description

3D command; creates a copy of the model, group, light, or camera and all of its children. The
clone is named cloneName and shares the parent of the model, group, light, or camera from
which it was cloned.
A clone of a model uses the same model resource and is assigned the same shaderList as the
original model.
If you do not specify the cloneName, or if you specify "", the clone will not be counted by the
method, but it will appear in the scene.

count

Example

This statement creates a clone named Teapot2 from the model named Teapot, and returns a
reference to the new model.
teapotCopy = member("3D World").model("Teapot").clone("Teapot2")
See also

cloneDeep, cloneModelFromCastmember, cloneMotionFromCastmember, loadFile()

cloneDeep
Syntax

member(whichCastmember).model(whichModel).cloneDeep(cloneName)
member(whichCastmember).group(whichGroup).cloneDeep(cloneName)
member(whichCastmember).light(whichLight).cloneDeep(cloneName)
member(whichCastmember).camera(whichCamera).cloneDeep(cloneName)
Description

3D command; creates a copy of the model, group, light, or camera plus all of the following:

The model resources, shaders, and textures used by the original model or group
The children of the model, group, light, or camera
The model resources, shaders, and textures used by the children
Note that cloneDeep uses more memory and takes more time than the clone command.
Example

This statement creates a copy of the model named Teapot, its children, and the model resources,
shaders, and textures used by Teapot and its children. The variable teapotCopy is a reference to
the cloned model.
teapotCopy = member("3D World").model("Teapot").cloneDeep("Teapot2")
See also

clone, cloneModelFromCastmember, cloneMotionFromCastmember, loadFile()

Lingo Dictionary 139

cloneModelFromCastmember
Syntax

member(whichCastmember).cloneModelFromCastmember\
(newModelName, sourceModelName, sourceCastmember)
Description

3D command; copies the model named sourceModelName from the cast member
sourceCastmember, renames it newModelName, and inserts it into the cast member
whichCastmember as a child of its 3D world.
This command also copies the children of sourceModelName, as well as the model resources,
shaders, and textures used by the model and its children.
The source cast member must be finished loading for this command to work correctly.
Example

This statement makes a copy of the model named Pluto of the cast member named Scene and
inserts it into the cast member named Scene2 with the new name Planet. The children of Pluto
are also imported, as are the model resources, shaders, and textures used by Pluto and its children.
member("Scene2").cloneModelFromCastmember("Planet", "Pluto", \
member("Scene"))
See also

cloneMotionFromCastmember, clone, cloneDeep, loadFile()

cloneMotionFromCastmember
Syntax

member(whichCastmember).cloneMotionFromCastmember(newMotionName, \
sourceMotionName, sourceCastmember)
Description

3D command; copies the motion named sourceMotionName from the cast member
sourceCastmember, renames it newMotionName, and inserts it into the cast member
whichCastmember.
The source cast member must be finished loading for this command to work correctly.
Example

This statement copies the motion named Walk from the cast member named ParkScene, names
the copy FunnyWalk, and puts the copy in the cast member gbMember.
member("gbMember").cloneMotionFromCastmember("FunnyWalk", \
"Walk", member("ParkScene"))
See also

map (3D), cloneModelFromCastmember, clone, cloneDeep, loadFile()

140 Chapter 3

closed
Syntax

member(whichCastMember).closed
Description

Vector shape cast member property; indicates whether the end points of a path are closed or open.
Vector shapes must be closed in order to contain a fill.
The value can be as follows:

TRUEthe

end points are closed.

FALSEthe

end points are open.

close window
Syntax

window(windowIdentifier).close()
close window windowIdentifier
Description

Window command; closes the window specified by windowIdentifier.

To specify a window by name, use the syntax close

window name,

where you replace name

with the name of a window. Use the complete pathname.

To specify a window by its number in windowList, use the syntax close

window number,

where you replace number with the windows number in windowList.

Closing a window that is already closed has no effect.
Be aware that closing a window does not stop the movie in the window nor clear it from memory.
This command simply closes the window in which the movie is playing. You can reopen it
quickly by using the open window command. This allows rapid access to windows that you want
to keep available.
If you want to completely dispose of a window and clear it from memory, use the forget window
command. Make sure that nothing refers to the movie in that window if you use the forget
window command, or you will generate errors when scripts try to communicate or interact with
the forgotten window.
Examples

This statement closes the window named Panel, which is in the subfolder MIAW Sources within
the current movies folder:
window("@/MIAW Sources/Panel").close()

This statement closes the window that is number 5 in windowList:

window(5).close()
See also

forget, open window, windowList

Lingo Dictionary

141

on closeWindow
Syntax

on closeWindow
statement(s)
end
Description

System message and event handler; contains statements that run when the user closes the window
for a movie by clicking the windows close box.
The on closeWindow handler is a good place to put Lingo commands that you want executed
every time the movies window closes.
Example

This handler tells Director to forget the current window when the user closes the window that
the movie is playing in:
on closeWindow
-- perform general housekeeping here
forget the activeWindow
end

closeXlib
Syntax

closeXlib whichFile
Description

Command; closes the Xlibrary file specified by the string whichFile. If the Xlibrary file is in a
folder other than that for the current movie, whichFile must specify a pathname. If no file is
specified, all open Xlibraries are closed.
Xtra extensions are stored in Xlibrary files. Xlibrary files are resource files that contain Xtra
extensions. HyperCard XCMDs and XFCNs can also be stored in Xlibrary files.
The closeXlib command doesnt work for URLs.
In Windows, using the DLL extension for Xtra extensions is optional.
It is good practice to close any file you have opened as soon as you have finished using it.
Note: This command is not supported in Shockwave.

Examples

This statement closes all open Xlibrary files:

closeXlib

This statement closes the Xlibrary Video Disc Xlibrary when it is in the same folder as the movie:
closeXlib "Video Disc Xlibrary"

The following statement closes the Xlibrary Transporter Xtra extensions in the folder New Xtras,
which is in the same folder as the movie. The disk is identified by the variable currentDrive:
closeXlib "@:New Xtras:Transporter Xtras"
See also

interface(), openXlib, showXlib

142 Chapter 3

collision (modifier)
Syntax

member(whichCastmember).model(whichModel).\
collision.collisionModifierProperty
Description

3D modifier; manages the detection and resolution of collisions. Adding the collision modifier
to a model by using the addModifier command allows access to the following collision
modifier properties:
enabled (collision)
resolve

indicates whether collisions with the model are detected.

indicates whether collisions with the model are resolved.

immovable

indicates whether a model can be moved from frame to frame.

mode (collision)

indicates the geometry used for collision detection.

Note: For more detailed information about these properties, see the individual property entries.

The collision modifier generates the following events. For more information about using collision
events, see the registerForEvent() entry.
A #collideAny event is generated when
collision modifier has been attached.

a collision occurs between models to which the

A #collideWith event is generated when a collision occurs with a specific model to which the
collision modifier has been attached.
The collisionData object is sent as an argument with the #collideAny and
events. See the collisionData entry for details of its properties.

#collideWith

See also

addModifier, removeModifier, modifiers

collisionData
Syntax

on myHandlerName me, collisionData

Description

3D data object; sent as an argument with the #collideWith and #collideAny events to the
handler specified in the registerForEvent, registerScript, and setCollisionCallback
commands. The collisionData object has these properties:
modelA

is one of the models involved in the collision.

modelB

is the other model involved in the collision.

pointOfContact

is the world position of the collision.

collisionNormal

is the direction of the collision.

Lingo Dictionary 143

Example

This example has three parts. The first part is the first line of code, which registers the
#putDetails handler for the #collideAny event. The second part is the #putDetails handler.
When two models in the cast member MyScene collide, the #putDetails handler is called and
the collisionData argument is sent to it. This handler displays the four properties of the
collisionData object in the message window. The third part of the example shows the results
from the message window. The first two lines show that the model named GreenBall was model A
and the model named YellowBall was model B in the collision. The third line shows the point of
contact of the two models. The last line shows the direction of the collision.
member("MyScene").registerForEvent(#collideAny, #putDetails, 0)
on putDetails me, collisionData
put collisionData.modelA
put collisionData.modelB
put collisionData.pointOfContact
put collisionData.collisionNormal
end
-----

model("GreenBall")
model("YellowBall")
vector( 24.800, 0.000, 0.000 )
vector( -1.000, 0.000, 0.000 )

See also

collisionData properties: modelA, modelB, pointOfContact, collisionNormal

collisionData methods: resolveA, resolveB, collision

(modifier)

collisionNormal
Syntax

collisionData.collisionNormal
Description

3D collisionData property; a vector indicating the direction of the collision.

The collisionData object is sent as an argument with the #collideWith and #collideAny
events to the handler specified in the registerForEvent, registerScript, and
setCollisionCallback commands.
The #collideWith and #collideAny events are sent when a collision occurs between models to
which collision modifiers have been added. The resolve property of the models modifiers must
be set to TRUE.
This property can be tested but not set.

144 Chapter 3

Example

This example has two parts. The first part is the first line of code, which registers the #explode
handler for the #collideAny event. The second part is the #explode handler. When two models
in the cast member named MyScene collide, the #explode handler is called and the
collisionData argument is sent to it. The first ten lines of the #explode handler create the
model resource SparkSource and set its properties. This model resource is a single burst of
particles. The tenth line sets the direction of the burst to collisionNormal, which is the
direction of the collision. The eleventh line of the handler creates a model called SparksModel
using the model resource SparkSource. The last line of the handler sets the position of
SparksModel to the position where the collision occurred. The overall effect is a collision that
causes a burst of sparks to fly in the direction of the collision from the point of contact.
member("MyScene").registerForEvent(#collideAny, #explode, 0)
on explode me, collisionData
nmr = member("MyScene").newModelResource("SparkSource", #particle)
nmr.emitter.mode = #burst
nmr.emitter.loop = 0
nmr.emitter.minSpeed = 30
nmr.emitter.maxSpeed = 50
nmr.emitter.angle = 45
nmr.colorRange.start = rgb(0, 0, 255)
nmr.colorRange.end = rgb(255, 0, 0)
nmr.lifetime = 5000
nmr.emitter.direction = collisionData.collisionNormal
nm = member("MyScene").newModel("SparksModel", nmr)
nm.transform.position = collisionData.pointOfContact
end
See also

pointOfContact, modelA, modelB, resolveA, resolveB, collision (modifier)

color()
Syntax

color(#rgb, redValue, greenValue, blueValue)

color(#paletteIndex, paletteIndexNumber)
rgb(rgbHexString)
rgb(redValue, greenValue, blueValue)
paletteIndex(paletteIndexNumber)
Description

Function and data type; determines an objects color as either RGB or 8-bit palette index values.
These are the same values as those used in the color member and color sprite properties, the
bgColor member and bgColor sprite properties, and the bgColor Stage property.
The color function allows for either 24-bit or 8-bit color values to be manipulated as well as
applied to cast members, sprites, and the Stage.
For RGB values, each color component has a range from 0 to 255, and all other values are
truncated. For paletteIndex types, an integer from 0 to 255 is used to indicate the index
number in the current palette, and all other values are truncated.

Lingo Dictionary 145

Examples

This statement performs a math operation:

palColorObj = paletteIndex(20)
put palColorObj
-- paletteIndex(20)
put palColorObj / 2
-- paletteIndex(10)

This statement converts one color type to another type:

newColorObj = color(#rgb, 155, 0, 75)
put newColorObj
-- rgb(155, 0, 75)
newColorObj.colorType = #paletteIndex
put newColorObj
-- paletteIndex(106)

This statement obtains the hexadecimal representation of a color regardless of its type:
someColorObj = color(#paletteIndex, 32)
put someColorObj.hexString()
-- "#FF0099"

This statement determines individual RGB components and the paletteIndex value of a color
regardless of its type:
newColorObj = color(#rgb, 155, 0, 75)
put newColorObj.green
-- 0
put newColorObj.paletteIndex
-- 106
newColorObj.green = 100
put newColorObj.paletteIndex
-- 94
put newColorObj
-- rgb(155, 100, 75)
newColorObj.paletteIndex = 45
put newColorObj
-- paletteIndex(45)

This statement changes the color of the fourth through the seventh characters of text member
myQuotes:
member("myQuotes").char[4..7].color = rgb(200, 150, 75)

This Lingo displays the color of sprite 6 in the Message window, and then sets the color of sprite
6 to a new RGB value:
put sprite(6).color
-- rgb( 255, 204, 102 )
sprite(6).color = rgb(122, 98, 210)
Note: Setting the paletteIndex value of an RGB color type changes colorType to paletteIndex. Setting
the RGB color type of a paletteIndex color sets its colorType value to RGB.

See also

bgColor

146 Chapter 3

color (fog)
Syntax

member(whichCastmember).camera(whichCamera).fog.color
sprite(whichSprite).camera{(index)}.fog.color
Description

3D property; indicates the color introduced into the scene by the camera when the cameras
fog.enabled property is set to TRUE.
The default setting for this property is rgb(0,

0, 0).

Example

This statement sets the color of the fog of the camera named BayView to rgb(255, 0, 0). If the
cameras fog.enabled property is set to TRUE, models in the fog will take on a red hue.
member("MyYard").camera("BayView").fog.color = rgb(255, 0, 0)
See also

fog

color (light)
Syntax

member(whichCastmember).light(whichLight).color
Description

3D light property; indicates the rgb value of the light.

The default value of this property is rgb(191,191,191).
Example

This statement sets the color of the light named RoomLight to rgb(255,

0, 255).

member("Room").light("RoomLight").color = rgb(255,0,255)
See also

fog

color (sprite and cast member property)

Syntax

sprite(whichSpriteNumber).color
the color of sprite whichSpriteNumber
member(whichMember).color
Description

Sprite and text cast member property; for sprites, determines the foreground color of the sprite
specified by whichSprite. Setting the foreColor sprite property is equivalent to choosing the
foreground color from the Tools window when the sprite is selected on the Stage.
This property has the equivalent functionality of the foreColor sprite property, but the color
value returned is a color object of whatever type has been set for that sprite.
For text cast members, this property determines the color of the text.

Lingo Dictionary 147

This property can be tested and set. The color property should be set to an RGB or hexidecimal
value.
Examples

This statement sets the color of the text of cast member 3 to a medium red:
member(3).color = rgb(255, 0, 100)

This statement sets the color of the text of cast member 3 to a medium blue:
member(3).color = rgb("0033FF")
See also

color(), bgColor, foreColor

colorBufferDepth
Syntax

getRendererServices().colorBufferDepth
Description

3D rendererServices property; indicates the color precision of the hardware output buffer of
the users system. The value is either 16 or 32, depending on the users hardware settings.
This property can be tested but not set.
Example

This statement shows that the colorBufferDepth value of the users video card is 32.
put getRendererServices().colorBufferDepth
-- 32
See also

getRendererServices(), getHardwareInfo(), depthBufferDepth

colorDepth
Syntax

the colorDepth
Description

System property; determines the color depth of the computers monitor.

In Windows, using this property lets you check and set the monitors color depth. Some video
card and driver combinations may not enable you to set the colorDepth property. Always
verify that the color depth has actually changed after you attempt to set it.

On the Macintosh, this property lets you check the color depth of different monitors and
change it when appropriate.
Possible values are the following:
1

Black and white

4 colors

16 colors

256 colors

148 Chapter 3

16

32,768 or 65,536 colors

32

16,777,216 colors

If you try to set a monitors color depth to a value that monitor does not support, the monitors
color depth doesnt change.
On computers with more than one monitor, the colorDepth property refers to the monitor
displaying the Stage. If the Stage spans more than one monitor, the colorDepth property
indicates the greatest depth of those monitors; colorDepth tries to set all those monitors to the
specified depth.
This property can be tested and set.
Examples

This statement tells Director to play the segment Full color only if the monitor color depth is set
to 256 colors:
if the colorDepth = 8 then play movie "Full color"

The following handler tries to change the color depth, and if it cant, it displays an alert:
on TryToSetColorDepth desiredDepth
the colorDepth = desiredDepth
if the colorDepth = desiredDepth then
return true
else
alert "Please change your system to" && desiredDepth &&"color depth and
reboot."
return false
end if
end

When changing the users monitor color depth settings, it is good practice to restore the original
depth when the movie has finished. In Windows, the command set the colorDepth = 0
restores the users preferred settings from the control panel.
See also

switchColorDepth

colorList
Syntax

member(whichCastmember).modelResource(whichModelResource).\
colorList
member(whichCastmember).modelResource(whichModelResource).\
colorList[index]
member(whichCastmember).model(whichModel).meshdeform.mesh\
[meshIndex].colorList
member(whichCastmember).model(whichModel).meshdeform.mesh\
[meshIndex].colorList[index]
Description

3D property; allows you to get or set every color used in a mesh. This command is accessible only
for model resources of the type #mesh. Any single color can be shared by several vertices (faces) of
the mesh. Alternately, you can specify texture coordinates for the faces of the mesh and apply a
shader to models that use this model resource.

Lingo Dictionary 149

This command must be set to a list of the same number of Lingo color values specified in the
newMesh call.
Example

This statement shows that the third color in the colorList of the model resource Mesh2 is
rgb(255, 0, 0).
put member("shapes").modelResource("mesh2").colorlist[3]
-- rgb(255,0,0)
See also

face, colors

colorRange
Syntax

member(whichCastmember).modelResource(whichModelResource).\
colorRange.start
member(whichCastmember).modelResource(whichModelResource).\
colorRange.end
Description

3D #particle model resource properties; indicate the beginning color and ending color of the
particles of a particle system.
The start property is the color of the particles when they are created. The end property is the
color of particles at the end of their lives. The color of each particle gradually changes from the
value of start to the value of end over the course of its life.
The start and end properties have a default value of rgb(255,

255, 255).

Example

This statement sets the colorRange properties of the model resource named ThermoSystem. The
first line sets the start value to rgb(255, 0, 0), and the second line sets the end value to
rgb(0, 0, 255). The effect of this statement is that the particles of ThermoSystem are red when
they first appear, and gradually change to blue during their lifetimes.
member(8,2).modelResource("ThermoSystem").colorRange.start = \
rgb(255,0,0)
member(8,2).modelResource("ThermoSystem").colorRange.end = \
rgb(0,0,255)
See also

emitter, blendRange, sizeRange

colors
Syntax

member(whichCastmember).modelResource(whichModelResource).\
face[faceIndex].colors
Description

3D face property; a linear list of three integers indicating which index positions of the model
resources color list to use for the three vertices of the face. The color list is a linear list of rgb values.
The colors property is used only with model resources whose type is #mesh.

150 Chapter 3

You must use the model resources build() command after setting this property; otherwise, the
changes will not take effect.
Example

This example creates a model resource whose type is #mesh, specifies its properties, and then
creates a new model with it.
Line 1 uses the newMesh() command to create a #mesh model resource named Triangle, which
has one face, three vertices, and a maximum of three colors. The number of normals and the
number of texture coordinates are not set.
Line 2 sets the vertexList property to a list of three vectors.
Line 3 assigns the vectors of the vertexList property to the vertices of the first face of Triangle.
Line 4 sets the color list to three rgb values.
Line 5 assigns colors to the first face of Triangle. The third color in the color list is applied to the
first vertex of Triangle, the second color to the second vertex, and the first color to the third
vertex. The colors will spread across the first face of Triangle in gradients.
Line 6 creates the normals of Triangle with the generateNormals() command.
Line 7 uses the build() command to construct the mesh.
Line 8 creates a new model named TriModel that uses the new mesh.
nm = member("Shapes").newMesh("Triangle",1,3,0,3,0)
nm.vertexList = [vector(0,0,0), vector(20,0,0), vector(20, 20, 0)]
nm.face[1].vertices = [1,2,3]
nm.colorList = [rgb(255,255,0), rgb(0, 255, 0), rgb(0,0,255)]
nm.face[1].colors = [3,2,1]
nm.generateNormals(#smooth)
nm.build()
nm = member("Shapes").newModel("TriModel", nm)
See also

face, vertices, colorList, flat

colorSteps
Syntax

member(whichCastmember).model(whichModel).toon.colorSteps
member(whichCastmember).model(whichModel).shader.colorSteps
member(whichCastmember).shader(whichShader).colorSteps
Description

3D toon modifier and painter shader property; the maximum number of colors available for use
by the toon modifier or painter shader. The value of this property can be 2, 4, 8, or 16. If you
set the value of colorSteps to any other number, it will be rounded to one of these.
The default value is 2.
Example

This statement limits the number of colors available for use by the toon modifier for the model
named Teapot to 8. The teapot will be rendered with a maximum of eight colors.
member("shapes").model("Teapot").toon.colorSteps = 8

Lingo Dictionary

151

See also

highlightPercentage, shadowPercentage

152 Chapter 3

commandDown
Syntax

the commandDown
Description

Function; determines whether the Control key (Windows) or the Command key (Macintosh) is
being pressed (TRUE) or not (FALSE).
You can use commandDown together with the element the key to determine when the Control or
Command key is pressed in combination with another key. This lets you create handlers that are
executed when the user presses specified Control or Command key combinations.
Control or Command key equivalents for the Director authoring menus take precedence while
the movie is playing, unless you have installed custom Lingo menus or are playing a projector
version of the movie.
For a movie playing back with the Director player for Java, this function returns TRUE only if a
second key is pressed simultaneously with the Control or Command key. If the Control or
Command key is pressed by itself, commandDown returns FALSE. This is because the browser
receives the keys before the movie and thus responds to and intercepts any key combinations that
are also browser keyboard shortcuts. For example, if the user presses Control+R or Command+R,
the browser reloads the current page; the movie never receives the key combination.
Example

These statements pause a projector whenever the user presses Control+A or Command+A. By
setting the keyDownScript property to doCommandKey, the on prepareMovie handler makes the
doCommandKey handler the first event handler executed when a key is pressed. The doCommandKey
handler checks whether the Control+A or Command+A keys are pressed at the same time and
pauses the movie if they are.
on prepareMovie
the keyDownScript = "doCommandKey"
end
on doCommandKey
if (the commandDown) and (the key = "a") then go to the frame
end
See also

controlDown, key(), keyCode(), optionDown, shiftDown

comments
Syntax

member.comments
the comments of member
Description

This cast member property provides a place to store any comments you want to maintain about
the given cast member, or any other strings you want to associate with the member. This property
can be tested and set. It can also be set in the Property inspectors Member tab.

Lingo Dictionary 153

Example

This statement sets the comments of the member Backdrop to the string Still need to license
this artwork:
member("Backdrop").comments = "Still need to license this artwork"
See also

creationDate, modifiedBy, modifiedDate

compressed
Syntax

member(whichCastmember).texture(whichTexture).compressed
Description

3D texture property; indicates whether the source cast member of the texture is compressed
(TRUE) or not (FALSE). The value of the compressed property changes automatically from TRUE
to FALSE when the texture is needed for rendering. It can be set to FALSE to decompress the
texture at an earlier time. It can be set to TRUE to release the decompressed representation from
memory. Cast members used for textures will not be compressed if this value is TRUE (apart from
the standard compression used for bitmap cast members when a Director movie is saved). The
default value for this property is TRUE.
Example

This statement sets the compressed property of the texture Plutomap to TRUE.
member("scene").texture("Plutomap").compressed = TRUE
See also

texture

constrainH()
Syntax

constrainH (whichSprite, integerExpression)

Description

Function; evaluates integerExpression and then returns a value that depends on the horizontal
coordinates of the left and right edges of whichSprite, as follows:

When the value is between the left and right coordinates, the value doesnt change.
When the value is less than the left horizontal coordinate, the value changes to the value of the
left coordinate.

When the value is greater than the right horizontal coordinate, the value changes to the value
of the right coordinate.
The constrainH and constrainV functions constrain only one axis each; the constraint sprite
property limits both. Note that this function does not change the sprites properties.

154 Chapter 3

Examples

These statements check the constrainH function for sprite 1 when it has left and right
coordinates of 40 and 60:
put constrainH(1, 20)
-- 40
put constrainH(1, 55)
-- 55
put constrainH(1, 100)
-- 60

This statement constrains a moveable slider (sprite 1) to the edges of a gauge (sprite 2) when the
mouse pointer goes past the edge of the gauge:
set the locH of sprite 1 to constrainH(2, the mouseH)
See also

constrainV(), constraint, left, right

constraint
Syntax

sprite(whichSprite).constraint
the constraint of sprite whichSprite
Description

Sprite property; determines whether the registration point of the sprite specified by whichSprite is
constrained to the bounding rectangle of another sprite (1 or TRUE) or not (0 or FALSE, default).
The constraint sprite property is useful for constraining a moveable sprite to the bounding
rectangle of another sprite to simulate a track for a slider control or to restrict where on the screen
a user can drag an object in a game.
The constraint sprite property affects moveable sprites and the locH and locV sprite properties.
The constraint point of a moveable sprite cannot be moved outside the bounding rectangle of the
constraining sprite. (The constraint point for a bitmap sprite is the registration point. The
constraint point for a shape sprite is its top left corner.) When a sprite has a constraint set, the
constraint limits override any locH and locV sprite property settings.
This property can be tested and set.
Examples

This statement removes a constraint sprite property:

Dot syntax:
sprite(whichSprite).constraint = 0

Verbose syntax:
set the constraint of sprite whichSprite to 0

This statement constrains sprite (i + 1) to the boundary of sprite 14:

sprite(i + 1).constraint = 14

This statement checks whether sprite 3 is constrained and activates the handler showConstraint
if it is (the operator <> performs a not-equal-to operation):
if sprite(3).constraint <> 0 then showConstraint

Lingo Dictionary 155

See also

constrainH(), constrainV(), locH, locV

constrainV()
Syntax

constrainV (whichSprite, integerExpression)

Description

Function; evaluates integerExpression and then returns a value that depends on the vertical
coordinates of the top and bottom edges of the sprite specified by whichSprite, as follows:

When the value is between the top and bottom coordinates, the value doesnt change.
When the value is less than the top coordinate, the value changes to the value of the top coordinate.
When the value is greater than the bottom coordinate, the value changes to the value of the
bottom coordinate.
This function does not change the sprite properties.
Examples

These statements check the constrainV function for sprite 1 when it has top and bottom
coordinates of 40 and 60:
put constrainV(1, 20)
-- 40
put constrainV(1, 55)
-- 55
put constrainV(1, 100)
-- 60

This statement constrains a moveable slider (sprite 1) to the edges of a gauge (sprite 2) when the
mouse pointer moves past the edge of the gauge:
set the locV of sprite 1 to constrainV(2, the mouseV)
See also

bottom, constraint, top, constrainH()

contains
Syntax

stringExpression1 contains stringExpression2

Description

Operator; compares two strings and determines whether stringExpression1 contains

stringExpression2 (TRUE) or not (FALSE).
The contains comparison operator has a precedence level of 1.
The contains comparison operator is useful for checking whether the user types a specific
character or string of characters. You can also use the contains operator to search one or more
fields for specific strings of characters.

156 Chapter 3

Example

This example determines whether a character passed to it is a digit:

on isNumber aLetter
digits = "1234567890"
if digits contains aLetter then
return TRUE
else
return FALSE
end if
end
Note: The string comparison is not sensitive to case or diacritical marks; a and are treated the same.

See also

offset() (string function), starts

continue
This Lingo is obsolete. Use go

to the frame +1.

controlDown
Syntax

the controlDown
Description

Function; determines whether the Control key is being pressed (TRUE) or not (FALSE).
You can use the controlDown function together with the
Control key and another key.

key

to check for combinations of the

For a movie playing back with the Director player for Java, this function returns TRUE only if a
second key is pressed simultaneously with the Control key. If the Control key is pressed by itself,
controlDown returns FALSE. The Director player for Java supports key combinations with the
Control key. However, the browser receives the keys before the movie and thus responds to and
intercepts any key combinations that are also browser keyboard shortcuts.
For a demonstration of modifier keys and Lingo, see the sample movie Keyboard Lingo in
Director Help.
Example

This on keyDown handler checks whether the pressed key is the Control key, and if it is, the
handler activates the on doControlKey handler. The argument (the key) identifies which key
was pressed in addition to the Control key.
on keyDown
if (the controlDown)then doControlKey (the key)
end
See also

charToNum(), commandDown, key(), keyCode(), optionDown, shiftDown

Lingo Dictionary 157

controller
Syntax

member(whichCastMember).controller
the controller of member whichCastMember
Description

Digital video cast member property; determines whether a digital video movie cast member shows
or hides its controller. Setting this property to 1 shows the controller; setting it to 0 hides the
controller.
The controller member property applies to a QuickTime digital video only.

Setting the

controller member property for a Video for Windows digital video performs no
operation and generates no error message.

Checking the controller member property for a Video for Windows digital video always
returns FALSE.
The digital video must be in direct-to-stage playback mode to display the controller.
Example

This statement causes the QuickTime cast member Demo to display its controller.
Dot syntax:
member("Demo").controller = 1

Verbose syntax:
set the controller of member "Demo" to 1
See also

directToStage

copyPixels()
Syntax

imageObject.copyPixels(sourceImageObject, destinationRect, sourceRect

{, parameterList})
imageObject.copyPixels(sourceImageObject, destinationQuad, sourceRect
{, parameterList })
Description

This function copies the contents of the sourceRect from the sourceImageObject into the
given imageObject. The pixels are copied from the sourceRect in the sourceImageObject and
placed into the destinationRect or destinationQuad in the given imageObject. See quad for
information on using quads.

158 Chapter 3

You can include an optional property list of parameters in order to manipulate the pixels being
copied before they are placed into the destinationRect. The property list may contain any or all
of the following parameters:
Property

Use and Effect

#color

The foreground color to apply for colorization effects. The default color is black.

#bgColor

The background color to apply for colorization effects or background transparency. The
default background color is white.

#ink

The type of ink to apply to the copied pixels. This can be an ink symbol or the corresponding
numeric ink value. The default ink is #copy. See ink for the list of possible values.

#blendLevel

The degree of blend (transparency) to apply to the copied pixels. The range of values is
from 0 to 255. The default value is 255 (opaque). Using a value less than 255 forces the
#ink setting to be #blend, or #blendTransparent if it was originally
#backgroundTransparent. You may also substitute #blend as the property name and use a
value range of 0 to 100. See blend for more information.

#dither

A TRUE or FALSE value that determines whether the copied pixels will be dithered when
placed into the destinationRect in 8- and 16-bit images. The default value is FALSE,
which maps the copied pixels directly into the imageObjects color palette.

#useFastQuads

A TRUE or FALSE value that determines whether quad calculations are made using the
faster but less precise method available in Director when copying pixels into a
destinationQuad. Set this to TRUE if you are using quads for simple rotation and skew
operations. Leave it FALSE (the default value) for arbitrary quads, such as those used for
perspective transformations. See useFastQuads.

#maskImage

Used to specified a mask or matte object created with the createMask() or

createMatte() functions to be used as a mask for the pixels being copied. This allows you
to duplicate the effects of mask and matte sprite inks. Note that if the source image has an
alpha channel and its useAlpha property is TRUE, the alpha channel is used and the
specified mask or matte is ignored. The default is no mask.

#maskOffset

A point indicating the amount of x and y offset to apply to the mask specified by
#maskImage. The offset is relative to the upper left corner of the sourceImage. The default
offset is (0, 0).

When copying pixels from one area of a cast member to another area of the same member, it is
best to copy the pixels first into a duplicate image object before copying them back into the
original member. Copying directly from one area to another in the same image is not
recommended. See duplicate().
To simulate matte ink with copyPixels(), create a matte object with createMatte() and then
pass that object as the #maskImage parameter with copyPixels().
Copying pixels from an image object into itself is not recommended. Use separate image
objects instead.
To see an example of quad used in a completed movie, see the Quad movie in the Learning/Lingo
Examples folder inside the Director application folder.
Examples

This statement copies the entire image of member Happy into the rectangle of member flower. If
the members are different sizes, the image of member Happy will be resized to fit the rectangle of
member flower.
member("flower").image.copyPixels(member("Happy").image,
member("flower").rect, member("Happy").rect)

Lingo Dictionary 159

The following statement copies part of the image of member Happy into part of member flower.
The part of the image copied from Happy is within rectangle(0, 0, 200, 90). It is pasted into
rectangle(20, 20, 100, 40) within the image of member flower. The copied portion of Happy is
resized to fit the rectangle into which it is pasted.
member("flower").image.copyPixels(member("Happy").image,\
rect(20, 20, 100, 40), rect(0, 0, 200, 90))

The following statement copies the entire image of member Happy into a rectangle within the
image of member flower. The rectangle into which the copied image of member Happy is pasted
is the same size as the rectangle of member Happy, so the copied image is not resized. The blend
level of the copied image is 50, so it is semi-transparent, revealing the part of member flower it is
pasted over.
member("flower").image.copyPixels(member("Happy").image,\
member("Happy").rect, member("Happy").rect, [#blendLevel: 50])
See also

ink, color()

copyrightInfo
Syntax

member(whichCastMember).copyrightInfo
copyrightInfo of member whichCastMember
Description

Shockwave Audio (SWA) cast member property; displays the copyright text in a SWA file. This
property is available only after the SWA sound begins playing or after the file has been preloaded
using the preLoadBuffer command.
This property can be tested and set.
Example

This statement tells Director to display the copyright information for the Shockwave Audio file
SWAfile in a field cast member named Info Display.
Dot syntax:
set whatState = the state of member "SWAfile"
if whatState > 1 AND whatState < 9 then
put member("SWAfile").copyrightInfo into member("Info Display")
end if

Verbose syntax:
set whatState = the state of member "SWAfile"
if whatState > 1 AND whatState < 9 then
put the copyrightInfo of member "SWAfile" into member "Info Display"
end if

160 Chapter 3

copyToClipBoard
Syntax

member(whichCastMember).copyToClipBoard()
copyToClipBoard member whichCastMember
Description

Command; copies the specified cast member to the Clipboard without requiring that the cast
window is active. You can use this command to copy cast members between movies or applications.
Examples

This statement copies the cast member named chair to the Clipboard:
member("chair").copyToClipboard()

This statement copies cast member number 5 to the Clipboard:

member(5).copyToClipboard()
See also

pasteClipBoardInto

cos()
Syntax

(angle).cos
cos (angle)
Description

Function; calculates the cosine of the specified angle, which must be expressed in radians.
Example

The following statement calculates the cosine of PI divided by 2 and displays it in the
Message window:
put (PI/2).cos
See also

atan(), PI, sin()

count()
Syntax

list.count
count (list)
count(theObject)
object.count
textExpression.count
Description

Function; returns the number of entries in a linear or property list, the number of properties in a
parent script without counting the properties in an ancestor script, or the chunks of a text
expression such as characters, lines, or words.
The count command works with linear and property lists, objects created with parent scripts, and
the globals property.

Lingo Dictionary

161

To see an example of count() used in a completed movie, see the Text movie in the Learning/
Lingo Examples folder inside the Director application folder.
Example

This statement displays the number 3, the number of entries:

put [10,20,30].count
-- 3
See also

globals

count
Syntax

member(whichCastmember).light.count
member(whichCastmember).camera.count
member(whichCastmember).modelResource(whichModelResource).\
bone.count
member(whichCastmember).model.count
member(whichCastmember).group.count
member(whichCastmember).shader.count
member(whichCastmember).texture.count
member(whichCastmember).modelResource.count
member(whichCastmember).motion.count
member(whichCastmember).light.child.count
member(whichCastmember).camera.child.count
member(whichCastmember).model.child.count
member(whichCastmember).group.child.count
sprite(whichSprite).camera{(index)}.backdrop.count
member(whichCastmember).camera(whichCamera).backdrop.count
sprite(whichSprite).camera{(index)}.overlay.count
member(whichCastmember).camera(whichCamera).overlay.count
member(whichCastmember).model(whichModel).modifier.count
member(whichCastmember).model(whichModel).keyframePlayer.\
playlist.count
member(whichCastmember).model(whichModel).bonesPlayer.\
playlist.count
member(whichCastmember).modelResource(whichModelResource).\
face.count
member(whichCastmember).model(whichModel).meshDeform.\
mesh[index].textureLayer.count
member(whichCastmember).model(whichModel).meshDeform.mesh.count
member(whichCastmember).model(whichModel).meshDeform.\
mesh[index].face.count
Description

3D property; returns the number of items in the given list that is associated with the given 3D
object. Can be used with any type of object.
The face.count property allows you to get the number of triangles in the mesh for a model
resource whose type is #mesh.
This property can be tested but not set.

162 Chapter 3

Examples

These examples determine the number of various types of objects within a 3D cast member called
3D World.
numberOfCameras = member("3D World").camera.count
put member("3D World").light.count
-- 3
numberOfModels = member("3D World").model.count
numberOfTextures = member("3D World").texture.count
put member("3D World").modelResource("mesh2").face.count
-- 4

This statement shows that the first mesh of the model named Ear is composed of 58 faces.
put member("Scene").model("Ear").meshdeform.mesh[1].face.count
-- 58

This statement shows that the model named Ear is composed of three meshes.
put member("Scene").model("Ear").meshdeform.mesh.count
-- 3

This statement shows that the first mesh of the model named Ear has two texture layers.
put member("Scene").model("Ear").meshdeform.mesh[1].\
textureLayer.count
-- 2
See also

cameraCount()

cpuHogTicks
Syntax

the cpuHogTicks
Description

System property; determines how often Director releases control of the CPU to let the computer
process background events, such as events in other applications, network events, clock updates,
and other keyboard events.
The default value is 20 ticks. To give more time to Director before releasing the CPU to
background events or to control how the computer responds to network operations, set
cpuHogTicks to a higher value.
To create faster auto-repeating key performance but slower animation, set cpuHogTicks to a
lower value. In a movie, when a user holds down a key to generate a rapid sequence of autorepeating key presses, Director typically checks for auto-repeating key presses less frequently than
the rate set in the computers control panel.
The cpuHogTicks property works only on the Macintosh.
Example

This statement tells Director to release control of the CPU every 6 ticks, or every 0.10 of a second:
the cpuHogTicks = 6
See also

ticks

Lingo Dictionary 163

creaseAngle
Syntax

member(whichCastmember).model(whichModel).inker.creaseAngle
member(whichCastmember).model(whichModel).toon.creaseAngle
Description

3D inker and toon modifier property; indicates the sensitivity of the line drawing function of
the modifier to the presence of creases in the models geometry. Higher settings result in more
lines (detail) drawn at creases.
The creases property of the modifier must be set to TRUE for the creaseAngle property to
have an effect.
CreaseAngle

has a range of -1.0 to +1.0. The default setting is 0.01.

Example

This statement sets the creaseAngle property of the inker modifier applied to the model named
Teapot to 0.10. A line will be drawn at all creases in the model that exceed this threshold. This
setting will only take effect if the inker modifiers creases property is set to TRUE.
member("shapes").model("Teapot").inker.creaseAngle = 0.10
See also

creases, lineColor, lineOffset, useLineOffset

creases
Syntax

member(whichCastmember).model(whichModel).inker.creases
member(whichCastmember).model(whichModel).toon.creases
Description

3D toon and inker modifier property; determines whether lines are drawn at creases in the
surface of the model.
The default setting for this property is TRUE.
Example

This statement sets the creases property of the inker modifier for the model named Teapot to
TRUE. A line will be drawn on all creases in the model that exceed the threshold set by the inker
modifiers creaseAngle property.
member("shapes").model("Teapot").inker.creases = TRUE
See also

creaseAngle, lineColor, lineOffset, useLineOffset

164 Chapter 3

createMask()
Syntax

imageObject.createMask()
Description

This function creates and returns a mask object for use with the copyPixels() function.
Mask objects arent image objects; theyre useful only with the copyPixels() function for
duplicating the effect of mask sprite ink. To save time, if you plan to use the same image as a mask
more than once, its best to create the mask object and save it in a variable for reuse.
Example

This statement copies the entire image of member Happy into a rectangle within the image of
member brown square. Member gradient2 is used as a mask with the copied image. The mask is offset
by 10 pixels up and to the left of the rectangle into which the image of member Happy is pasted.
member("brown square").image.copyPixels(member("Happy").image, \
rect(20, 20, 150, 108), member("Happy").rect, \
[#maskImage:member("gradient2").image.createMask(), maskOffset:point(-10, 10)])
See also

copyPixels(), createMatte(), ink

createMatte()
Syntax

imageObject.createMatte({alphaThreshold})
Description

This function creates and returns a matte object that you can use with copyPixels() to duplicate
the effect of the matte sprite ink. The matte object is created from the specified image objects
alpha layer. The optional parameter alphaThreshold excludes from the matte all pixels whose
alpha channel value is below that threshold. It is used only with 32-bit images that have an alpha
channel. The alphaThreshold must be a value between 0 and 255.
Matte objects arent image objects; they are useful only with the copyPixels() function. To save
time, if you plan to use the same image as a matte more than once, its best to create the matte and
save it in a variable for reuse.
Example

This statement creates a new matte object from the alpha layer of the image object testImage and
ignores pixels with alpha values below 50%:
newMatte = testImage.createMatte(128)
See also

copyPixels(), createMask()

Lingo Dictionary 165

creationDate
Syntax

member.creationDate
the creationDate of member
Description

This cast member property records the date and time that the cast member was first created, using
the system time on the computer. You can use this property to schedule a project; Director doesnt
use it for anything.
This property can be tested and set.
Example

Although you typically inspect the creationDate property using the Property inspector or the
Cast window list view, you can check it in the Message window:
put member(1).creationDate
-- date( 1999, 12, 8 )
See also

comments, modifiedBy, modifiedDate

crop() (image object command)

Syntax

imageObject.crop(rectToCropTo)
Description

When used with an image object, returns a new image object that contains a copy of the given
image object, cropped to the given rect. The original image object is unchanged. The new image
object does not belong to any cast member and has no association with the Stage. If you wish to
assign it to a cast member you can do so by setting the image property of that cast member.
This is different from using crop with a cast member, which crops the cast member itself, altering
the original.
Examples

This Lingo takes a snapshot of the Stage and crops it to the rect of sprite 10, capturing the
current appearance of that sprite on the Stage:
set stageImage = (the stage).image
set spriteImage = stageImage.crop(sprite(10).rect)
member("sprite snapshot").image = spriteImage

This statement uses the rectangle of cast member Happy to crop the image of cast member
Flower, then sets the image of cast member Happy to the result:
member("Happy").image = member("Flower").image.crop(member("Happy").rect)

166 Chapter 3

crop() (member command)

Syntax

member(whichMember).crop(rectToCropTo)
crop member whichMember, rectToCropTo
Description

Bitmap command; allows a bitmap cast member to be cropped to a specific size.

You can use crop to trim existing cast members, or in conjunction with the picture of the Stage to
grab a snapshot and then crop it to size for display.
The registration point is kept in the same location so the bitmap does not move in relation to the
original position.
Example

This statement sets an existing bitmap member to a snapshot of the Stage, then crops the
resulting image to a rectangle equal to sprite 10:
member("stage image").picture = (the stage).picture
member("stage image").crop(sprite(10).rect)
See also

picture (cast member property)

crop (cast member property)

Syntax

member(whichCastMember).crop
the crop of member whichCastMember
Description

Cast member property; scales a digital video cast member to fit exactly inside the sprite rectangle
in which it appears (FALSE), or it crops but doesnt scale the cast member to fit inside the sprite
rectangle (TRUE).
This property can be tested and set.
Example

This statement instructs Lingo to crop any sprite that refers to the digital video cast member
Interview.
Dot syntax:
member("Interview").crop = TRUE

Verbose syntax:
set the crop of member "Interview" to TRUE
See also

center

Lingo Dictionary 167

cross
Syntax

vector1.cross(vector2)
Description

3D vector method; returns a vector which is perpendicular to both vector1 and vector2.
Example

In this example, pos1 is a vector on the x axis and pos2 is a vector on the y axis. The value
returned by pos1.cross(pos2) is vector( 0.0000, 0.0000, 1.00000e4 ), which is
perpendicular to both pos1 and pos2.
pos1 = vector(100, 0, 0)
pos2 = vector(0, 100, 0)
put pos1.cross(pos2)
-- vector( 0.0000, 0.0000, 1.00000e4 )
See also

crossProduct(), perpendicularTo

crossProduct()
Syntax

vector1.crossProduct(vector2)
Description

3D vector method; returns a vector which is perpendicular to both vector1 and vector2.
Example

In this example, pos1 is a vector on the x axis and pos2 is a vector on the y axis. The value
returned by pos1.crossProduct(pos2) is vector( 0.0000, 0.0000, 1.00000e4 ), which is
perpendicular to both pos1 and pos2.
pos1 = vector(100, 0, 0)
pos2 = vector(0, 100, 0)
put pos1.crossProduct(pos2)
-- vector( 0.0000, 0.0000, 1.00000e4 )
See also

perpendicularTo, cross

on cuePassed
Syntax

on cuePassed(channelID, cuePointNumber,cuePointName)
statement(s)
end
on cuePassed(me,channelID, cuePointNumber,cuePointName)
statement(s)
end

168 Chapter 3

Description

System message and event handler; contains statements that run each time a sound or sprite
passes a cue point in its media.

meThe optional me parameter is the scriptInstanceRef value of the script being invoked.
You must include this parameter when using the message in a behavior. If this parameter is
omitted, the other arguments will not be processed correctly.

channelIDThe number of the sound or sprite channel for the file where the cue
point occurred.

cuePointNumberThe ordinal number of the cue point that triggers the event in the list of
the cast members cue points.

cuePointNameThe

name of the cue point that was encountered.

The message is passedin orderto sprite, cast member, frame, and movie scripts. For the sprite
to receive the event, it must be the source of the sound, like a QuickTime movie or SWA cast
member. Use the isPastCuePoint property to check cues in behaviors on sprites that dont
generate sounds.
Example

This handler placed in a Movie or Frame script reports any cue points in sound channel 1 to the
Message window:
on cuePassed channel, number, name
if (channel = #Sound1) then
put "CuePoint" && number && "named" && name && "occurred in sound 1"
end if
end
See also

scriptInstanceList, cuePointNames, cuePointTimes, isPastCuePoint()

cuePointNames
Syntax

member(whichCastMember).cuePointNames
the cuePointNames of member whichCastMember
Description

Cast member property; creates list of cue point names, or if a cue point is not named, inserts an
empty string ("") as a placeholder in the list. Cue point names are useful for synchronizing sound,
QuickTime, and animation.
This property is supported by SoundEdit cast members, QuickTime digital video cast members,
and Xtra extension cast members that contain cue points. Xtra extensions that generate cue points
at run time may not be able to list cue point names.
Example

This statement obtains the name of the third cue point of a cast member.
Dot syntax:
put member("symphony").cuePointNames[3]

Verbose syntax:
put (getAt(the cuePointNames of member "symphony",3))

Lingo Dictionary 169

See also

cuePointTimes, mostRecentCuePoint

cuePointTimes
Syntax

member(whichCastMember).cuePointTimes
the cuePointTimes of member whichCastMember
Description

Cast member property; lists the times of the cue points, in milliseconds, for a given cast member.
Cue point times are useful for synchronizing sound, QuickTime, and animation.
This property is supported by SoundEdit cast members, QuickTime digital video cast members,
and Xtra extension cast members that support cue points. Xtra extensions that generate cue points
at run time may not be able to list cue point names.
Example

This statement obtains the time of the third cue point for a sound cast member.
Dot syntax:
put member("symphony").cuePointTimes[3]

Verbose syntax:
put (getAt(the cuePointTimes of member "symphony",3))
See also

cuePointNames, mostRecentCuePoint

currentLoopState
Syntax

member(whichCastmember).model(whichModel).keyframePlayer.\
currentLoopState
member(whichCastmember).model(whichModel).bonesPlayer.\
currentLoopState
Description

3D keyframePlayer and bonesPlayer modifier property; indicates whether the motion being
executed by the model repeats continuously (TRUE) or plays to the end and is replaced by the next
motion in the modifiers playlist (FALSE).
The default setting for this property is the value of the looped parameter of the play() command
that initiated playback of the motion, or the value of the queue() command that added the
motion to the modifiers playlist. Changing the currentLoopState property also changes the
value of the #looped property of the motions entry in the modifiers playlist.
Example

This statement causes the motion that is being executed by the model named Monster to repeat
continuously.
member("NewAlien").model("Monster").keyframePlayer.\
currentLoopState = TRUE

170 Chapter 3

See also

loop (cast member property), play() (3D), queue() (3D), playlist

currentSpriteNum
Syntax

the currentSpriteNum
Description

Movie property; indicates the channel number of the sprite whose script is currently running. It
is valid in behaviors and cast member scripts. When used in frame scripts or movie scripts, the
currentSpriteNum propertys value is 0.
The currentSpriteNum property is similar to spriteNum
reference.

of me,

but it doesnt require the

me

This property can be tested but not set.

Note: This property was more useful during transitions from older movies to Director 6, when behaviors were
introduced. It allowed some behavior-like functionality without having to completely rewrite Lingo code. It is not
necessary when authoring with behaviors and is therefore less useful than in the past.

Example

The following handler in a cast member or movie script switches the cast member assigned to the
sprite involved in the mouseDown event:
on mouseDown
sprite(the currentSpriteNum).member = member "DownPict"
end
See also

me, spriteNum

currentTime
Syntax

sprite(whichSprite).currentTime
the currentTime of sprite whichSprite
sound(channelNum).currentTime
Description

Sprite and sound channel property; returns the current playing time, in milliseconds, for a sound
sprite, QuickTime digital video sprite, or any Xtra that supports cue points. For a sound channel,
returns the current playing time of the sound member currently playing in the given sound channel.
This property can be tested, but can only be set for traditional sound cast members (WAV, AIFF,
SND). When this property is set, the range of allowable values is from zero to the duration of
the member.
Shockwave Audio (SWA) sounds can appear as sprites in sprite channels, but they play sound in a
sound channel. You should refer to SWA sound sprites by their sprite channel number rather than
by a sound channel number.
Example

This statement displays the current time, in seconds, of the sound sprite in sprite channel 10.

Lingo Dictionary

171

Dot syntax:
member("time").text = string(sprite (10).currentTime/ 1000)

Verbose syntax:
set the text of member "time" to (the currentTime of sprite 10) / 1000

This statement causes the sound playing in sound channel 2 to skip to the point 2.7 seconds from
the beginning of the sound cast member:
sound(2).currentTime = 2700
See also

movieTime, duration

currentTime (3D)
Syntax

member(whichCastmember).model(whichModel).keyframePlayer.\
currentTime
member(whichCastmember).model(whichModel).bonesPlayer.\
currentTime
Description

3D keyframePlayer and bonesPlayer modifier property; indicates the local time of the motion
being executed by the model. The currentTime property is measured in milliseconds, but it only
corresponds to real time when the motion is playing at its original speed.
Playback of a motion by a model is the result of either a play() or queue() command. The
scale parameter of the play() or queue() command is multiplied by the modifiers playRate
property, and the resulting value is multiplied by the motions original speed to determine how
fast the model will execute the motion and how fast the motions local time will run. So if the
scale parameter has a value of 2 and the modifiers playRate property has a value of 3, the
model will execute the motion six times as fast as its original speed and local time will run six
times as fast as real time.
The currentTime property resets to the value of the cropStart parameter
queue() command at the beginning of each iteration of a looped motion.

of the play() or

Example

This statement shows the local time of the motion being executed by the model named Alien3.
put member("newalien").model("Alien3").keyframePlayer.currentTime
-- 1393.8599
See also

play() (3D), queue() (3D), playlist

currentTime (RealMedia)
Syntax

sprite(whichSprite).currentTime
member(whichCastmember).currentTime
sprite(whichSprite).currentTime = timeInMilliseconds
member(whichCastmember).currentTime = timeInMilliseconds

172 Chapter 3

Description

RealMedia sprite or cast member property; allows you to get or set the current time of the
RealMedia stream, in milliseconds. If the RealMedia cast member is not playing, the value of this
property is 0, which is the default setting. This is a playback property, and it is not saved.
If the stream is playing when the currentTime property is set or changed, a seek action takes
place, the stream rebuffers, and then playback resumes at the new time. If the stream is paused
(#paused mediaStatus value) when currentTime is set or changed, the stream redraws the
frame at the new time, and it resumes playback if pausedAtStart is set to FALSE. When the
stream is paused or stopped in the RealMedia viewer, mediaStatus is #paused. When the stream
is stopped by the Lingo stop command, mediaStatus is #closed. This property has no effect if
the streams mediaStatus value is #closed. When you set integer values, they are clipped to the
range from 0 to the duration of the stream.
Setting currentTime is equivalent to invoking
x.currentTime = n. Changing currentTime

the seek command: x.seek(n) is the same as

or calling seek will require the stream to be

rebuffered.
Examples

The following examples show that the current time of the sprite 2 and the cast member Real is
15,534 milliseconds (15.534 seconds) from the beginning of the stream.
put sprite(2).currentTime
-- 15534
put member("Real").currentTime
-- 15534

The following examples cause playback to jump 20,000 milliseconds (20 seconds) into the stream
of sprite 2 and the cast member Real.
sprite(2).currentTime = 20000
member("Real").currentTime = 20000
See also

duration (RealMedia), seek, mediaStatus

cursor (command)
Syntax

cursor [castNumber, maskCastNumber]

cursor whichCursor
cursor (member whichCursorCastMember)
Description

Command; changes the cast member or built-in cursor that is used for a cursor and stays in effect
until you turn it off by setting the cursor to 0.

Use the syntax cursor

[castNumber, maskCastNumber] to specify the number of a cast

member to use as a cursor and its optional mask. The cursors hot spot is the registration point
of the cast member.

Lingo Dictionary 173

The cast member that you specify must be a 1-bit cast member. If the cast member is larger
than 16 by 16 pixels, Director crops it to a 16-by-16-pixel square, starting in the upper left
corner of the image. The cursors hot spot is still the registration point of the cast member.

Use the syntax cursor whichCursor to specify default system cursors. The term whichCursor
must be one of the following integer values:
0*

No cursor set

-1

Arrow (pointer) cursor

I-beam cursor

Crosshair cursor

3*

Crossbar cursor

Watch cursor (Macintosh only)

200*
*

Blank cursor (hides cursor)

The Director player for Java does not support these cursor types and displays an arrow cursor instead.

Use the syntax cursor

(member whichCursorCastMember)

for the custom cursors available

through the Cursor Xtra.

Be sure not to confuse the syntax cursor 1 with cursor [1]. The first selects the I-beam from
the system cursor set; the second uses cast member 1 as the custom cursor.
Note: Although the Cursor Xtra allows cursors of different cast types, text cast members cannot be used as cursors.

During system events such as file loading, the operating system may display the watch cursor and
then change to the pointer cursor when returning control to the application, overriding the
cursor command settings from the previous movie. To use cursor at the beginning of any new
movie that is loaded in a presentation using a custom cursor for multiple movies, store any special
cursor resource number as a global variable that remains in memory between movies.
Cursor commands can be interrupted by an Xtra or other external agent. If the cursor is set to a
value in Director and an Xtra or external agent takes control of the cursor, resetting the cursor to
the original value has no effect because Director doesnt perceive that the cursor has changed. To
work around this, explicitly set the cursor to a third value and then reset it to the original value.
Example

This statement changes the cursor to a watch cursor on the Macintosh, and hourglass in
Windows, whenever the value in the variable named status equals 1:
if status = 1 then cursor 4

This handler checks whether the cast member assigned to the variable is a 1-bit cast member and
then uses it as the cursor if it is:
on myCursor someMember
if the depth of member someMember = 1 then
cursor[someMember]
else
beep
end if
end
See also

cursor (sprite property), rollOver()

174 Chapter 3

cursor (sprite property)

Syntax

sprite(whichSprite).cursor = [castNumber, maskCastNumber]

set the cursor of sprite whichSprite to [castNumber, maskCastNumber]
sprite(whichSprite).cursor = whichCursor
set the cursor of sprite whichSprite to whichCursor
Description

Sprite property; determines the cursor used when the pointer is over the sprite specified by the
integer expression whichSprite. This property stays in effect until you turn it off by setting the
cursor to 0. Use the cursor sprite property to change the cursor when the mouse pointer is over
specific regions of the screen and to indicate regions where certain actions are possible when the
user clicks on them.
When you set the cursor sprite property in a given frame, Director keeps track of the sprite
rectangle to determine whether to alter the cursor. This rectangle persists when the movie enters
another frame unless you set the cursor sprite property for that channel to 0.

Use the syntax cursor

of sprite...[castNumber, maskCastNumber]

to specify the

number of a cast member to use as a cursor and its optional mask.

Use the syntax cursor

of sprite...whichCursor to specify default system cursors. The

term whichCursor must be one of the following integer values:

0*

No cursor set

-1

Arrow (pointer) cursor

I-beam cursor

Crosshair cursor

3*

Crossbar cursor

Watch cursor (Macintosh only)

200*
*

Blank cursor (hides cursor)

The Director player for Java does not support these cursor types and displays an arrow cursor instead.

To use custom cursors, set the cursor sprite property to a list containing the cast member to be
used as a cursor or to the number that specifies a system cursor. In Windows, a cursor must be a
cast member, not a resource; if a cursor is not available because it is a resource, Director displays
the standard arrow cursor instead. For best results, dont use custom cursors when creating crossplatform movies.
If the sprite is a bitmap that has matte ink applied, the cursor changes only when the cursor is
over the matte portion of the sprite.
When the cursor is over the location of a sprite that has been removed, rollover still occurs. Avoid
this problem by not performing rollovers at these locations or by relocating the sprite up above
the menu bar before deleting it.
On the Macintosh, you can use a numbered cursor resource in the current open movie file as the
cursor by replacing whichCursor with the number of the cursor resource.
This property can be tested and set.

Lingo Dictionary 175

Example

This statement changes the cursor that appears over sprite 20 to a watch cursor.
Dot syntax:
sprite(20).cursor = 4

Verbose syntax:
set the cursor of sprite 20 to 4
See also

cursor (command)

cursorSize
Syntax

member(whichCursorCastMember).cursorSize
the cursorSize of member whichCursorCastMember
Description

Cursor cast member property; specifies the size of the animated color cursor cast member
whichCursorCastMember.
Specify size:

For cursors up to:

16

16 by 16 pixels

32

32 by 32 pixels

Bitmap cast members smaller than the specified size are displayed at full size, and larger ones are
scaled proportionally to the specified size.
The default value is 32 for Windows and 16 for the Macintosh. If you set an invalid value, an
error message appears when the movie runs (but not when you compile).
This property can be tested and set.
Example

This command resizes the animated color cursor stored in cast member 20 to 32 by 32 pixels.
Dot syntax:
member(20).cursorSize = 32

Verbose syntax:
set the cursorSize of member 20 = 32

176 Chapter 3

curve
Syntax

member.curve[curveListIndex]
Description

This property contains the vertexList of an individual curve (shape) from a vector shape cast
member. You can use the curve property along with the vertex property to get individual vertices
of a specific curve in a vector shape.
A vertexList is a list of vertices, and each vertex is a property list containing up to three
properties: a #vertex property with the location of the vertex, a #handle1 property with the
location of the first control point for that vertex, and a #handle2 property with the location of the
second control point for that vertex. See vertexList.
Examples

This statement displays the list of vertices of the third curve of vector shape member
SimpleCurves:
put member("SimpleCurves").curve[3]
-- [[#vertex: point(113.0000, 40.0000), #handle1: point(32.0000, 10.0000),
#handle2: point(-32.0000, -10.0000)], [#vertex: point(164.0000, 56.0000)]]

This statement moves the first vertex of the first curve in a vector shape down and to the right by
10 pixels:
member(1).curve[1].vertex[1] = member(1).curve[1].vertex[1] + point(10, 10)

The following code moves a sprite to the location of the first vertex of the first curve in a vector
shape. The vector shapes originMode must be set to #topLeft for this to work.
vertexLoc = member(1).curve[1].vertex[1]
spriteLoc = mapMemberToStage(sprite(3), vertexLoc)
sprite(7).loc = spriteLoc
vertex, vertexList

date() (system clock)

Syntax

the
the
the
the
the
the

abbr date
abbrev date
abbreviated date
date
long date
short date

Description

Function; returns the current date in the system clock in one of three formats: abbreviated,
long, or short (default). The abbreviated format can also be referred to as abbrev and abbr.
In Java, the date function is available, but it doesnt accept abbrev, long, or short modifiers.
When the movie plays back as an applet, the dates format is MM/DD/YY, where MM represents the
month, DD represents the day, and YY represents the last two digits of the current year. For the
months January through September, the value for MM is a single digit.

Lingo Dictionary 177

The format Director uses for the date varies, depending on how the date is formatted on
the computer.

In Windows, you can customize the date display by using the International control panel.
(Windows stores the current short date format in the System.ini file. Use this value to
determine what the parts of the short date indicate.)

On the Macintosh, you can customize the date display by using the Date and Time control panel.
Examples

This statement displays the abbreviated date:

put the abbreviated date
-- "Sat, Sep 7, 1991"

This statement displays the long date:

put the long date
-- "Saturday, September 7, 1991"

This statement displays the short date:

put the short date
-- "9/7/91"

This statement tests whether the current date is January 1 by checking whether the first four
characters of the date are 1/1. If it is January 1, the alert Happy New Year! appears:
if char 1 to 4 of the date = "1/1/" then alert "Happy New Year!"
Note: The three date formats vary, depending on the country for which your operating system was designed. These
examples are for the United States. Use the date object to create and manipulate dates in a standard format.

See also

time(), date() (formats), systemDate

date() (formats)
Syntax

date(ISOFormatString)
date(ISOFormatInteger)
date(ISOFormatIntegerYear, ISOFormatIntegerMonth, ISOFormatIntegerDay)
Description

Function and data type; creates a standard, formatted date object instance for use with other date
object instances in arithmetic operations and for use in manipulating dates across platforms and
in international formats.
When creating the date, use four digits for the year, two digits for the month, and two digits for
the day. The following expressions are equivalent:
integer:

set vacationStart = date(19980618)

string:

set vacationStart = date("19980618")

comma separated:

set vacationStart = date(1998, 06, 18)

Addition and subtraction operations on the date are interpreted as the addition and subtraction
of days.

178 Chapter 3

The individual properties of the date object instance returned are:

#year

Integer representing the year

#month

Integer representing the month of the year

#day

Integer representing the day of the month

Examples

These statements create and determine the number of days between two dates:
myBirthDay = date(19650712)
yourBirthDay = date(19450529)
put "There are" && abs(yourBirthday - myBirthday) && "days between our
birthdays."

These statements access an individual property of a date:

myBirthDay = date(19650712)
put "I was born in month number"&&myBirthday.month
See also

date() (system clock)

deactivateApplication
Syntax

on deactivateApplication
Description

Built-in handler; runs when the projector is sent to the background. This handler is useful when a
projector runs in a window and the user can send it to the background to work with other
applications. Any MIAWs running in the projector can also make use of this handler.
During authoring, this handler is called only if Animate in Background is turned on in General
Preferences.
On Windows, this handler is not called if the projector is merely minimized and no other
application is brought to the foreground.
Example

This handler plays a sound each time the user sends the projector to the background:
on deactivateApplication
sound(1).queue(member("closeSound"))
sound(1).play()
end
See also

add (3D texture), activeCastLib, on deactivateWindow

Lingo Dictionary 179

on deactivateWindow
Syntax

on deactivateWindow
statement(s)
end
Description

System message and event handler; contains statements that run when the window that the movie
is playing in is deactivated. The on deactivate event handler is a good place for Lingo that you
want executed whenever a window is deactivated.
Example

This handler plays the sound Snore when the window that the movie is playing in is deactivated:
on deactivateWindow
puppetSound 2, "Snore"
end

debug
Syntax

member(whichCastmember).model(whichModel).debug
Description

3D model property; indicates whether the bounding sphere and local axes of the model are displayed.
Example

This statement sets the debug property of the model Dog to TRUE.
member("ParkScene").model("Dog").debug = TRUE
See also

boundingSphere

debugPlaybackEnabled
Syntax

the debugPlaybackEnabled
Description

Property; in Windows, opens a Message window for debugging purposes in Shockwave and
projectors. It does not have any effect when used in the Director application. Once the Message
window is closed, it cannot be reopened for a particular Shockwave or projector session. If more
than one Shockwave movie uses this Lingo in a single browser, only the first will open a Message
window, and the Message window will be tied to the first movie alone.
On the Macintosh, rather than a Message window being opened, a log file is generated to allow
Lingo put statements to output data for debugging purposes. This file is located in the
Shockwave folder at HardDrive/System Folder/Extensions/Macromedia/Shockwave.
To open this Message window, set the debugPlaybackEnabled property to TRUE. To close the
window, set the debugPlaybackEnabled property to FALSE.

180 Chapter 3

Example

This statement opens the Message window in either Shockwave or a projector:

the debugPlaybackEnabled = TRUE

decayMode
Syntax

member(whichCastmember).camera(whichCamera).fog.decayMode
sprite(whichSprite).camera{(index)}.fog.decayMode
Description

3D property; indicates the manner in which fog density builds from minimum to maximum
density when the cameras fog.enabled property is set to TRUE.
The following are the possible values for this property:

#linear:

the fog density is linearly interpolated between fog.near and fog.far.

#exponential: fog.far

is the saturation point; fog.near is ignored.

#exponential2: fog.near

is the saturation point; fog.far is ignored.

The default setting for this property is #exponential.

Example

This statement sets the decayMode property of the fog of the camera Defaultview to #linear. If
the fogs enabled property is set to TRUE, the density of the fog will steadily increase between the
distances set by the fogs near and far properties. If the near property is set to 100 and the far
property is set to 1000, the fog will begin 100 world units in front of the camera and gradually
increase in density to a distance of 1000 world units in front of the camera.
member("3d world").camera("Defaultview").fog.decayMode = #linear
See also

fog, near (fog), far (fog), enabled (fog)

defaultRect
Syntax

member(whichFlashOrVectorShapeMember).defaultRect
the defaultRect of member whichFlashOrVectorShapeMember
Description

Cast member property; controls the default size used for all new sprites created from a Flash
movie or vector shape cast member. The defaultRect setting also applies to all existing sprites
that have not been stretched on the Stage. You specify the property values as a Director rectangle;
for example, rect(0,0,32,32).
The defaultRect member property is affected by the cast members defaultRectMode member
property. The defaultRectMode property is always set to #Flash when a movie is inserted into a
cast, which means the original defaultRect setting is always the size of the movie as it was
originally created in Flash. Setting defaultRect after that implicitly changes the cast members
defaultRectMode property to #fixed.
This property can be tested and set.

Lingo Dictionary

181

Example

This handler accepts a cast reference and a rectangle as parameters. It then searches the specified
cast for Flash cast members and sets their defaultRect property to the specified rectangle.
on setDefaultFlashRect whichCast, whichRect
repeat with i = 1 to the number of members of castLib whichCast
if member(i, whichCast).type = #flash then
member(i, whichCast).defaultRect = whichRect
end if
end repeat
end
See also

defaultRectMode, flashRect

defaultRectMode
Syntax

member(whichVectorOrFlashMember).defaultRectMode
the defaultRectMode of member whichVectorOrFlashMember
Description

Cast member property; controls how the default size is set for all new sprites created from Flash
movie or vector shape cast members. You specify the property value as a Director rectangle; for
example, rect(0,0,32,32).
The defaultRectMode property does not set the actual size of a Flash movies default rectangle; it
only determines how the default rectangle is set. The defaultRectMode member property can
have these values:

#flash

#fixedSets

(default)Sets the default rectangle using the size of the movie as it was originally
created in Flash.
the default rectangle using the fixed size specified by the defaultRect
member property.

The defaultRect member property is affected by the cast members defaultRectMode member
property. The defaultRectMode property is always set to #flash when a movie is inserted into a
cast, which means the original defaultRect setting is always the size of the movie as it was
originally created in Flash. Setting defaultRect after that implicitly changes the cast members
defaultRectMode property to #fixed.
This property can be tested and set.
Example

This handler accepts a cast reference and a rectangle as parameters. It then searches the specified
cast for Flash cast members, sets their defaultRectMode property to #fixed, and then sets their
defaultRect property to rect(0,0,320,240).
on setDefaultRectSize whichCast
repeat with i = 1 to the number of members of castLib whichCast
if member(i, whichCast).type = #flash then
member(i, whichCast).defaultRectMode = #fixed
member(i, whichCast).defaultRect = rect(0,0,320,240)
end if
end repeat
end

182 Chapter 3

See also

flashRect, defaultRect

delay
Syntax

delay numberOfTicks
Description

Command; pauses the playhead for a given amount of time. The integer expression
numberOfTicks specifies the number of ticks to wait, where each tick is 1/60 of a second. The
only mouse and keyboard activity possible during this time is stopping the movie by pressing
Control+Alt+period (Windows) or Command+period (Macintosh). Because it increases the time
of individual frames, the delay command is useful for controlling the playback rate of a
sequence of frames.
The delay command can be applied only when the playhead is moving. However, when delay is
in effect, handlers still run: only the playhead halts, not script execution. Place scripts that use the
delay command in either an on enterFrame or on exitFrame handler.
To mimic the behavior of a halt in a handler when the playhead is not moving, use the
startTimer command or assign the current value of timer to a variable and wait for the specified

amount of time to pass before exiting the frame.

Examples

This handler delays the movie for 2 seconds when the playhead exits the current frame:
on exitFrame
delay 2 * 60
end

This handler, which can be placed in a frame script, delays the movie a random number of ticks:
on keyDown
if the key = RETURN then delay random(180)
end
Example

The first of these handlers sets a timer when the playhead leaves a frame. The second handler,
assigned to the next frame, loops in the frame until the specified amount of time passes:
--script for first frame
on exitFrame
global gTimer
set gTimer = the ticks
end
--script for second frame
on exitFrame
global gTimer
if the ticks < gTimer + (10 * 60) then
go to the frame
end if
end
See also

startTimer, ticks, timer

Lingo Dictionary 183

delete
Syntax

delete chunkExpression
Description

Command; deletes the specified chunk expression (character, word, item, or line) in any string
container. Sources of strings include field cast members and variables that hold strings.
To see an example of delete used in a completed movie, see the Text movie in the Learning/
Lingo Examples folder inside the Director application folder.
Examples

This statement deletes the first word of line 3 in the field cast member Address:
delete word 1 of line 3 of member "Address"

The same chunk of text may also be deleted with the syntax:
delete member("Address").line[3].word[1]

This statement deletes the first character of the string in the variable bidAmount if that character
is the dollar sign ($):
if bidAmount.char[1] = "$" then delete bidAmount.char[1]
See also

char...of, field, item...of, line...of, word...of, hilite (cast member property),

paragraph

deleteAll
Syntax

list.deleteAll()
deleteAll list
Description

List command; deletes all items in the specified list without changing the list type.
Example

This statement deletes every item in the list named propList:

propList.deleteAll()

deleteAt
Syntax

list.deleteAt(number)
deleteAt list, number
Description

List command; deletes the item in the position specified by number from the linear or property
list specified by list.
The deleteAt command checks whether an item is in a list; if you try to delete an object that
isnt in the list, Director displays an alert.

184 Chapter 3

Example

This statement deletes the second item from the list named designers, which contains [gee,
kayne, ohashi]:
designers = ["gee", "kayne", "ohashi"]
designers.deleteAt(2)

The result is the list [gee, ohashi].

This handler checks whether an object is in a list before attempting to delete it:
on myDeleteAt theList, theIndex
if theList.count < theIndex then
beep
else
theList.deleteAt(theIndex)
end if
end
See also

addAt

deleteCamera
Syntax

member(whichCastmember).deleteCamera(cameraName)
member(whichCastmember).deleteCamera(index)
sprite(whichSprite).deleteCamera(cameraOrIndex)
Description

3D command; in a cast member, this command removes the camera from the cast member and
the 3D world. Children of the camera are removed from the 3D world but not deleted.
It is not possible to delete the default camera of the cast member.
In a sprite, this command removes the camera from the sprites list of cameras. The camera is not
deleted from the cast member.
Examples

This statement deletes two cameras from the cast member named Room: first the camera named
Camera06, and then camera 1.
member("Room").deleteCamera("Camera06")
member("Room").deleteCamera(1)

This statement removes two cameras from the list of cameras for sprite 5: first the second camera
in the list, then the camera named Camera06
sprite(5).deleteCamera(2)
sprite(5).deleteCamera(member("Room").camera("Camera06"))
See also

newCamera, addCamera, cameraCount()

Lingo Dictionary 185

deleteFrame
Syntax

deleteFrame
Description

Command; deletes the current frame and makes the next frame the new current frame during a
Score generation session only.
Example

The following handler checks whether the sprite in channel 10 of the current frame has gone past
the right edge of a 640-by-480-pixel Stage and deletes the frame if it has:
on testSprite
beginRecording
if sprite(10).locH > 640 then deleteFrame
endRecording
end
See also

beginRecording, endRecording, updateFrame

deleteGroup
Syntax

member(whichCastmember).deleteGroup(whichGroup)
member(whichCastmember).deleteGroup(index)
Description

3D command; removes the group from the cast member and the 3D world. Children of the
group are removed from the 3D world but not deleted.
It is not possible to delete the group named World, which is the default group.
Example

The first line of this example deletes the group Dummy16 from the cast member Scene. The
second line deletes the third group of Scene.
member("Scene").deleteGroup("Dummy16")
member("Scene").deleteGroup(3)
See also

newGroup, child, parent

186 Chapter 3

deleteLight
Syntax

member(whichCastmember).deleteLight(whichLight)
member(whichCastmember).deleteLight(index)
Description

3D command; removes the light from the cast member and the 3D world. Children of the light
are removed from the 3D world but not deleted.
Examples

These examples delete lights from the cast member named Room.
member("Room").deleteLight("ambientRoomLight")
member("Room").deleteLight(6)
See also

newLight

deleteModel
Syntax

member(whichCastmember).deleteModel(whichModel)
member(whichCastmember).deleteModel(index)
Description

3D command; removes the model from the cast member and the 3D world. Children of the
model are removed from the 3D world but not deleted.
Examples

The first line of this example deletes the model named Player3 from the cast member named
gbWorld. The second line deletes the ninth model of gbWorld.
member("gbWorld").deleteModel("Player3")
member("gbWorld").deleteModel(9)
See also

newModel

deleteModelResource
Syntax

member(whichCastmember).deleteModelResource(whichModelResource)
member(whichCastmember).deleteModelResource(index)
Description

3D command; removes the model resource from the cast member and the 3D world.
Models using the deleted model resource become invisible, because they lose their geometry, but
they are not deleted or removed from the world.
Example

These examples delete two model resources from the cast member named StreetScene.
member("StreetScene").deleteModelResource("HouseB")
member("StreetScene").deleteModelResource(3)
See also

newModelResource, newMesh

Lingo Dictionary 187

deleteMotion
Syntax

member(whichCastmember).deleteMotion(whichMotion)
member(whichCastmember).deleteMotion(index)
Description

3D command; removes the motion from the cast member.

Examples

The first line of this example deletes the motion named BackFlip from the cast member named
PicnicScene. The second line deletes the fifth motion in PicnicScene.
member("PicnicScene").deleteMotion("BackFlip")
member("PicnicScene").deleteMotion(5)
See also

newMotion(), removeLast()

deleteOne
Syntax

list.deleteOne(value)
deleteOne list, value
Description

List command; deletes a value from a linear or property list. For a property list, deleteOne also
deletes the property associated with the deleted value. If the value appears in the list more than
once, deleteOne deletes only the first occurrence.
Attempting to delete a property has no effect.
Example

The first statement creates a list consisting of the days Tuesday, Wednesday, and Friday. The
second statement deletes the name Wednesday from the list.
days = ["Tuesday", "Wednesday", "Friday"]
days.deleteOne("Wednesday")
put days

The put

days

statement causes the Message window to display the result:

-- ["Tuesday", "Friday"].

deleteProp
Syntax

list.deleteProp(item)
deleteProp list, item
Description

List command; deletes the specified item from the specified list.

For linear lists, replace item with the number identifying the list position of the item to be
deleted. The deleteProp command for linear lists is the same as the deleteAt command. If
the number is greater than the number of items in the list, a script error occurs.

188 Chapter 3

 For property lists, replace item with the name of the property to be deleted. Deleting a
property also deletes its associated value. If the list has more than one of the same property,
only the first property in the list is deleted.
Example

This statement deletes the color property from the list [#height:100, #width: 200, #color: 34,
#ink: 15], which is called spriteAttributes:
spriteAttributes.deleteProp(#color)

The result is the list [#height:100, #width: 200, #ink: 15].

See also

deleteAt

deleteShader
Syntax

member(whichCastmember).deleteShader(whichShader)
member(whichCastmember).deleteShader(index)
Description

3D command; removes the shader from the cast member.

Example

The first line of this example deletes the shader Road from the cast member named StreetScene.
The second line deletes the third shader of StreetScene.
member("StreetScene").deleteShader("Road")
member("StreetScene").deleteShader(3)
See also

newShader, shaderList

deleteTexture
Syntax

member(whichCastmember).deleteTexture(whichTexture)
member(whichCastmember).deleteTexture(index)
Description

3D command; removes the shader from the cast member.

Example

The first line of this example deletes the texture named Sky from the cast member named
PicnicScene. The second line deletes the fifth texture of PicnicScene.
member("PicnicScene).deleteTexture("Sky")
member("PicnicScene").deleteTexture(5)
See also

newTexture

Lingo Dictionary 189

deleteVertex()
Syntax

member(memberRef).deleteVertex(indexToRemove)
deleteVertex(member memberRef, indexToRemove)
Description

Vector shape command; removes an existing vertex of a vector shape cast member in the index
position specified.
Example

This line removes the second vertex point in the vector shape Archie:
member("Archie").deleteVertex(2)
See also
addVertex, moveVertex(), originMode, vertexList

density
Syntax

member(whichCastmember).shader(whichShader).density
member(whichCastmember).model(whichModel).shader.density
member(whichCastmember).model(whichModel).shaderList{[index]}.\
density
Description

3D #engraver and #newsprint shader property; adjusts the number of lines or dots used to
create the effects of these specialized shader types. Higher values result in more lines or dots.
For #engraver shaders, this property adjusts the number of lines used to create the image. The
range is 0 to 100 and the default value is 40.
For #newsprint shaders, this property adjusts the number of dots used to create the image. The
value can be from 0 to 100 and the default value is 45.
Example

The following statement sets the density property of the shader named EngShader to 10. The
lines used by this #engraver shader to create its stylized image will be coarse and far apart.
member("scene").shader("EngShader").density = 10

The following statement sets the density property of the shader gbShader to 100. The dots used
by this #newsprint shader to create its stylized image will be very fine and close together.
member("scene").shader("gbShader").density = 100
See also

newShader

190 Chapter 3

depth
Syntax

imageObject.depth
member(whichCastMember).depth
the depth of member whichCastMember
Description

Image object or bitmap cast member property; displays the color depth of the given image object
or bitmap cast member.
Depth

Number of Colors

Black and white

4 colors

4, 8

16 or 256 palette-based colors, or gray levels

16

Thousands of colors

32

Millions of colors

This property can be tested but not set.

Examples

This statement displays the color depth of the image object stored in the variable newImage. The
output appears in the Message window.
put newImage.depth

This statement displays the color depth of the cast member Shrine in the Message window:
put member("Shrine").depth

depth (3D)
Syntax

member(whichCastmember).model(whichModel).sds.depth
Description

3D subdivision surfaces (sds) modifier property; specifies the maximum number of levels of
resolution that the model can display when using the sds modifier.
If the sds modifiers error and tension settings are low, increasing the depth property will have
a more pronounced effect on the models geometry.
The sds modifier cannot be used with the inker or toon modifiers, and you should be careful
when using the sds modifier with the lod modifier.
Example

This statement sets the depth property of the sds modifier for the model named Baby to 3. If the
sds modifiers error and tension settings are low, this will cause a very pronounced effect on
Babys geometry.
member("Scene").model("Baby").sds.depth = 3
See also

sds (modifier), error, tension

Lingo Dictionary

191

depthBufferDepth
Syntax

getRendererServices().depthBufferDepth
Description

3D rendererServices property; indicates the precision of the hardware depth buffer of the
users system. The value is either 16 or 24, depending on the users hardware settings.
Example

This statement shows that the depthBufferDepth value of the users video card is 16:
put getRendererServices().depthBufferDepth
-- 16
See also

getRendererServices(), getHardwareInfo(), colorBufferDepth

deskTopRectList
Syntax

the deskTopRectList
Description

System property; displays the size and position on the desktop of the monitors connected to a
computer. This property is useful for checking whether objects such as windows, sprites, and popup windows appear entirely on one screen.
The result is a list of rectangles, where each rectangle is the boundary of a monitor. The
coordinates for each monitor are relative to the upper left corner of monitor 1, which has the
value (0,0). The first set of rectangle coordinates is the size of the first monitor. If a second
monitor is present, a second set of coordinates shows where the corners of the second monitor are
relative to the first monitor.
This property can be tested but not set.
Examples

This statement tests the size of the monitors connected to the computer and displays the result in
the Message window:
put the deskTopRectList
-- [rect(0,0,1024,768), rect(1025, 0, 1665, 480]

The result shows that the first monitor is 1024 by 768 pixels and the second monitor is 640 by
480 pixels.
This handler tells how many monitors are in the current system:
on countMonitors
return the deskTopRectList.count
end

192 Chapter 3

diffuse
Syntax

member(whichCastmember).shader(whichShader).diffuse
member(whichCastmember).model(whichModel).shader.diffuse
member(whichCastmember).model(whichModel).shaderList{[index]}.\
diffuse
Description

3D #standard shader property; indicates a color that is blended with the first texture of the
shader when the following conditions are met:

the shaders useDiffuseWithTexture property is set to TRUE, and either

the blendFunction property of the shader is set to #add or #multiply, or
the blendFunction property of the shader is set to #blend, the blendSource property of the
shader is set to #constant, and the value of the blendConstant property of the shader is less
than 100.
The default value is of this property is rgb(

255, 255, 255 ).

Example

This statement sets the diffuse property of the shader named Globe to rgb(255,

0, 0).

member("MysteryWorld").shader("Globe").diffuse = rgb(255, 0, 0)
See also

diffuseColor, useDiffuseWithTexture, blendFunction, blendSource, blendConstant

diffuseColor
Syntax

member(whichCastmember).diffuseColor
Description

3D cast member property; indicates a color that is blended with the first texture of the first shader
of the cast member when the following conditions are met:

the shaders useDiffuseWithTexture property is set to TRUE, and either

the blendFunction property of the shader is set to #add or #multiply, or
the blendFunction property of the shader is set to #blend, the blendSource property of the
shader is set to #constant, and the value of the blendConstant property of the shader is less
than 100.
The default value is of the diffuseColor property is rgb(

255, 255, 255 ).

Example

This statement sets the diffuseColor property of the cast member named Room to
rgb(255, 0, 0).
member("Room").diffuseColor = rgb(255, 0, 0)
See also

diffuse, useDiffuseWithTexture, blendFunction, blendSource, blendConstant

Lingo Dictionary 193

diffuseLightMap
Syntax

member(whichCastmember).shader(whichShader).diffuseLightMap
member(whichCastmember).model(whichModel).shader.diffuseLightMap
member(whichCastmember).model(whichModel).shaderList{[index]}.\
diffuseLightMap
Description

3D #standard shader property; specifies the texture to use for diffuse light mapping.
When you set this property, the following properties are automatically set:

The second texture layer of the shader is set to the texture you specified.
The value of textureModeList[2] is set to #diffuse.
The value of blendFunctionList[2] is set to #multiply.
The value of blendFunctionList[1] is set to #replace.

Example

This statement sets the texture named Oval as the diffuseLightMap property of the shader used
by the model named GlassBox.
member("3DPlanet").model("GlassBox").shader.diffuseLightMap = \
member("3DPlanet").texture("Oval")
See also

blendFunctionList, textureModeList, glossMap, region, specularLightMap

digitalVideoTimeScale
Syntax

the digitalVideoTimeScale
Description

System property; determines the time scale, in units per second, that the system uses to track
digital video cast members.
The digitalVideoTimeScale property can be set to any value you choose.
The value of the property determines the fraction of a second that is used to track the video, as in
the following examples:

100The time scale is 1/100 of a second (and the movie is tracked in 100 units per second).
500The time scale is 1/500 of a second (and the movie is tracked in 500 units per second).
0Director uses the time scale of the movie that is currently playing.
Set digitalVideoTimeScale to precisely access tracks by ensuring that the systems time unit for
video is a multiple of the digital videos time unit. Set the digitalVideoTimeScale property to a
higher value to enable finer control of video playback.
This property can be tested and set.
Example

This statement sets the time scale that the system uses to measure digital video to 600 units
per second:
the digitalVideoTimeScale to 600

194 Chapter 3

digitalVideoType
Syntax

member(whichCastMember).digitalVideoType
the digitalVideoType of member whichCastMember
Description

Cast member property; indicates the format of the specified digital video. Possible values are
#quickTime or #videoForWindows.
This property can be tested but not set.
Example

The following statement tests whether the cast member Todays Events is a QuickTime or AVI
(Audio-Video Interleaved) digital video and displays the result in the Message window:
put member("Todays Events").digitalVideoType
See also

quickTimeVersion()

direction
Syntax

member(whichCastmember).modelResource(whichModelResource).\
emitter.direction
Description

3D emitter property; a vector that indicates the direction in which the particles of a particle
system are emitted. A particle system is a model resource whose type is #particle.
The primary direction of particle emission is the vector set by the emitters direction property.
However, the direction of emission of a given particle will deviate from that vector by a random
angle between 0 and the value of the emitters angle property.
Setting direction to vector(0,0,0) causes the particles to be emitted in all directions.
The default value of this property is vector(1,0,0).
Example

In this example, ThermoSystem is a model resource whose type is #particle. This statement sets
the direction property of ThermoSystems emitter to vector(1, 0, 0), which causes the particles
of ThermoSystem to be emitted into a conical region whose axis is the X axis of the 3D world.
member("Fires").modelResource("ThermoSystem").emitter.\
direction = vector(1,0,0)
See also

emitter, angle

Lingo Dictionary 195

directionalColor
Syntax

member(whichCastmember).directionalColor
Description

3D cast member property; indicates the RGB color of the default directional light of the cast member.
The default value of this property is rgb(255, 255, 255).
Example

This statement sets the directionalColor property of the cast member named Room to rgb(0,
255, 0). The default directional light of the cast member will be green. This property can also be
set in the Property inspector.
member("Room").directionalcolor = rgb(0, 255, 0)
See also

directionalPreset

directionalPreset
Syntax

member(whichCastmember).directionalPreset
Description

3D cast member property; indicates the direction from which the default directional light shines,
relative to the camera of the sprite.
Changing the value of this property results in changes to the position and rotation properties
of the lights transform.
Possible values of directionalPreset include the following:

#topLeft
#topCenter
#topRight
#middleLeft
#middleCenter
#middleRight
#bottomLeft
#bottomCenter
#bottomRight
#None

The default value of this property is #topCenter.

Example

This statement sets the directionalPreset property of the cast member named Room to
#middleCenter. This points the default light of Room so it will shine on the middle center the
current view of the camera of the sprite. This property can also be set in the Property inspector.
member("Room").directionalpreset = #middleCenter
See also

directionalColor

196 Chapter 3

directToStage
Syntax

member(whichCastMember).directToStage
the directToStage of member whichCastMember
sprite(whichSprite).directToStage
the directToStage of sprite whichSprite
Description

Sprite property and member property; determines the layer where a digital video, animated GIF,
vector shape, 3D, or Flash Asset cast member plays. If this property is TRUE (1), the cast member
plays in front of all other layers on the Stage, and ink effects have no affect. If this property is
FALSE (0), the cast member can appear in any layer of the Stages animation planes, and ink
effects affect the appearance of the sprite.

Use the syntax member(whichCastMember).directToStage for digital video or

animated GIFs.

Use the syntax sprite(whichSprite).directToStage for Flash or vector shapes.

Use either syntax for 3D cast members or sprites.
Using this property improves the playback performance of the cast member or sprite.
No other cast member can appear in front of a directToStage sprite. Also, ink effects do not
affect the appearance of a directToStage sprite.
When a sprites directToStage property is TRUE, Director draws the sprite directly to the screen
without first compositing it in the Director offscreen buffer. The result can be similar to the trails
ink effect of the Stage.
Explicitly refresh a trailed area by turning the directToStage property off and on, using a fullscreen transition, or wiping another sprite across this area. (In Windows, if you dont do this,
you can branch to another similar screen, and the video may not completely disappear.)
To see an example of directToStage used in a completed movie, see the QT and Flash movie in
the Learning/Lingo Examples folder inside the Director application folder.
Example

This statement makes the QuickTime movie The Residents always play in the top layer of the Stage:
member("The Residents").directToStage = 1

disableImagingTransformation
Syntax

the disableImagingTransformation
Description

Imaging Lingo property; When TRUE, this property prevents Director from automatically taking
Stage scrolling or zooming into account when (the stage).image is used. When the
disableImagingTransformation property is FALSE, Director will always capture the image of
the stage as if the stage window was zoomed at 100% and was not scrolled out from the center of
the stage window. Then this property is TRUE, zooming and scrolling of the Stage will affect the
appearance of the image captured by using (the stage).image.

Lingo Dictionary 197

displayFace
Syntax

member(whichTextCastmember).displayFace
member(which3DCastmember).modelResource(whichModelResource).\
displayFace
Description

3D text property; a linear list indicating which face or faces of the 3D text to display. Possible
values include #front, #tunnel, and #back. You can show any combination of faces, and the list
can be in any order.
The default value of this property is [#front,

#back, #tunnel].

For text cast members, this is a member property. For extruded text in a 3D cast member, this is a
model resource property.
Example

In this example, the cast member named Rugsign is a text cast member. This statement sets the
displayFace property of Rugsign to [#tunnel]. When Rugsign is displayed in 3D mode, its
front and back faces will not appear.
member("Rugsign").displayFace = [#tunnel]

In this example, the model resource of the model named Slogan is extruded text. This statement
sets the displayFace property of Slogans model resource to [#back, #tunnel]. The front face
of Slogan will not be drawn.
member("scene").model("Slogan").resource.displayFace = \
[#back, #tunnel]
See also

extrude3D, displayMode

displayMode
Syntax

member(whichTextCastmember).displayMode
Description

Text cast member property; specifies whether the text will be rendered as 2D text or 3D text.
If this property is set to #Mode3D, the text is shown in 3D. You can set the 3D properties (such as
displayFace and bevelDepth) of the text, as well as the usual text properties (such as text and
font). The sprite containing this cast member becomes a 3D sprite.
If this property is set to #ModeNormal, the text is shown in 2D.
The default value of this property is #ModeNormal.
Example

In this example, the cast member named Logo is a text cast member. This statement causes Logo
to be displayed in 3D.
member("Logo").displayMode = #mode3D
See also

extrude3D

198 Chapter 3

displayRealLogo
Syntax

sprite(whichSprite).displayRealLogo
member(whichCastmember).displayRealLogo
Description

RealMedia sprite or cast member property; allows you to set or get whether the RealNetworks
logo is displayed (TRUE) or not (FALSE). When set to TRUE, this property displays the
RealNetworks logo in the RealMedia viewer at the beginning of the stream, when the video is
stopped, or when the video is rewound.
The default value of this property is TRUE (1). Integer values other than 1 or 0 are treated as TRUE.
Examples

The following examples show that the displayRealLogo property for sprite 2 and the cast
member Real is set to TRUE, which means that the RealNetworks logo is displayed when the
movie starts to play and when it is stopped or rewound.
put sprite(2).displayRealLogo
-- 1
put member("Real").displayRealLogo
-- 1

The following examples set the displayRealLogo property for sprite 2 and the cast member Real
to FALSE, which means that the RealNetworks logo is not displayed.
sprite(2).displayRealLogo = FALSE
member("Real").displayRealLogo = FALSE

distanceTo()
Syntax

vector1.distanceTo(vector2)
Description

3D vector method; returns the distance in world units between two vectors.
Example

There are three vectors in this example. The distance from Vec1 to Vec2 is 100.0000 world units.
The distance from Vec1 to Vec3 is 141.4214 world units.
Vec1 = vector(100, 0, 0)
Vec2 = vector(100, 100, 0)
Vec3 = vector(100, 100, 100)
put Vec1.distanceTo(Vec2)
-- 100.0000
put Vec1.distanceTo(Vec3)
-- 141.4214
See also
magnitude

Lingo Dictionary 199

distribution
Syntax

member(whichCastmember).modelResource(whichModelResource).\
emitter.distribution
Description

3D emitter property; indicates how the particles of a particle system are distributed across the
emitters region at their creation. The possible values of this property are #gaussian or #linear.
The default value is #linear.
Example

In this example, ThermoSystem is a model resource whose type is #particle. This statement sets
the distribution property of ThermoSystems emitter to #linear, which causes the particles of
ThermoSystem to be evenly distributed across their origin region at their birth.
member("Fires").modelResource("ThermoSystem").emitter.\
distribution = #linear
See also

emitter, region

dither
Syntax

member(whichMember).dither
the dither of member whichMember
Description

Bitmap cast member property; dithers the cast member when it is displayed at a color depth of 8
bits or less (256 colors) if the display must show a color gradation not in the cast member (TRUE),
or tells Director to choose the nearest color out of those available in the current palette (FALSE).
For both performance and quality reasons, you should set dither to TRUE only when higher
display quality is necessary. Dithering is slower than remapping, and artifacts may be more
apparent when animating over a dithered image.
If the color depth is greater than 8 bits, this property has no effect.
See also

depth

do
Syntax

do stringExpression
Description

Command; evaluates stringExpression and executes the result as a Lingo statement. This
command is useful for evaluating expressions that the user has typed and for executing commands
stored in string variables, fields, arrays, and files.
Using uninitialized local variables within a do command creates a compile error. Initialize any
local variables in advance.
Note: This command does not allow global variables to be declared; these variables must be declared in advance.

200 Chapter 3

The do command works with multiple-line strings as well as single lines.

Example

This statement performs the statement contained within quotation marks:

do "beep 2"
do commandList[3]

doneParsing()
Syntax

parserObject.doneParsing()
Description

Function; returns 1 (TRUE) when the parser has completed parsing a document using
parseURL(). The return value is 0 (FALSE) until the parsing is complete.
See also

parseURL()

dot()
Syntax

vector1.dot(vector2)
Description

3D vector method; returns the sum of the products of the x, y, and z components of two vectors.
If both vectors are normalized, the dot is the cosine of the angle between the two vectors.
To manually arrive at the dot of two vectors, multiply the x component of vector1 by the x
component of vector2, then multiply the y component of vector1 by the y component of
vector2, then multiply the z component of vector1 by the z component of vector2, and finally
add the three products together.
This method is identical to dotProduct() function.
Example

In this example, the angle between the vectors pos5 and pos6 is 45 degrees. The getNormalized
function returns the normalized values of pos5 and pos6, and stores them in the variables norm1
and norm2. The dot of norm1 and norm2 is 0.7071, which is the cosine of 45 degrees.
pos5 = vector(100, 100, 0)
pos6 = vector(0, 100, 0)
put pos5.angleBetween(pos6)
-- 45.0000
norm1 = pos5.getNormalized()
put norm1
-- vector( 0.7071, 0.7071, 0.0000 )
norm2 = pos6.getNormalized()
put norm2
-- vector( 0.0000, 1.0000, 0.0000 )
put norm1.dot(norm2)
-- 0.7071
See also

dotProduct(), getNormalized, normalize

Lingo Dictionary 201

dotProduct()
Syntax

vector1.dotProduct(vector2)
Description

3D vector method; returns the sum of the products of the x, y, and z components of two vectors.
If both vectors are normalized, the dotproduct is the cosine of the angle between the two vectors.
To manually arrive at the dot of two vectors, multiply the x component of vector1 by the x
component of vector2, then multiply the y component of vector1 by the y component of
vector2, then multiply the z component of vector1 by the z component of vector2, and finally
add the three products together.
This method is identical to dot() function.
Example

In this example, the angle between the vectors pos5 and pos6 is 45. The getNormalized
function returns the normalized values of pos5 and pos6, and stores them in the variables norm1
and norm2. The dotProduct of norm1 and norm2 is 0.7071, which is the cosine of 45.
pos5 = vector(100, 100, 0)
pos6 = vector(0, 100, 0)
put pos5.angleBetween(pos6)
-- 45.0000
norm1 = pos5.getNormalized()
put norm1
-- vector( 0.7071, 0.7071, 0.0000 )
norm2 = pos6.getNormalized()
put norm2
-- vector( 0.0000, 1.0000, 0.0000 )
put norm1.dotProduct(norm2)
-- 0.7071
See also

dot(), getNormalized, normalize

doubleClick
Syntax

the doubleClick
Description

Function; tests whether two mouse clicks within the time set for a double-click occurred as a
double-click rather than two single clicks (TRUE), or if they didnt occur within the time set, treats
them as single clicks (FALSE).
Examples

This statement branches the playhead to the frame Enter Bid when the user double-clicks the
mouse button:
if the doubleClick then go to frame "Enter Bid"

202 Chapter 3

The following handler tests for a double-click. When the user clicks the mouse, a repeat loop runs
for the time set for a double-click (20 ticks in this case). If a second click occurs within 20 ticks,
the doubleClickAction handler runs. If a second click doesnt occur within the specified period,
the singleClickAction handler runs:
on mouseUp
if the doubleClick then exit
startTimer
repeat while the timer < 20
if the mouseDown then
doubleClickAction
exit
end if
end repeat
singleClickAction
end mouseUp
See also

clickOn, the mouseDown (system property), the mouseUp (system property)

downloadNetThing
Syntax

downloadNetThing URL, localFile

Description

Command; copies a file from the Internet to a file on the local disk, while the current movie
continues playing. Use netDone to find out whether downloading is finished.

URLThe

localFileThe

filename of any object that can be downloaded: for example, an FTP or HTTP
server, an HTML page, an external cast member, a Director movie, or a graphic
pathname and filename for the file on the local disk

Director movies in authoring mode and projectors support the downLoadNetThing command,
but the Shockwave player does not. This protects users from unintentionally copying files from
the Internet.
Although many network operations can be active at one time, running more than four concurrent
operations usually slows down performance unacceptably.
Neither the Director movies cache size nor the setting for the Check Documents option affects
the behavior of the downloadNetThing command.
Note: Director for Java does not support the downloadNetThing command.

Example

These statements download an external cast member from a URL to the Director application
folder and then make that file the external cast member named Cast of Thousands:
downLoadNetThing("http://www.cbDeMille.com/Thousands.cst", the \
applicationPath&"Thousands.Cst")
castLib("Cast of Thousands").fileName = the applicationPath&"Thousands.Cst"
See also

importFileInto, netDone(), preloadNetThing()

Lingo Dictionary 203

drag
Syntax

member(whichCastmember).modelResource(whichModelResource).drag
Description

3D #particle model resource property; indicates the percentage of each particles velocity that is
lost in each simulation step. This property has a range of 0 (no velocity lost) to 100 (all velocity
lost and the particle stops moving). The default value is 0.
Example

In this example, ThermoSystem is a model resource whose type is #particle. This statement sets
the drag property of ThermoSystem to 5, applying a large resistance to the motion of the
particles of ThermoSystem and preventing them from traveling very far.
member("Fires").modelResource("ThermoSystem").drag = 5
See also

wind, gravity

draw()
Syntax

imageObject.draw(x1, y1, x2, y2, colorObjectOrParameterList)

imageObject.draw(point(x, y), point(x, y), colorObjectOrParameterList)
imageObject.draw(rect, colorObjectOrParameterList)
Description

This function draws a line or an unfilled shape of color colorObject in a rectangular region of
the given image object, as specified in any of the three ways shown. The draw returns a value of 1
if there is no error. You can use the optional property list ParameterList function to specify the
following shape properties:
Property

Description

#shapeType

A symbol value of #oval, #rect, #roundRect, or #line. The default is #line.

#lineSize

The width of the line to use in drawing the shape.

#color

A color object, which determines the color of the shape border.

If you do not provide a parameter list, this function draws a 1-pixel line between the first and
second points given or between the upper left and lower right corners of the given rectangle.
For best performance, with 8-bit or lower images the colorObject should contain an indexed
color value. For 16- or 32-bit images, use an RGB color value.
If you want to fill a solid region, use the fill() function.
Examples

This statement draws a 1-pixel, dark red, diagonal line from point (0, 0) to point (128, 86) within
the image of member Happy.
member("Happy").image.draw(0, 0, 128, 86, rgb(150,0,0))

204 Chapter 3

The following statement draws a dark red, 3-pixel unfilled oval within the image of member
Happy. The oval is drawn within the rectangle (0, 0, 128, 86).
member("Happy").image.draw(0, 0, 128, 86, [#shapeType:#oval, #lineSize:3, \
#color: rgb(150, 0, 0)])
See also

color(), copyPixels(), fill(), setPixel()

drawRect
Syntax

window windowName.drawRect
the drawRect of window windowName
Description

Window property; identifies the rectangular coordinates of the Stage of the movie that appears in the
window. The coordinates are given as a rectangle, with entries in the order left, top, right, and bottom.
This property is useful for scaling or panning movies, but it does not rescale text and field cast
members. Scaling bitmaps can affect performance.
This property can be tested and set.
Example

This statement displays the current coordinates of the movie window called Control Panel:
put the drawRect of window "Control Panel"
-- rect(10, 20, 200, 300).

The following statement sets the rectangle of the movie to the values of the rectangle named
movieRectangle. The part of the movie within the rectangle is what appears in the window.
set the drawRect of window "Control Panel" to movieRectangle

The following lines cause the Stage to fill the main monitor area:
(the stage).drawRect = the desktopRectList[1]
(the stage).rect = the desktopRectList[1]
See also

deskTopRectList, rect (camera), sourceRect

dropShadow
Syntax

member(whichCastMember).dropShadow
the dropShadow of member whichCastMember
Description

Cast member property; determines the size of the drop shadow in pixels, for text in a field
cast member.
Example

This statement sets the drop shadow of the field cast member Comment to 5 pixels:
member("Comment").dropShadow = 5

Lingo Dictionary 205

duplicate
Syntax

vectorReference.duplicate()
transformReference.duplicate()
Description

3D vector and transform method; returns a copy of the vector or transform.

Example

This statement creates a copy of the position of model 1 and stores it in the variable zz.
zz = member("MyRoom").model[1].transform.position.duplicate()
See also

clone

duplicateFrame
Syntax

duplicateFrame
Description

Command; duplicates the current frame and its content, inserts the duplicate frame after the
current frame, and then makes the duplicate frame the current frame. This command can be used
during Score generation only.
The duplicateFrame command performs the same function as the insertFrame command.
Example

When used in the following handler, the duplicateFrame command creates a series of frames
that have cast member Ball in the external cast Toys assigned to sprite channel 20. The number of
frames is determined by the argument numberOfFrames.
on animBall numberOfFrames
beginRecording
sprite(20).member = member("Ball", "Toys")
repeat with i = 0 to numberOfFrames
duplicateFrame
end repeat
endRecording
end

206 Chapter 3

duplicate() (list function)

Syntax

(oldList).duplicate()
duplicate(oldList)
Description

List function; returns a copy of a list and copies nested lists (list items that also are lists) and their
contents. The function is useful for saving a lists current content.
When you assign a list to a variable, the variable contains a reference to the list, not the list itself.
This means any changes to the copy also affect the original list.
To see an example of duplicate() (list function) used in a completed movie, see the Vector
Shapes movie in the Learning/Lingo Examples folder inside the Director application folder.
Example

This statement makes a copy of the list CustomersToday and assigns it to the variable
CustomerRecord:
CustomerRecord = CustomersToday.duplicate()

duplicate() (image function)

Syntax

imageObject.duplicate()
Description

This function creates and returns a copy of the given imageObject. The new image is completely
independent of the original, and isnt linked to any cast member.
If you plan to make a lot of changes to an image, its better to make a copy thats independent of a
cast member.
Example

This statement creates a new image object from the image of cast member Lunar Surface and
places the new image object into the variable workingImage:
workingImage = member("Lunar Surface").image.duplicate()
See also

duplicate member

Lingo Dictionary 207

duplicate member
Syntax

member(originalMember).duplicate()
member(originalMember).duplicate({new})
duplicate member original {, new}
Description

Command; makes a copy of the cast member specified by original. The optional new parameter
specifies a specific Cast window location for the duplicate cast member. If the new parameter isnt
included, the duplicate cast member is placed in the first open Cast window position.
This command is best used during authoring rather than run time because it creates another cast
member in memory, which could result in memory problems. Use the command during
authoring if you want the changes to the cast to be permanently saved with the file.
Examples

This statement makes a copy of cast member Desk and places it in the first empty Cast window
position:
member("Desk").duplicate()

This statement makes a copy of cast member Desk and places it in the Cast window at
position 125:
member("Desk").duplicate(125)

duration
Syntax

member(whichCastMember).duration
the duration of member whichCastMember
Description

Cast member property; determines the duration of the specified Shockwave Audio (SWA),
transition, and QuickTime cast members.

When whichCastMember is a streaming sound file, this property indicates the duration of the
sound. The duration property returns 0 until streaming begins. Setting preLoadTime to 1
second allows the bit rate to return the actual duration.

When whichCastMember is a digital video cast member, this property indicates the digital
videos duration. The value is in ticks.

When whichCastMember is a transition cast member, this property indicates the transitions
duration. The value for the transition is in milliseconds. During playback, this setting has the
same effect as the Duration setting in the Frame Transition dialog box.
This property can be tested for all cast members that support it, but only set for transitions.
To see an example of duration used in a completed movie, see the QT and Flash movie in the
Learning/Lingo Examples folder inside the Director application folder.

208 Chapter 3

Examples

If the SWA cast member Louie Prima has been preloaded, this statement displays the sounds
duration in the field cast member Duration Displayer:
on exitFrame
if member("Louie Prima").state = 2 then
member("Duration Displayer").text = member("Louie Prima").duration
end if
end

You can use a behavior on a digital video sprite to loop the playhead in the current frame until the
movie is finished playing, allowing it to continue when the end is reached:
property spriteNum
on exitFrame me
myMember = sprite(spriteNum).member
myDuration = member(myMember).duration
myMovietime = sprite(spriteNum).movieTime
if myDuration > myMovietime then
go to the frame
else
go to the frame + 1
end if
end

duration (3D)
Syntax

member(whichCastmember).motion(whichMotion).duration
motionObjectReference.duration
Description

3D property; lets you get the time in millisecond that it takes the motion specified in the
whichMotion parameter to play to completion. This property is always greater than or equal to 0.
Example

This statement shows the length in milliseconds of the motion Kick.

put member("GbMember").motion("Kick").duration
-- 5100.0000
See also

motion, currentTime (3D), play() (3D), queue() (3D)

Lingo Dictionary 209

duration (RealMedia)
Syntax

sprite(whichSprite).duration
member(whichCastmember).duration
Description

RealMedia sprite or cast member property; returns the duration of the RealMedia stream, in
milliseconds. The duration of the RealMedia stream is not known until the cast member starts to
play. If the stream is from a live feed or has not been played, the value of this property is 0. This
property can be tested but not set.
Examples

The following examples show that the duration of the RealMedia stream in sprite 2 and the cast
member Real is 100,500 milliseconds (100.500 seconds).
put sprite(2).duration
-- 100500
put member("Real").duration
-- 100500
See also

play (RealMedia), seek, currentTime (RealMedia)

210 Chapter 3

editable
Syntax

member(whichCastMember).editable
the editable of member whichCastMember
sprite(whichSprite).editable
the editable of sprite whichSprite
Description

Cast member and sprite property; determines whether the specified field cast member can be
edited on the Stage (TRUE) or not (FALSE).
When the cast member property is set, the setting is applied to all sprites that contain the field.
When the sprite property is set, only the specified sprite is affected.
You can also make a field cast member editable by using the Editable option in the Field Cast
Member Properties dialog box.
You can make a field sprite editable by using the Editable option in the Score.
For the value set by Lingo to last beyond the current sprite, the sprite must be a puppet.
This property can be tested and set.
Examples

This statement makes the field cast member Answer editable:

member("Answer").editable = TRUE

This handler first makes the sprite channel a puppet and then makes the field sprite editable:
on myNotes
puppetSprite 5, TRUE
sprite(5).editable = TRUE
end

This statement checks whether a field sprite is editable and displays a message if it is:
if sprite(13).editable = TRUE then
member("Notice").text = "Please enter your answer below."
end if

211

editShortCutsEnabled
Syntax

the editShortCutsEnabled
Description

Movie property; determines whether cut, copy, and paste operations and their keyboard shortcuts
function in the current movie. When set to TRUE, these text operations function. When set to
FALSE, these operations are not allowed.
This property can be tested and set. The default is TRUE for movies made in Director 8 and later,
FALSE for movies made in versions of Director prior to Director 8.
Example

This statement disables cut, copy, and paste operations:

the editShortCutsEnabled = 0

elapsedTime
Syntax

sound(channelNum).elapsedTime
the elapsedTime of sound channelNum
Description

This read-only property gives the time, in milliseconds, that the current sound member in the
given sound channel has been playing. It starts at 0 when the sound begins playing and increases
as the sound plays, regardless of any looping, setting of the currentTime or other manipulation.
Use the currentTime to test for the current absolute time within the sound.
The value of this property is a floating-point number, allowing for measurement of sound
playback to fractional milliseconds.
Example

This idle handler displays the elapsed time for sound channel 4 in a field on the Stage during idles:
on idle
member("time").text = string(sound(4).elapsedTime)
end idle
See also

currentTime, loopCount, loopsRemaining, rewind()

emissive
Syntax

member(whichCastmember).shader(whichShader).emissive
member(whichCastmember).model(whichModel).shader.emissive
member(whichCastmember).model(whichModel).shaderList{[index]}.\
emissive
Description

3D #standard shader property; adds light to the shader independently of the lighting in the
scene. For example, a model using a shader whose emissive property is set to rgb(255, 255,
255) will appear to be illuminated by a white light, even if there are no lights in the scene. The
model will not, however, illuminate any other models or contribute any light to the scene.

212

The default value for this property is rgb(0,

0, 0).

Example

This statement sets the emissive property of the shader named Globe to rgb(255,
Models using this shader will appear to be illuminated by a red light:

0, 0).

member("MysteryWorld").shader("Globe").emissive = rgb(255, 0, 0)
See also

silhouettes

emitter
Syntax

member(whichCastmember).modelResource(whichModelResource).\
emitter.numParticles
member(whichCastmember).modelResource(whichModelResource).\
emitter.mode
member(whichCastmember).modelResource(whichModelResource).\
emitter.loop
member(whichCastmember).modelResource(whichModelResource).\
emitter.direction
member(whichCastmember).modelResource(whichModelResource).\
emitter.region
member(whichCastmember).modelResource(whichModelResource).\
emitter.distribution
member(whichCastmember).modelResource(whichModelResource).\
emitter.angle
member(whichCastmember).modelResource(whichModelResource).\
emitter.path
member(whichCastmember).modelResource(whichModelResource).\
emitter.pathStrength
member(whichCastmember).modelResource(whichModelResource).\
emitter.minSpeed
member(whichCastmember).modelResource(whichModelResource).\
emitter.maxSpeed
Description

3D particle system element; controls the initial propulsion of particles from a model resource
whose type is #particle.
The See also section of this entry contains a complete list of emitter properties. For more
information, see the individual property entries.
See also

numParticles, loop (emitter), direction, distribution, region, angle, path,

pathStrength, minSpeed, maxSpeed

213

EMPTY
Syntax

EMPTY
Description

Character constant; represents the empty string, "", a string with no characters.
Example

This statement erases all characters in the field cast member Notice by setting the field to EMPTY:
member("Notice").text = EMPTY

emulateMultiButtonMouse
Syntax

the emulateMultiButtonMouse
Description

System property; determines whether a movie interprets a mouse click with the Control key
pressed on the Macintosh the same as a right mouse click in Windows (TRUE) or not (FALSE).
Right-clicking has no direct Macintosh equivalent.
Setting this property to TRUE lets you provide consistent mouse button responses for crossplatform movies.
Example

The following statement checks if the computer is a Macintosh and if so, sets the
emulateMultiButtonMouse property to TRUE:
if the platform contains "Macintosh" then the emulateMultiButtonMouse = TRUE
See also

keyPressed(), rightMouseDown (system property), rightMouseUp (system property)

enabled
Syntax

the enabled of menuItem whichItem of menu whichMenu

Description

Menu item property; determines whether the menu item specified by whichItem is displayed in
plain text and is selectable (TRUE, default) or appears dimmed and is not selectable (FALSE).
The expression whichItem can be either a menu item name or a menu item number. The
expression whichMenu can be either a menu name or a menu number.
The enabled property can be tested and set.
Note: Menus are not available in Shockwave.

214

Example

This handler enables or disables all the items in the specified menu. The argument theMenu
specifies the menu; the argument Setting specifies TRUE or FALSE. For example, the calling
statement ableMenu ("Special", FALSE) disables all the items in the Special menu.
on ableMenu theMenu, vSetting
set n = the number of menuItems of menu theMenu
repeat with i = 1 to n
set the enabled of menuItem i of menu theMenu to vSetting
end repeat
end ableMenu
See also

name (menu property), number (menus), checkMark, script, number (menu items)

enabled (collision)
Syntax

member(whichCastmember).model(whichModel).collision.enabled
Description

3D collision property; allows you to get or set whether (TRUE) or not (FALSE) collisions are
detected on models. Setting this property to FALSE temporarily disables the collision modifier
without removing it from the model.
The default setting for this property is TRUE.
Example

This statement activates the collision modifier for the model box:
member("3d world").model("box").collision.enabled = TRUE
See also

addModifier, collision (modifier), modifier

enabled (fog)
Syntax

member(whichCastmember).camera(whichCamera).fog.enabled
sprite(whichSprite).camera{(index)}.fog.enabled
Description

3D camera property; indicates whether the camera adds fog to the view from the camera. The
default setting for this property is FALSE.
Example

This statement creates fog in the view from the camera named BayView:
member("MyYard").camera("BayView").fog.enabled = TRUE
See also

fog

215

enabled (sds)
Syntax

member(whichCastmember).model(whichModel).sds.enabled
Description

3D sds modifier property; indicates whether the sds modifier attached to a model is used by
the model.
The default setting for this property is TRUE.
An attempt to add the sds modifier to a model that already has the inker or toon modifier
attached fails without an error message. Likewise, an attempt to add the inker or toon modifier
to a model that already has the sds modifier attached also fails without an error message. Be
careful when using the sds modifier with the lod modifier. For more information, see the sds
(modifier) entry.
Example

This statement turns on the sds modifier attached to the model Baby:
member("Scene").model("Baby").sds.enabled = TRUE
See also

sds (modifier), modifier, addModifier

enableHotSpot
Syntax

enableHotSpot(sprite whichQTVRSprite, hotSpotID, trueOrFalse)

Description

QTVR (QuickTime VR) command; determines whether the specified hot spot for the specified
QTVR sprite is enabled (TRUE), or disabled (FALSE).

end
Syntax

end
Description

Keyword; marks the end of handlers and multiple-line control structures.

end case
Syntax

end case
Description

Keyword; ends a case statement.

216

Example

This handler uses the end

case

keyword to end the case statement:

on keyDown
case the key
of "A": go to frame "Apple"
of "B", "C" :
puppetTransition 99
go to frame "Mango"
otherwise beep
end case
end keyDown
See also

case

endAngle
Syntax

member(whichCastmember).modelResource(whichModelResource).\
endAngle
Description

3D #cylinder or #sphere model resource property; indicates how much of the sphere or
cylinder is drawn.
The surface of a sphere is generated by sweeping a 2D half circle arc around the spheres Y axis
from startAngle to endAngle. If startAngle is set to 0 and endAngle is set to 360, the result is
a complete sphere. To draw a section of a sphere, set endAngle to a value less than 360.
The surface of a cylinder is generated by sweeping a 2D line around the spheres Y axis from
to endAngle. If startAngle is set to 0 and endAngle is set to 360, the result is a
complete cylinder. To draw a section of a cylinder, set endAngle to a value less than 360.

startAngle

The default setting for this property is 360.

Example

For this example, assume that the cast member named MyMember contains a model that uses the
model resource named Sphere4, whose endAngle value is 310, leaving an opening of 50. The
handler closeSphere closes that opening in a way that makes it look like it is sliding shut. The
repeat loop changes the endAngle value of the sphere 1 at a time. The updateStage command
in the repeat loop forces the Stage to redraw after every 1 increment.
on closeSphere
MyAngle = member("MyMember").modelresource("Sphere4").endAngle
repeat with r = 1 to 50
MyAngle = MyAngle + 1
member("MyMember").modelresource("Sphere4").endAngle = MyAngle
updateStage
end repeat
end
See also

state (3D)

217

endColor
Syntax

the endColor of member whichCastMember

Description

Vector shape cast member property; the ending color of a gradient shapes fill specified as an
RGB value.
endColor is only
with fillColor.

valid when the fillMode is set to #gradient, and the starting color is set

This property can be tested and set.

To see an example of endColor used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.
See also

color(), fillColor, fillMode

endFrame()
Syntax

sprite(whichSprite).endFrame
Description

Function; returns the frame number of the end frame of the sprite span.
This function is useful in determining the span in the Score of a particular sprite. This function is
available only in a frame that contains the sprite. It cannot be applied to sprites in different frames
of the movie, nor is it possible to set this value.
Example

This statement output reports the ending frame of the sprite in channel 5 in the Message window:
put sprite(5).endFrame
See also

startFrame

endRecording
Syntax

endRecording
Description

Keyword; ends a Score update session. You can resume control of Score channels through
puppetting after the endRecording keyword is issued.

218

Example

When used in the following handler, the endRecording keyword ends the Score
generation session:
on animBall numberOfFrames
beginRecording
horizontal = 0
vertical = 100
repeat with i = 1 to numberOfFrames
go to frame i
sprite(20).member = member "Ball"
sprite(20).locH = horizontal
sprite(20).locV = vertical
horizontal = horizontal + 3
vertical = vertical + 2
updateFrame
end repeat
endRecording
end
See also

beginRecording, scriptNum, tweened, updateFrame

end repeat
See

repeat while, repeat with, repeat with...in list, repeat with...down to

on endSprite
Syntax

on endSprite
statement(s)
end
Description

System message and event handler; contains Lingo that runs when the playhead leaves a sprite
and goes to a frame in which the sprite doesnt exist. It is generated after exitFrame.
Place on

endSprite

handlers in a behavior script.

Director destroys instances of any behavior scripts attached to the sprite immediately after the
endSprite event occurs.
The event handler is passed the behavior or frame script reference me if used in a behavior. This
endSprite message is sent after the exitFrame message if the playhead plays to the end of the frame.
The go, play, and updateStage commands are disabled in an on

endSprite

handler.

Example

This handler runs when the playhead exits a sprite:

on endSprite me
-- clean up
gNumberOfSharks = gNumberOfSharks - 1
puppetSound(5,0)
end
See also

on beginSprite, on exitFrame
219

endTellTarget()
See tellTarget().

endTime
Syntax

sound(channelNum).endTime
the endTime of sound channelNum
Description

This property is the specified end time of the currently playing, paused or queued sound. This is
the time within the sound member when it will stop playing. Its a floating-point value, allowing
for measurement and control of sound playback to fractions of milliseconds. The default value is
the normal end of the sound.
This property may be set to a value other than the normal end of the sound only when passed as a
parameter with the queue() or setPlayList() commands.
Example

This Lingo checks whether the sound member Jingle is set to play all the way through in sound
channel 1:
if sound(1).startTime > 0 and sound(1).endTime < member("Jingle").duration
then
alert "Not playing the whole sound"
end if
See also

setPlaylist(), queue(), startTime

ENTER
Syntax

ENTER
Description

Character constant; represents the Enter key (Windows) or the Return key (Macintosh) for a
carriage return.
On PC keyboards, the element ENTER refers only to the Enter key on the numeric keypad.
For a movie that plays back as an applet, use RETURN to specify both the Return key in Windows
and the Enter key on the Macintosh.
Example

This statement checks whether the Enter key is pressed and if it is, sends the playhead to the
frame addSum:
on keyDown
if the key = ENTER then go to frame "addSum"
end
See also

RETURN (constant)

220

on enterFrame
Syntax

on enterFrame
statement(s)
end
Description

System message and event handler; contains statements that run each time the playhead enters
the frame.
Place on

enterFrame

handlers in behavior, frame, or movie scripts, as follows:

To assign the handler to an individual sprite, put the handler in a behavior attached to the sprite.
To assign the handler to an individual frame, put the handler in the frame script.
To assign the handler to every frame (unless you explicitly instruct the movie otherwise), put
the on enterFrame handler in a movie script. The handler executes every time the playhead
enters a frame unless the frame script has its own handler. If the frame script has its own
handler, the on enterFrame handler in the frame script overrides the on enterFrame handler
in the movie script.
The order of frame events is stepFrame, prepareFrame,

enterFrame,

and exitFrame.

This event is passed the object reference me if used in a behavior.

Example

This handler turns off the puppet condition for sprites 1 through 5 each time the playhead enters
the frame:
on enterFrame
repeat with i = 1 to 5
puppetSprite i, FALSE
end repeat
end

environment
Syntax

the environment
the envrionment.propertyName
Description

System property; this property contains a list with information about the environment under
which the Director content is currently running.
This design enables Macromedia to add information to the environment property in the future,
without affecting existing movies.

221

The information is in the form of property and value pairs for that area.
#shockMachine

Integer TRUE or FALSE value indicating whether the movie is playing in

ShockMachine.

#shockMachineVersion

String indicating the installed version number of ShockMachine.

#platform

String containing Macintosh,PowerPC, or Windows,32. This is based on the

current OS and hardware that the movie is running under.

#runMode

String containing Author, Projector, Plugin, or Java Applet. This is based on

the current application that the movie is running under.

#colorDepth

Integer representing the bit depth of the monitor the Stage appears on. Possible
values are 1, 2, 4, 8, 16, or 32.

#internetConnected

Symbol indicating whether the computer the movie is playing on has an active
Internet connection. Possible values are #online and #offline.

#uiLanguage

String indicating the language the computer is using to display its user interface. This
can be different from the #osLanguage on computers with specific language kits
installed.

#osLanguage

String indicating the native language of the computers operating system.

#productBuildVersion

String indicating the internal build number of the playback application.

The properties contain exactly the same information as the properties and functions of the
same name.
Example

This statement displays the environment list in the Message window:

put the environment
-- [#shockMachine: 0, #shockMachineVersion: "", #platform:
"Macintosh,PowerPC", #runMode: "Author", #colorDepth: 32,
#internetConnected: #online, #uiLanguage: "English", #osLanguage: "English",
#productBuildVersion: "151"]
See also

colorDepth, platform, runMode

erase member
Syntax

member(whichCastMember).erase()
erase member whichCastMember
Description

Command; deletes the specified cast member and leaves its slot in the Cast window empty.
For best results, use this command during authoring and not in projectors, which can cause
memory problems.
Examples

This statement deletes the cast member named Gear in the Hardware cast:
member("Gear", "Hardware").erase()

222

This handler deletes cast members start through finish:

on deleteMember start, finish
repeat with i = start to finish
member(i).erase()
end repeat
end on deleteMember
See also

new()

error
Syntax

member(whichCastmember).model(whichModel).sds.error
Description

3D #sds modifier property; indicates the percentage of error tolerated by the modifier when
synthesizing geometric detail in models.
This property works only when the modifiers subdivision property is set to #adaptive. The
tension and depth (3D) properties of the modifier combine with the error property to control
the amount of subdivision performed by the modifier.
Example

The following statement sets the error property of the #sds modifier of the model named Baby
to 0. If the modifiers tension setting is low, its depth setting is high, and its subdivision
setting is #adaptive, this will cause a very pronounced effect on Babys geometry.
member("Scene").model("Baby").sds.error = 0
See also

sds (modifier), subdivision, depth (3D), tension

on EvalScript
Syntax

on EvalScript aParam
statement(s)
end
Description

System message and event handler; in a Shockwave movie, contains statements that run when the
handler receives an EvalScript message from a browser. The parameter is a string passed in from
the browser.

The EvalScript message can include a string that Director can interpret as a Lingo statement.
Lingo cannot accept nested strings. If the handler you are calling expects a string as a
parameter, pass the parameter as a symbol.

The on

EvalScript handler is called by the EvalScript() scripting method from JavaScript

or VBScript in a browser.

The Director player for Java doesnt support the on EvalScript handler. To
enable communication between an applet and a browser, use Java, JavaScript, or VBScript.

223

Include only those behaviors in on EvalScript that you want users to control; for security
reasons, dont give complete access to behaviors.
Note: If you place a return at the end of your EvalScript handler, the value returned can be used by JavaScript in
the browser.

Examples

This shows how to make the playhead jump to a specific frame depending on what frame is
passed in as the parameter:
on EvalScript aParam
go frame aParam
end

This handler runs the statement go frame

includes dog, cat, or tree as an argument:

aParam

if it receives an EvalScript message that

on EvalScript aParam
case aParam of
"dog", "cat", "tree": go frame aParam
end case
end

A possible calling statement for this in JavaScript would be EvalScript

("dog").

This handler takes an argument that can be a number or symbol:

on EvalScript aParam
if word 1 of aParam = "myHandler" then
do aParam
end if
end

The following handler normally requires a string as its argument. The argument is received as a
symbol and then converted to a string within the handler by the string function:
on myHandler aParam
go to frame string(aParam)
end
See also

externalEvent, return (keyword)

eventPassMode
Syntax

sprite(whichFlashSprite).eventPassMode
the eventPassMode of sprite whichFlashSprite
member(whichFlashMember).eventPassMode
the eventPassMode of member whichFlashMember
Description

Flash cast member property and sprite property; controls when a Flash movie passes mouse events
to behaviors that are attached to sprites that lie underneath the flash sprite. The eventPassMode
property can have these values:

224

#passAlways

(default)Always passes mouse events.

#passButtonPasses

mouse events only when a button in the Flash movie is clicked.

#passNotButtonPasses
#passNeverNever

mouse events only when a nonbutton object is clicked.

passes mouse events.

This property can be tested and set.

Example

The following frame script checks to see whether the buttons in a Flash movie sprite are currently
enabled, and if so, sets eventPassMode to #passNotButton; if the buttons are disabled, the script
sets eventPassMode to #passAlways. The effect of this script is the following:

Mouse events on nonbutton objects always pass to sprite scripts.

Mouse events on button objects are passed to sprite scripts when the buttons are disabled.
When the buttons are enabled, mouse events on buttons are stopped.
on enterFrame
if sprite(5).buttonsEnabled = TRUE then
sprite(5).eventPassMode= #passNotButton
else
sprite(5).eventPassMode = #passAlways
end if
end

exit
Syntax

exit
Description

Keyword; instructs Lingo to leave a handler and return to where the handler was called. If the
handler is nested within another handler, Lingo returns to the main handler.
Example

The first statement of this script checks whether the monitor is set to black and white and then
exits if it is:
on setColors
if the colorDepth = 1 then exit
sprite(1).foreColor = 35
end
See also

abort, halt, quit, pass, return (keyword)

on exitFrame
Syntax

on exitFrame
statement(s)
end
Description

System message and event handler; contains statements that run each time the playhead exits the
frame that the on exitFrame handler is attached to. The on exitFrame handler is a useful place
for Lingo that resets conditions that are no longer appropriate after leaving the frame.

225

Place on

exitFrame

handlers in behavior, frame, or movie scripts, as follows:

To assign the handler to an individual sprite, put the handler in a behavior attached to the sprite.
To assign the handler to an individual frame, put the handler in the frame script.
To assign the handler to every frame unless explicitly instructed otherwise, put the handler in a
movie script. The on exitFrame handler then executes every time the playhead exits the frame
unless the frame script has its own on exitFrame handler. When the frame script has its own
on exitFrame handler, the on exitFrame handler in the frame script overrides the one in the
movie script.
This event is passed the sprite script or frame script reference me if it is used in a behavior. The
order of frame events is prepareFrame, enterFrame, and exitFrame.
Examples

This handler turns off all puppet conditions when the playhead exits the frame:
on exitFrame me
repeat with i = 48 down to 1
sprite(i).puppet = FALSE
end repeat
end

This handler branches the playhead to a specified frame if the value in the global variable
vTotal exceeds 1000 when the playhead exits the frame:
global vTotal
on exitFrame
if vTotal > 1000 then go to frame "Finished"
end
See also

on enterFrame

exitLock
Syntax

the exitLock
Description

Movie property; determines whether a user can quit to the Windows desktop or Macintosh
Finder from projectors (FALSE, default) or not (TRUE).
The user can quit to the desktop by pressing Control+period (Windows) or Command+period
(Macintosh), Control+Q (Windows) or Command+Q (Macintosh), or Control+W (Windows)
or Command+W (Macintosh); the Escape key is also supported in Windows.
This property can be tested and set.
Examples

This statement sets the exitLock property to TRUE:

set the exitLock to TRUE

226

Assuming that exitLock is set to TRUE, nothing occurs automatically when the Control+period/
Q/W, Esc, or Command+period/Q/W keys are used. This handler checks keyboard input for keys
to exit and takes the user to a custom quit sequence:
on checkExit
if the commandDown and (the key = "." or the key = "q") and the exitLock =
TRUE then go to frame "quit sequence"
end

exit repeat
Syntax

exit repeat
Description

Keyword; instructs Lingo to leave a repeat loop and go to the statement following the end
repeat statement but to remain within the current handler or method.
The exit repeat keyword is useful for breaking out of a repeat loop when a
specified conditionsuch as two values being equal or a variable being a certain valueexists.
Example

The following handler searches for the position of the first vowel in a string represented by the
variable testString. As soon as the first vowel is found, the exit repeat command instructs
Lingo to leave the repeat loop and go to the statement return i:
"on findVowel testString
repeat with i = 1 to testString.char[testString.char.count]
if ""aeiou"" contains testString.char[i] then exit repeat
end repeat
return i
end"
See also

repeat while, repeat with

exp()
Syntax

(integerOrFloat).exp
exp(integerOrFloat)
Description

Function; calculates e, the natural logarithm base, to the power specified by integerOrFloat.
Example

The following statement calculates the value of e to the exponent 5:

put (5).exp
-- 148.4132

227

externalEvent
Syntax

externalEvent "string"
Description

Command; sends a string to the browser that the browser can interpret as a scripting language
instruction, allowing a movie playing or a browser to communicate with the HTML page in
which it is embedded. The string sent by externalEvent must be in a scripting language
supported by the browser.
This command works only for movies in browsers. To enable communication between an applet
and a browser, use Java, JavaScript, or VBScript.
Note: The externalEvent command does not produce a return value. There is no immediate way to determine
whether the browser handled the event or ignored it. Use on EvalScript within the browser to return a message
to the movie.

Examples

The following statements use externalEvent in the LiveConnect scripting environment, which
is supported by Netscape 3.x and later.
LiveConnect evaluates the string passed by externalEvent as a function call. JavaScript authors
must define and name this function in the HTML header. In the movie, the function name and
parameters are defined as a string in externalEvent. Because the parameters must be interpreted
by the browser as separate strings, each parameter is surrounded by single quotation marks.
Statements within HTML:
function MyFunction(parm1, parm2) {
//script here
}

Statements within a script in the movie:

externalEvent ("MyFunction(parm1,parm2)")

The following statements use externalEvent in the ActiveX scripting environment used by
Internet Explorer in Windows. ActiveX treats externalEvent as an event and processes this
event and its string parameter the same as an onClick event in a button object.

Statements within HTML:

In the HTML header, define a function to catch the event; this example is in VBScript:
Sub
NameOfShockwaveInstance_externalEvent(aParam)
script here
End Sub

Alternatively, define a script for the event:

<SCRIPT FOR="NameOfShockwaveInstance"
EVENT="externalEvent(aParam)"
LANGUAGE="VBScript">
script here
</SCRIPT>

Within the movie, include the function and any parameters as part of the string for
externalEvent:
externalEvent ("MyFunction (parm1,parm2)")
See also

on EvalScript
228

externalParamCount()
Syntax

externalParamCount()
Description

Function; returns the number of parameters that an HTML <EMBED> or <OBJECT> tag is
passing to a Shockwave movie.
This function is valid only for Shockwave movies that are running in a browser. It doesnt work
for movies during authoring or for projectors.
Example

This handler determines whether an <OBJECT> or <EMBED> tag is passing any external
parameters to a Shockwave movie and runs Lingo statements if parameters are being passed:
if externalParamCount() > 0 then
-- perform some action
end if
See also

externalParamName(), externalParamValue()

externalParamName()
Syntax

externalParamName(n)
Description

Function; returns the name of a specific parameter in the list of external parameters from an
HTML <EMBED> or <OBJECT> tag. This function is valid only for Shockwave movies that are
running in a browser. It cannot be used with Director movies or projectors.

If n is an integer, externalParamName returns the nth parameter name in the list.

If n is a string, externalParamName returns n if any of the external parameter names matches
n. The match is not case sensitive. If
externalParamName returns VOID.

no matching parameter name is found,

Example

This statement places the value of a given external parameter in the variable myVariable:
if externalParamName ("swURLString") = "swURLString" then
myVariable = externalParamValue ("swURLString")
end if
See also

externalParamCount(), externalParamValue()

229

externalParamValue()
Syntax

externalParamValue(n)
Description

Function; returns a specific value from the external parameter list in an HTML <EMBED> or
<OBJECT> tag. This function is valid only for Shockwave movies that are running in a browser.
It cant be used with movies running in the authoring environment or projectors.

If n is an integer, externalParamValue returns the nth parameter value from the external
parameter list.

If n is a string, externalParamValue returns the value associated with the first name that
matches n. The match isnt case sensitive.
externalParamValue returns VOID.

If no such parameter value exists,

This functions behavior in an applet differs from that in other Director movies. In an applet,
does the following:

externalParamValue

Returns the applets parameters instead of the <EMBED> tag parameters.

Accepts only string parameters.
Returns a zero-length string rather than VOID.
See Parameters for OBJECT and EMBED tags and Parameters accessible from Lingo on the
Director Developers Center Web site.
Example

This statement places the value of an external parameter in the variable myVariable:
if externalParamName ("swURLString") = "swURLString" then
myVariable = externalParamValue ("swURLString")
end if
See also

externalParamCount(), externalParamName()

extractAlpha()
Syntax

imageObject.extractAlpha()
Description

This function copies the alpha channel from the given 32-bit image and returns it as a new image
object. The result is an 8-bit grayscale image representing the alpha channel.
This function is useful for downsampling 32-bit images with alpha channels.
Example

This statement places the alpha channel of the image of member 1 into the variable mainAlpha:
mainAlpha = member(1).image.extractAlpha()
setAlpha(), useAlpha

230

extrude3D
Syntax

member(whichTextCastmember).extrude3D(member(which3dCastmember))
Description

3D command; creates a new #extruder model resource in the 3D cast member

which3DCastmember from the text in whichTextCastmember.
Note that this is not the same as using the 3D displayMode property of a text cast member.
To create a model using extrude3D:

Create a new #extruder model resource in a 3D cast member:

textResource = member("textMember").extrude3D(member\
("3DMember"))

Create a new model using the model resource created in step 1:

member("3DMember").newModel("myText", textResource)

Example

In this example, Logo is a text cast member and Scene is a 3D cast member. The first line creates
a model resource in Scene which is a 3D version of the text in Logo. The second line uses this
model resource to create a model named 3dLogo.
myTextModelResource = member("Logo").extrude3d(member("Scene"))
member("Scene").newModel("3dLogo", myTextModelResource)
See also

bevelDepth, bevelType, displayFace, smoothness, tunnelDepth, displayMode

face
Syntax

member(whichCastmember).modelResource(whichModelResource).\
face.count
member(whichCastmember).modelResource(whichModelResource).\
face[index].colors
member(whichCastmember).modelResource(whichModelResource).\
face[index].normals
member(whichCastmember).modelResource(whichModelResource).\
face[index].shader
member(whichCastmember).modelResource(whichModelResource).\
face[index].textureCoordinates
member(whichCastmember).modelResource(whichModelResource).\
face[index].vertices
member(whichCastmember).model(whichModel).meshdeform.\
face.count
member(whichCastmember).model(whichModel).meshdeform.\
mesh[index].face.count
member(whichCastmember).model(whichModel).meshdeform.\
mesh[meshIndex].face[faceIndex]
member(whichCastmember).model(whichModel).meshdeform.\
mesh[meshIndex].face[faceIndex].neighbor{[neighborIndex]}

231

Description

3D #mesh model resource and meshdeform modifier property. All model resources are meshes
composed of triangles. Each triangle is a face.
You can access the properties of the faces of model resources whose type is #mesh. Changes to any
of these properties do not take effect until you call the build() command.
Note: For detailed information about the following properties, see the individual property entries.

count

normals indicates which indices in the normal list of the model resource to use for each of the
vertices of the face.

shadowPercentage

vertices indicates which indices in the vertex list of the model resource to use to define the face.

indicates the number of triangles in the mesh.

indicates which indices in the color list of the model resource to use for each of the
vertices of the face.

colors

identifies the shader used when the face is rendered.

indicates which indices in the texture coordinate list of the model

resource to use for each of the vertices of the face.

textureCoordinates

See the entry for meshDeform for descriptions of its face properties.
See also

build(), newMesh, meshDeform (modifier)

face[ ]
Syntax

member(whichCastmember).model(whichModel).meshdeform.\
mesh[meshIndex].face[faceIndex]
Description

3D meshdeform modifier property; indicates which indices in the vertex list of the model
resource were used to define the face.
This property can be tested but not set. You can specify the vertices of a face of the #mesh model
resource by setting its vertexList and vertices properties and calling the build command.
Example

This statement shows that the first face of the first mesh of the model named Floor is defined by
the first three vectors in the vertex list of the model resource used by Floor:
put member("Scene").model("Floor").meshdeform.mesh[1].face[1]
-- [1, 2, 3]
See also
meshDeform (modifier), face, vertexList (mesh deform), vertices

232

fadeIn()
Syntax

sound(channelNum).fadeIn({milliseconds})
fadeIn(sound(channelNum) {, milliseconds })
Description

This function immediately sets the volume of sound channel channelNum to zero and then brings
it back to the current volume over the given number of milliseconds. The default is 1000
milliseconds (1 second) value is given.
The current pan setting is retained for the entire fade.
Example

This Lingo fades in sound channel 3 over a period of 3 seconds from the beginning of cast
member introMusic2:
sound(3).play(member("introMusic2"))
sound(3).fadeIn(3000)
See also

fadeOut(), fadeTo(), pan (sound property), volume (sound channel)

fadeOut()
Syntax

sound(channelNum).fadeOut({milliseconds})
fadeOut(sound(channelNum) {, milliseconds })
Description

This function gradually reduces the volume of sound channel channelNum to zero over the given
number of milliseconds, or 1000 milliseconds (1 second) if no value is given.
The current pan setting is retained for the entire fade.
Example

This statement fades out sound channel 3 over a period of 5 seconds:

sound(3).fadeOut(5000)
See also

fadeIn(), fadeTo(), pan (sound property), volume (sound channel)

fadeTo()
Syntax

sound(channelNum).fadeTo(volume {, milliseconds })
fadeTo(sound(channelNum), volume {, milliseconds })
Description

This function gradually changes the volume of sound channel channelNum to the specified
volume over the given number of milliseconds, or 1000 milliseconds (1 second) if no value is
given. The range of values for volume is 0-255.
The current pan setting is retained for the entire fade.

233

To see an example of fadeTo() used in a completed movie, see the Sound Control movie in the
Learning/Lingo Examples folder inside the Director application folder.
Example

The following statement changes the volume of sound channel 4 to 150 over a period of 2
seconds. It can be a fade up or a fade down, depending on the original volume of sound channel 4
when the fade begins.
sound(4).fadeTo(150, 2000)
See also

fadeIn(), fadeOut(), pan (sound property), volume (sound channel)

FALSE
Syntax

FALSE
Description

Constant; applies to an expression that is logically FALSE, such as 2 > 3. When treated as a
number value, FALSE has the numerical value of 0. Conversely, 0 is treated as FALSE.
Example

This statement turns off the soundEnabled property by setting it to FALSE:

the soundEnabled = FALSE
See also

if, not, TRUE

far (fog)
Syntax

member(whichCastmember).camera(whichCamera).fog.far
sprite(whichSprite).camera{(index)}.fog.far
Description

3D camera property; indicates the distance from the camera, in world units, where the fog reaches
its maximum density when the cameras fog.enabled property is set to TRUE.
The default value for this property is 1000.
Example

The following statement sets the far property of the fog of the camera named BayView to 5000.
If the fogs enabled property is set to TRUE, the fog will be densest 5000 world units in front of
the camera.
member("MyYard").camera("BayView").fog.far = 5000
See also

fog, near (fog)

234

field
Syntax

field whichField
Description

Keyword; refers to the field cast member specified by whichField.

When whichField is a string, it is used as the cast member name.

When whichField is an integer, it is used as the cast member number.
Character strings and chunk expressions can be read from or placed in the field.
The term field was used in earlier versions of Director and is maintained for backward
compatibility. For new movies, use member to refer to field cast members.
Examples

This statement places the characters 5 through 10 of the field name entry in the variable myKeyword:
myKeyword = field("entry").char[5..10]

This statement checks whether the user entered the word desk and, if so, goes to the frame deskBid:
if member "bid" contains "desk" then go to "deskBid"
See also

char...of, item...of, line...of, word...of

fieldOfView
Syntax

sprite(whichQTVRSprite).fieldOfView
the fieldOfView of sprite whichQTVRSprite
Description

QTVR sprite property; gives the specified sprites current field of view in degrees.
This property can be tested and set.

fieldOfView (3D)
Syntax

member(whichCastmember).camera(whichCamera).fieldOfView
sprite(whichSprite).camera{(index)}.fieldOfView
Description

3D camera property; indicates the angle formed by two rays: one drawn from the camera to the top
of the projection plane, and the other drawn from the camera to the bottom of the projection plane.
The images of the models in the 3D world are mapped onto the projection plane, which is
positioned in front of the camera like a screen in front of a movie projector. The projection plane
is what you see in the 3D sprite. The top and bottom of the projection plane are defined by the
fieldOfView property. Note, however, that the sprite is not resized as the value of the
fieldOfView property changes. Instead, the image of the projection plane is scaled to fit the rect
of the sprite.

235

The value of this property is meaningful only when the value of the cameras projection
property is set to #perspective. When the projection property is set to #orthographic, use
the cameras orthoHeight property to define the top and bottom of the projection plane.
The default setting for this property is 30.0.
Example

This statement sets the fieldOfView property of camera 1 to 90:

member("3d world").camera[1].fieldOfView = 90
See also

orthoHeight

fileName (cast property)

Syntax

castLib(whichCast).fileName
the fileName of castLib whichCast
Description

Property; specifies the filename of the specified cast.

For an external cast, fileName gives the casts full pathname and filename.
For an internal cast, the fileName castLib property depends on which internal cast is
specified. For the first internal cast library, the fileName castLib property specifies the name
of the movie. For remaining internal casts, fileName is an empty string.
The fileName of castLib property accepts URLs as references. However, to use a cast from the
Internet and minimize download time, use the downloadNetThing or preloadNetThing
command to download the casts file to a local disk first and then set fileName castLib to the
file on the disk.
If a movie sets the filename of an external cast, dont use the Duplicate Cast Members for Faster
Loading option in the Projector Options dialog box.
This property can be tested and set for external casts. It can be tested only for internal casts.
Note: Director for Java does not support the downloadNetThing command.

Examples

This statement displays the pathname and filename of the Buttons external cast in the
Message window:
put castLib("Buttons").fileName

This statement sets the filename of the Buttons external cast to Content.cst:
castLib("Buttons").fileName = the moviePath & "Content.cst"

The movie then uses the external cast file Content.cst as the Buttons cast.
These statements download an external cast from a URL to the Director application folder and
then make that file the external cast named Cast of Thousands:
downLoadNetThing("http://www.cbDeMille.com Thousands.cst", the \
applicationPath&"Thousands.cst")
castLib("Cast of Thousands").fileName = the applicationPath & "Thousands.cst"
See also

downloadNetThing, preloadNetThing()

236

fileName (cast member property)

Syntax

member(whichCastMember).fileName
the fileName of member whichCastMember
Description

Cast member property; refers to the name of the file assigned to the linked cast member specified
by whichCastMember. This property is useful for switching the external linked file assigned to a
cast member while a movie plays, similar to the way you can switch cast members. When the
linked file is in a different folder than the movie, you must include the files pathname.
You can also make unlinked media linked by setting the filename of those types of members that
support linked media.
The fileName member property accepts URLs as a reference. However, to use a file from a URL
and minimize download time, use the downloadNetThing or preloadNetThing command to
download the file to a local disk first and then set fileName member property to the file on the
local disk.
The Director player for Java doesnt support the downLoadNetThing command, so the player
cant download files in the background before assigning a new file to a cast member. Changing the
fileName member property in a movie playing as an applet can make the applet wait for the new
file to download.
This property can be tested and set. After the filename is set, Director uses that file the next time
the cast member is used.
Example

This statement links the QuickTime movie ChairAnimation to cast member 40:
member(40).fileName = "ChairAnimation"

These statements download an external file from a URL to the Director application folder and
make that file the media for the sound cast member Norma Desmond Speaks:
downLoadNetThing("http://www.cbDeMille.com/ Talkies.AIF",the \
applicationPath&"Talkies.AIF")
member("Norma Desmond Speaks").fileName = the applicationPath & "Talkies.AIF"
See also

downloadNetThing, preloadNetThing()

fileName (window property)

Syntax

window whichWindow.fileName
the fileName of window whichWindow
Description

Window property; refers to the filename of the movie assigned to the window specified by
whichWindow. When the linked file is in a different folder than the movie, you must include the
files pathname.
To be able to play the movie in a window, you must set the fileName window property to the
movies filename.

237

The fileName of window property accepts URLs as a reference. However, to use a movie file
from a URL and minimize the download time, use the downloadNetThing or preloadNetThing
command to download the movie file to a local disk first and then set fileName window property
to the file on the local disk.
This property can be tested and set.
Examples

This statement assigns the file named Control Panel to the window named Tool Box:
window("Tool Box").fileName = "Control Panel"

This statement displays the filename of the file assigned to the window named Navigator:
put window("Navigator").fileName

These statements download a movie file from a URL to the Director application folder and then
assign that file to the window named My Close Up:
downLoadNetThing("http://www.cbDeMille.com/Finale.DIR",the \
applicationPath&"Finale.DIR")
window("My Close Up").fileName = the applicationPath&"Finale.DIR"
See also

downloadNetThing, preloadNetThing()

fill()
Syntax

imageObject.fill(left, top, right, bottom, colorObjectOrParameterList)

imageObject.fill(point(x, y), point(x, y), colorObjectOrParameterList)
imageObject.fill(rect, colorObjectOrParameterList)
Description

This function fills a rectangular region with the color colorObject in the given image object.
You specify the rectangle in any of the three ways shown. The points specified are relative to the
upper-left corner of the given image object. The return value is 1 if there is no error, zero if there
is an error.
If you provide a parameterList instead of a simple colorObject, the rectangle is filled with a
shape you specify with these parameters:
Property

Description

#shapeType

A symbol value of #oval, #rect, #roundRect, or #line. The default is #line.

#lineSize

The width of the line to use in drawing the shape.

#color

A color object, which determines the fill color of the shape.

#bgColor

A color object, which determines the color of the shapes border.

For best performance, with 8-bit or lower images the colorObject should contain an indexed
color value. For 16- or 32-bit images, use an RGB color value.
Examples

This statement renders the image object in the variable myImage completely black:
myImage.fill(myImage.rect, rgb(0, 0, 0))

238

The following statement draws a filled oval in the image object TestImage. The oval has a green
fill and a 5-pixel-wide red border.
TestImage.fill(0, 0, 100, 100, [#shapeType: #oval, #lineSize: 5, #color:
rgb(0, 255, 0), \
#bgColor: rgb(255, 0, 0)])
See also

color(), draw()

fillColor
Syntax

member(whichCastMember).fillColor
Description

Vector shape cast member property; the color of the shapes fill specified as an RGB value.
Its possible to use fillColor when the fillMode property of the shape is set to #solid or
#gradient, but not if it is set to #none. If the fillMode is #gradient, fillColor specifies the
starting color for the gradient. The ending color is specified with endColor.
This property can be tested and set.
To see an example of fillColor used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.
Example

This statement sets the fill color of the member Archie to a new RGB value:
member("Archie").fillColor = rgb( 24, 15, 153)
See also

endColor, fillMode

fillCycles
Syntax

member(whichCastMember).fillCycles
Description

Vector shape cast member property; the number of fill cycles in a gradient vector shapes fill, as
specified by an integer value from 1 to 7.
This property is valid only when the fillMode property of the shape is set to #gradient.
This property can be tested and set.
To see an example of fillCycles used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.
Example

This statement sets the fillCycles of member Archie to 3:

member("Archie").fillCycles = 3
See also

endColor, fillColor, fillMode

239

fillDirection
Syntax

member(whichCastMember).fillDirection
Description

Vector shape cast member property; specifies the amount in degrees to rotate the fill of the shape.
This property is only valid when the fillMode property of the shape is set to #gradient.
This property can be tested and set.
To see an example of fillDirection used in a completed movie, see the Vector Shapes movie in
the Learning/Lingo Examples folder inside the Director application folder.
See also

fillMode

filled
Syntax

member(whichCastMember).filled
the filled of member whichCastMember
Description

Shape cast member property; indicates whether the specified cast member is filled with a pattern
(TRUE) or not (FALSE).
Example

The following statements make the shape cast member Target Area a filled shape and assign it the
pattern numbered 1, which is a solid color:
member("Target Area").filled = TRUE
member("Target Area").pattern = 1
See also

fillColor, fillMode

fillMode
Syntax

member(whichCastMember).fillMode
Description

Vector shape cast member property; indicates the fill method for the shape, using the following
possible values:

#noneThe

shape is transparent

#solidThe

shape uses a single fill color

#gradientThe

shape uses a gradient between two colors

This property can be tested and set when the shape is closed; open shapes have no fill.
To see an example of fillMode used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.

240

Example

This statement sets the fillMode of member Archie to gradient:

member("Archie").fillMode = #gradient
See also

endColor, fillColor

fillOffset
Syntax

member(whichCastMember).fillOffset
Description

Vector shape cast member property; specifies the horizontal and vertical amount in pixels (within
the defaultRect space) to offset the fill of the shape.
This property is only valid when the fillMode property of the shape is set to #gradient, but can
be both tested and set.
To see an example of fillOffset used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.
Example

This statement changes the fill offset of the vector shape cast member miette to a horizontal offset
of 33 pixels and a vertical offset of 27 pixels:
member("miette").fillOffset = point(33, 27)
See also

defaultRect, fillMode

fillScale
Syntax

member(whichCastMember).fillScale
Description

Vector shape cast member property; specifies the amount to scale the fill of the shape. This
property is referred to as spread in the vector shape window.
This property is only valid when the fillMode property of the shape is set to #gradient, but can
be both tested and set.
To see an example of fillScale used in a completed movie, see the Vector Shapes movie in the
Learning/Lingo Examples folder inside the Director application folder.
Example

This statement sets the fillScale of member Archie to 33:

member("Archie").fillScale = 33.00
See also

fillMode

241

findEmpty()
Syntax

findEmpty(member whichCastMember)
Description

Function; for the current cast only, displays the next empty cast member position or the position
after the cast member specified by whichCastMember.
Example

This statement finds the first empty cast member on or after cast member 100:
put findEmpty(member 100)

findLabel()
Syntax

sprite(whichFlashSprite).findLabel(whichLabelName)
findLabel(sprite whichFlashSprite, whichLabelName)
Description

Function: this function returns the frame number (within the Flash movie) that is associated with
the label name requested.
A 0 is returned if the label doesnt exist, or if that portion of the Flash movie has not yet been
streamed in.

findPos
Syntax

list.findPos(property)
findPos(list, property)
Description

List command; identifies the position of the property specified by property in the property list
specified by list.
Using findPos with linear lists returns a bogus number if the value of property is a number and
a script error if the value of property is a string.
The findPos command performs the same function as the findPosNear command, except that
findPos is VOID when the specified property is not in the list.
Example

This statement identifies the position of the property c in the list Answers, which consists of
[#a:10, #b:12, #c:15, #d:22]:
Answers.findPos(#c)

The result is 3, because c is the third property in the list.

See also

findPosNear, sort

242

findPosNear
Syntax

sortedList.findPosNear(valueOrProperty)
findPosNear(sortedList, valueOrProperty)
Description

List command; for sorted lists only, identifies the position of the item specified by
valueOrProperty in the specified sorted list.
The findPosNear command works only with sorted lists. Replace valueOrProperty with a
value for sorted linear lists, and with a property for sorted property lists.
The findPosNear command is similar to the findPos command, except that when the specified
property is not in the list, the findPosNear command identifies the position of the value with the
most similar alphanumeric name. This command is useful in finding the name that is the closest
match in a sorted directory of names.
Example

This statement identifies the position of a property in the sorted list Answers, which consists of
[#Nile:2, #Pharaoh:4, #Raja:0]:
Answers.findPosNear(#Ni)

The result is 1, because Ni most closely matches Nile, the first property in the list.
See also

findPos

finishIdleLoad
Syntax

finishIdleLoad loadTag
Description

Command; forces completion of loading for all the cast members that have the specified load tag.
Example

This statement completes the loading of all cast members that have the load tag 20:
finishIdleLoad 20
See also

idleHandlerPeriod, idleLoadDone(), idleLoadMode, idleLoadPeriod, idleLoadTag,

idleReadChunkSize

243

firstIndent
Syntax

chunkExpression.firstIndent
Description

Text cast member property; contains the number of pixels the first indent in chunkExpression is
offset from the left margin of the chunkExpression.
The value is an integer: less than 0 indicates a hanging indent, 0 is no indention, and greater than
0 is a normal indention.
This property can be tested and set.
Example

This statement sets the indent of the first line of member Desk to 0 pixels:
member("Desk").firstIndent = 0
See also

leftIndent, rightIndent

fixedLineSpace
Syntax

chunkExpression.fixedLineSpace
Description

Text cast member property; controls the height of each line in the chunkExpression portion of
the text cast member.
The value itself is an integer, indicating height in absolute pixels of each line.
The default value is 0, which results in natural height of lines.
Example

This statement sets the height in pixels of each line of member Desk to 24:
member("Desk").fixedLineSpace = 24

fixedRate
Syntax

sprite(whichFlashOrGIFSprite).fixedRate
the fixedRate of sprite whichFlashOrGIFSprite
member(whichFlashOrGIFMember).fixedRate
the fixedRate of member whichFlashOrGIFMember
Description

Cast member property and sprite property; controls the frame rate of a Flash movie or animated
GIF. The fixedRate property can have integer values. The default value is 15.
This property is ignored if the sprites playbackMode property is anything other than #fixed.
This property can be tested and set.

244

Example

The following handler adjusts the frame rate of a Flash movie sprite. As parameters, the handler
accepts a sprite reference, an indication of whether to speed up or slow down the Flash movie, and
the amount to adjust the speed.
on adjustFixedRate whichSprite, adjustType, howMuch
case adjustType of
#faster:
sprite(whichSprite).fixedRate = sprite(whichSprite).fixedRate + howMuch
#slower:
sprite(whichSprite).fixedRate = sprite(whichSprite).fixedRate - howMuch
end case
end
See also

playBackMode

fixStageSize
Syntax

the fixStageSize
Description

Movie property; determines whether the Stage size remains the same when you load a new movie
(TRUE, default), or not (FALSE), regardless of the Stage size saved with that movie, or the setting
for the centerStage.
The fixStageSize property cannot change the Stage size for a movie that is currently playing.
This property can be tested and set.
Examples

The following statement determines whether the fixStageSize property is turned on. If
fixStageSize is FALSE, it sends the playhead to a specified frame.
if the fixStageSize = FALSE then go to frame "proper size"

This statement sets the fixStageSize property to the opposite of its current setting:
the fixStageSize = not the fixStageSize
See also

centerStage

flashRect
Syntax

member(whichVectorOrFlashMember).flashRect
the flashRect of member whichVectorOrFlashMember
Description

Cast member property; indicates the size of a Flash movie or vector shape cast member as it was
originally created. The property values are indicated as a Director rectangle: for example,
rect(0,0,32,32).
For linked Flash cast members, the FlashRect member property returns a valid value only when
the cast members header has finished loading into memory.

245

This property can be tested but not set.

Example

This sprite script resizes a Flash movie sprite so that it is equal to the original size of its Flash
movie cast member:
on beginSprite me
sprite(me.spriteNum).rect = sprite(me.spriteNum).member.FlashRect
end
See also

defaultRect, defaultRectMode, state (Flash, SWA)

flashToStage()
Syntax

sprite(whichFlashSprite).flashToStage(pointInFlashMovie)
flashToStage (sprite whichFlashSprite, pointInFlashMovie)
Description

Function; returns the coordinate on the Director Stage that corresponds to a specified coordinate
in a Flash movie sprite. The function accepts both the Flash channel and movie coordinate and
returns the Director Stage coordinate as Director point values: for example, point(300,300).
Flash movie coordinates are measured in Flash movie pixels, which are determined by a movies
original size when it was created in Flash. For the purpose of calculating Flash movie coordinates,
point(0,0) of a Flash movie is always at its upper left corner. (The cast members originPoint
property is used only for rotation and scaling, not to calculate movie coordinates.)
The flashToStage and the corresponding stageToFlash functions are helpful for determining
which Flash movie coordinate is directly over a Director Stage coordinate. For both Flash and
Director, point(0,0) is the upper left corner of the Flash Stage or Director Stage. These
coordinates may not match on the Director Stage if a Flash sprite is stretched, scaled, or rotated.
Example

This handler accepts a point value and a sprite reference as a parameter, and it then sets the upper left
coordinate of the specified sprite to the specified point within a Flash movie sprite in channel 10:
on snapSprite whichFlashPoint, whichSprite
sprite(whichSprite).loc = sprite(1).FlashToStage(whichFlashPoint)
updatestage
end
See also

stageToFlash()

flat
Syntax

member(whichCastmember).shader(whichShader).flat
member(whichCastmember).model(whichModel).shader.flat
member(whichCastmember).model(whichModel).shaderList{[index]}.flat
Description

3D #standard shader property; indicates whether the mesh should be rendered with flat shading
(TRUE) or Gouraud shading (FALSE).

246

Flat shading uses one color per face of the mesh. The color used for the face is the color of its first
vertex. Flat shading is faster than Gouraud shading.
Gouraud shading assigns a color to each vertex of a face and interpolates the colors across the face in
a gradient. Gouraud shading requires more time and calculation, but creates a smoother surface.
The default value for this property is FALSE.
Example

The following statement sets the flat property of the shader named Wall to TRUE. The mesh of a
model that uses this shader will be rendered with one color per face.
member("MysteryWorld").shader("Wall").flat = TRUE
See also

mesh (property), colors, vertices, generateNormals()

flipH
Syntax

sprite(whichSpriteNumber).flipH
the flipH of sprite whichSpriteNumber
Description

Sprite property; indicates whether a sprites image has been flipped horizontally on the Stage
(TRUE) or not (FALSE).
The image itself is flipped around its registration point.
This means any rotation or skew remains constant; only the image data itself is flipped.
Example

This statement displays the flipH of sprite 5:

put sprite (5).flipH
See also

flipV, rotation, skew

flipV
Syntax

sprite(whichSpriteNumber).flipV
the flipV of sprite whichSpriteNumber
Description

Sprite property; indicates whether a sprites image has been flipped vertically on the Stage (TRUE)
or not (FALSE).
The image itself is flipped around its registration point.
This means any rotation or skew remains constant; only the image data itself is flipped.
Example

This statement displays the flipV of sprite 5:

sprite (5).flipV = 1
See also

flipH, rotation, skew

247

float()
Syntax

(expression).float
float (expression)
Description

Function; converts an expression to a floating-point number. The number of digits that follow
the decimal point (for display purposes only, calculations are not affected) is set using the
floatPrecision property.
Examples

This statement converts the integer 1 to the floating-point number 1:

put (1).float
-- 1.0

Math operations can be performed using float; if any of the terms is a float value, the entire
operation is performed with float:
"the floatPrecision = 1
put 2 + 2
-- 4
put (2).float + 2
-- 4.0
the floatPrecision = 4
put 22/7
-- 3
put (22).float / 7
-- 3.1429"
See also

floatPrecision, ilk()

floatP()
Syntax

(expression).floatP
floatP(expression)
Description

Function; indicates whether the value specified by expression is a floating-point number (1 or

TRUE) or not (0 or FALSE).
The P in floatP stands for predicate.
Examples

This statement tests whether 3.0 is a floating-point number. The Message window displays the
number 1, indicating that the statement is TRUE.
put (3.0).floatP
-- 1

This statement tests whether 3 is a floating-point number. The Message window displays the
number 0, indicating that the statement is FALSE.
put (3).floatP
-- 0
See also

float(), ilk(), integerP(), objectP(), stringP(), symbolP()

248

floatPrecision
Syntax

the floatPrecision
Description

Movie property; rounds off the display of floating-point numbers to the number of decimal places
specified. The value of floatPrecision must be an integer. The maximum value is 15
significant digits; the default value is 4.
The floatPrecision property determines only the number of digits used to display
floating-point numbers; it does not change the number of digits used to perform calculations.

If floatPrecision is a number from 1 to 15, floating-point numbers display that number of

digits after the decimal point. Trailing zeros remain.

If floatPrecision is zero, floating-point numbers are rounded to the nearest integer. No

decimal points appear.

If floatPrecision is a negative number, floating-point numbers are rounded to the absolute

value for the number of decimal places. Trailing zeros are dropped.
This property can be tested and set.
Examples

This statement rounds off the square root of 3.0 to three decimal places:
the floatPrecision = 3
x = sqrt(3.0)
put x
-- 1.732

This statement rounds off the square root of 3.0 to eight decimal places:
the floatPrecision = 8
put x
-- 1.73205081

flushInputEvents
Syntax

flushInputEvents()
Description

This command will flush any waiting mouse or keyboard events from the Director message
queue. Generally this is useful when Lingo is in a tight repeat loop and the author wants to make
sure any mouse clicks or keyboard presses dont get through. This command operates at runtime
only and has no effect during authoring.
Example

This Lingo disables mouse and keyboard events while a repeat loop executes:
repeat with i = 1 to 10000
flushInputEvents()
sprite(1).loc = sprite(1).loc + point(1, 1)
end repeat
mouseDown, mouseUp, keyDown, keyUp

249

fog
Syntax

member(whichCastmember).camera(whichCamera).fog.color
sprite(whichSprite).camera{(index)}.fog.color
member(whichCastmember).camera(whichCamera).fog.decayMode
sprite(whichSprite).camera{(index)}.fog.decayMode
member(whichCastmember).camera(whichCamera).fog.enabled
sprite(whichSprite).camera{(index)}.fog.enabled
member(whichCastmember).camera(whichCamera).fog.far
sprite(whichSprite).camera{(index)}.fog.far
member(whichCastmember).camera(whichCamera).fog.near
sprite(whichSprite).camera{(index)}.fog.near
Description

3D camera property; fog introduces a coloring and blurring of models that increases with distance
from the camera. The effect is similar to real fog, except that it can be any color.
The See also section of this entry contains a complete list of fog properties. See the individual
property entries for more information.
See also

color (fog), decayMode, enabled (fog), far (fog), near (fog)

font
Syntax

member(whichCastMember).font
the font of member whichCastMember
Description

Text and field cast member property; determines the font used to display the specified cast
member and requires that the cast member contain characters, if only a space. The parameter
whichCastMember can be either a cast member name or number.
The Director player for Java doesnt map to other fonts when converting a movie; Java substitutes
the default font for any unsupported font. Use only Javas supported fonts as values for the font
member property in a movie that plays back as an applet.
Java offers only the following cross-platform fonts:
Java font name

Corresponding Windows font

Corresponding Macintosh font

Helvetica

Arial

Helvetica

TimesRoman

Times New Roman

Times

Courier

Courier-New

Courier

Dialog

MS Sans Serif

Chicago or Charcoal

DialogInput

MS Sans Serif

Geneva

ZapfDingbats

WingDings

Zapf Dingbats

Default

Arial

Helvetica

The font member property can be tested and set.

250

To see an example of font used in a completed movie, see the Text movie in the Learning/Lingo
Examples folder inside the Director application folder.
Example

This statement sets the variable named oldFont to the current font setting for the field cast
member Rokujo Speaks:
oldFont = member("Rokujo Speaks").font
See also

text, alignment, fontSize, fontStyle, lineHeight (cast member property)

fontSize
Syntax

member(whichCastMember).fontSize
the fontSize of member whichCastMember
Description

Field cast member property; determines the size of the font used to display the specified field cast
member and requires that the cast member contain characters, if only a space. The parameter
whichCastMember can be either a cast member name or number.
This property can be tested and set. When tested, it returns the height of the first line in the field.
When set, it affects every line in the field.
To see an example of fontSize used in a completed movie, see the Text movie in the Learning/
Lingo Examples folder inside the Director application folder.
Examples

This statement sets the variable named oldSize to the current fontSize
the field cast member Rokujo Speaks:

of member

setting for

oldSize = member("Rokujo Speaks").fontSize

This statement sets the third line of the text cast member myMenu to 24 points:
member("myMenu").fontSize = 12
See also

text, alignment, font, fontStyle, lineHeight (cast member property)

fontStyle
Syntax

member(whichCastMember).fontStyle
the fontStyle of member whichCastMember
member(whichCastMember).char[whichChar].fontStyle
the fontStyle of char whichChar
member(whichCastMember).word[whichWord].fontStyle
the fontStyle of word whichWord
member(whichCastMember).line[whichLine].fontStyle
the fontStyle of line whichLine

251

Description

Cast member property; determines the styles applied to the font used to display the specified field
cast member, character, line, word, or other chunk expression and requires that the field cast
member contain characters, if only a space.
The value of the property is a string of styles delimited by commas. Lingo uses a font that is a
combination of the styles in the string. The available styles are plain, bold, italic, underline,
shadow, outline, and extended; on the Macintosh, condensed also is available.
Use the style plain to remove all currently applied styles. The parameter whichCastMember can be
either a cast member name or number.
For a movie playing back as an applet, plain, bold, and italic are the only valid styles for the
member property. The Director player for Java doesnt support underline, shadow,
outline, extended, or condensed font styles.
fontStyle

This property can be tested and set.

To see an example of fontStyle used in a completed movie, see the Text movie in the Learning/
Lingo Examples folder inside the Director application folder.
Examples

This statement sets the variable named oldStyle to the current fontStyle setting for the field
cast member Rokujo Speaks:
oldStyle = member("Rokujo Speaks").fontStyle

This statement sets the fontStyle member property for the field cast member Poem to bold
italic:
member("Poem").fontStyle = [#bold, #italic]

This statement sets the fontStyle property of the third word of the cast member Sons Names
to italic:
member("Sons Names").word[3].fontStyle = [#italic]

This statement sets the fontStyle member property of word 1 through word 4 of text member
myNote to bold italic:
member("myNote").word[1..4].fontstyle = [#bold, #italic]
See also

text, alignment, fontSize, font, lineHeight (cast member property)

foreColor
Syntax

member(castName).foreColor = colorNumber
set the foreColor of member castName to colorNumber
sprite whichSprite.foreColor
the foreColor of sprite whichSprite
Description

Cast member property; sets the foreground color of a field cast member.
For a movie that plays back as an applet, specify colors for the foreColor sprite property as the
decimal equivalent of the 24-bit hexadecimal values used in an HTML document.

252

It is not recommended to apply this property to bitmap cast members deeper than 1-bit, as the
results are difficult to predict.
It is recommended that the newer color property be used instead of the foreColor property.
Examples

The hexadecimal value for pure red, FF0000, is equivalent to 16711680 in decimal numbers.
This statement specifies pure red as a cast members forecolor:
member(20).foreColor = 16711680

This statement changes the color of the field in cast member 1 to the color in palette entry 250:
member(1).foreColor = 250

The following statement sets the variable oldColor to the foreground color of sprite 5:
oldColor = sprite(5).foreColor

The following statement makes 36 the number for the foreground color of a random sprite from
sprites 11 to 13:
sprite(10 + random(3)).foreColor = 36

The following statement sets the foreColor of word 3 of line 2 of text member myDescription to
a value of 27:
member("myDescription").line[2].word[3].forecolor = 27
See also

backColor, color (sprite and cast member property)

forget()
Syntax

timeout("timeoutName").forget()
forget(timeout("timeoutName"))
Description

This timeout object function removes the given timeoutObject from the
prevents it from sending further timeout events.

timeoutList,

and

Example

This statement deletes the timeout object named AlarmClock from the

timeoutList:

timeout("AlarmClock").forget()
See also

timeout(), timeoutHandler, timeoutList, new()

253

forget
Syntax

window(whichWindow).forget()
forget window whichWindow
Description

Window property; instructs Lingo to close and delete the window specified by whichWindow
when its no longer in use and no other variables refer to it.
When a forget window command is given, the window and the movie in a window (MIAW)
disappear without calling the on stopMovie, on closeWindow, or on deactivateWindow handlers.
If there are many global references to the movie in a window, the window doesnt respond to the
command.

forget

Example

This statement instructs Lingo to delete the window Control Panel when the movie no longer
uses the window:
window("Control Panel").forget()
See also

close window, open window

frame() (function)
Syntax

the frame
Description

Function; returns the number of the current frame of the movie.

Example

This statement sends the playhead to the frame before the current frame:
go to (the frame - 1)
See also

go, label(), marker()

frame (sprite property)

Syntax

sprite(whichFlashSprite).frame
the frame of sprite whichFlashSprite
Description

Sprite property; controls which frame of the current Flash movie is displayed. The default value is 1.
This property can be tested and set.

254

Example

The following frame script checks to see if a Flash movie has finished playing (by checking to see
if the current frame is equal to the total number of frames in the movie). If the movie has not
finished, the playhead continues to loop in the current frame; when the movie finishes, the
playhead continues to the next frame. (This script assumes that the movie was designed to stop on
its final frame and that it has not been set for looped playback.)
on exitFrame
if sprite(5).frame < sprite(5).member.frameCount then
go to the frame
end if
end

frameCount
Syntax

member(whichFlashMember).frameCount
the frameCount of member whichFlashMember
Description

Flash cast member property; indicates the number of frames in the Flash movie cast member. The
frameCount member property can have integer values.
This property can be tested but not set.
Example

This sprite script displays, in the Message window, the channel number and the number of frames
in a Flash movie:
property spriteNum
on beginSprite me
put ""The Flash movie in channel"" && spriteNum && has"" &&
sprite(spriteNum).member.frameCount && ""frames.""
end

frameLabel
Syntax

the frameLabel
Description

Frame property; identifies the label assigned to the current frame. When the current frame has no
label, the value of the frameLabel property is 0.
This property can be tested at any time. It can be set during a Score generation session.
Example

The following statement checks the label of the current frame. In this case, the current
frameLabel value is Start:
put the frameLabel
-- "Start"
See also

labelList

255

framePalette
Syntax

the framePalette
Description

Frame property; identifies the cast member number of the palette used in the current frame,
which is either the current palette or the palette set in the current frame.
Because the browser controls the palette for the entire Web page, the Director player for Java
always uses the browsers palette. For the most reliable color when authoring a movie for playback
as a Director player for Java, use the default palette for the authoring system. When you want
exact control over colors, use Shockwave instead of Java.
This property can be tested. It can also be set during a Score generation session.
Examples

The following statement checks the palette used in the current frame. In this case, the palette is
cast member 45.
put the framePalette
-- 45

This statement makes palette cast member 45 the palette for the current frame:
the framePalette = 45
See also

puppetPalette

frameRate
Syntax

member(whichCastMember).frameRate
the frameRate of member whichCastMember
Description

Cast member property; specifies the playback frame rate for the specified digital video, or Flash
movie cast member.
The possible values for the frame rate of a digital video member correspond to the radio buttons
for selecting digital video playback options.

When the frameRate member property is between 1 and 255, the digital video movie plays
every frame at that frame rate. The frameRate member property cannot be greater than 255.

When the frameRate member property is set to -1 or 0, the digital video movie plays every
frame at its normal rate. This allows the video to sync to its soundtrack. When the frameRate is
set to any value other than -1 or 0, the digital video soundtrack will not play.

When the frameRate member property is set to -2, the digital video movie plays every frame
as fast as possible.
For Flash movie cast members, the property indicates the frame rate of the movie created in Flash.
This property can be tested but not set.

256

Examples

This statement sets the frame rate of the QuickTime digital video cast member Rotating Chair to
30 frames per second:
member("Rotating Chair").frameRate = 30

This statement instructs the QuickTime digital video cast member Rotating Chair to play every
frame as fast as possible:
member("Rotating Chair").frameRate = -2

The following sprite script checks to see if the sprites cast member was originally created in Flash
with a frame rate of less than 15 frames per second. If the movies frame rate is slower than 15
frames per second, the script sets the playBackMode property for the sprite so it can be set to
another rate. The script then sets the sprites fixedRate property to 15 frames per second.
property spriteNum
on beginSprite me
if sprite(spriteNum).member.frameRate < 15 then
sprite(spriteNum).playBackMode = #fixed
sprite(spriteNum).fixedRate = 15
end if
end
See also

fixedRate, movieRate, movieTime, playBackMode

frameReady()
Syntax

frameReady(frameN)
frameReady(frameN, frameZ)
frameReady()
frameReady(sprite whichFlashSprite, frameNumber)
Description

Function; for a Flash movie, determines whether a streaming movie is ready for display. If enough
of a sprite has streamed into memory to render the frame (integer for frame number, string for
label) specified in the frameNumber parameter, this function is TRUE; otherwise it is FALSE. For a
Director movie, this function determines whether all the cast members for frameN (the number
of the frame) are downloaded from the Internet and available locally.
This function is useful only when streaming a movie, range of frames, cast, or linked cast
member. To activate streaming, set the Movie:Playback properties in the Modify menu to Use
Media as Available or Show Placeholders.
For Director movies, projectors, and Shockwave movies:

frameReady (frameN)Determines

frameReady()Determines

whether the cast members for frameN are downloaded.

frameReady (frameN, frameZ)Determines

frameZ are downloaded.

whether the cast members for frameN through

if cast member used in any frame of the Score are downloaded.

For a demonstration of the frameReady function used with a Director movie, see the sample
movie Streaming Shockwave in Director Help.
This function can be tested but not set.

257

Examples

This statement determines whether the cast members for frame 20 are downloaded and ready to
be viewed:
on exitFrame
if frameReady(20) then
-- go to frame 20 if all the required
--castmembers are locally available
go to frame 20
else
-- resume animating loop while background
--is streaming
got to frame 1
end if
end

The following frame script checks to see if frame 25 of a Flash movie sprite in channel 5 can be
rendered. If it cant, the script keeps the playhead looping in the current frame of the Director
movie. When frame 25 can be rendered, the script starts the movie and lets the playhead proceed
to the next frame of the Director movie.
on exitFrame
if the frameReady(sprite 5, 25) = FALSE then
go to the frame
else
play sprite 5
end if
end
See also

mediaReady

frameScript
Syntax

the frameScript
Description

Frame property; contains the unique cast member number of the frame script assigned to the
current frame.
The frameScript property can be tested. During a Score recording session, you can also assign a
frame script to the current frame by setting the frameScript property.
Examples

The following statement displays the number of the script assigned to the current frame. In this
case, the script number is 25.
put the frameScript
-- 25

This statement makes the script cast member Button responses the frame script for the current frame:
the frameScript = member "Button responses"

258

frameSound1
Syntax

the frameSound1
Description

Frame property; determines the number of the cast member assigned to the first sound channel in
the current frame.
This property can be tested and set. This property can also be set during a Score recording session.
Example

As part of a Score recording session, this statement assigns the sound cast member Jazz to the first
sound channel:
the frameSound1 = member("Jazz").number

frameSound2
Syntax

the frameSound2
Description

Frame property; determines the number of the cast member assigned to the second sound channel
for the current frame.
This property can be tested and set. This property can also be set during a Score recording session.
Example

As part of a Score recording session, this statement assigns the sound cast member Jazz to the
second sound channel:
the frameSound2 = member("Jazz").number

framesToHMS()
Syntax

framesToHMS(frames, tempo, dropFrame, fractionalSeconds)

Description

Function; converts the specified number of frames to their equivalent length in hours, minutes,
and seconds. This function is useful for predicting the actual playtime of a movie or controlling a
video playback device.

framesInteger
tempoInteger

expression that specifies the number of frames.

expression that specifies the tempo in frames per second.

dropFrameCompensates for the color NTSC frame rate, which is not exactly 30 frames
per second and is meaningful only if FPS is set to 30 frames per second. Normally, this
argument is set to FALSE.
fractionalSecondsDetermines whether the residual frames are converted to the nearest
hundredth of a second (TRUE) or returned as an integer number of frames (FALSE).

259

The resulting string uses the form sHH:MM:SS.FFD, where:

s

A character is used if the time is less than zero, or a space if the time is greater than or equal to zero.

HH

Hours.

MM

Minutes.

SS

Seconds.

FF

Indicates a fraction of a second if fractionalSeconds is TRUE or frames if

fractionalSeconds is FALSE.

A "d" is used if dropFrame is TRUE, or a space if dropFrame is FALSE.

Example

The following statement converts a 2710-frame, 30 frame-per-second movie. The dropFrame and
fractionalSeconds arguments are both turned off:
put framesToHMS(2710, 30, FALSE, FALSE)
-- " 00:01:30.10 "
See also

HMStoFrames()

frameTempo
Syntax

the frameTempo
Description

Frame property; indicates the tempo assigned to the current frame.

This property can be tested. It can be set during a Score recording session.
Example

The following statement checks the tempo used in the current frame. In this case, the tempo is 15
frames per second.
put the frameTempo
-- 15
See also

puppetTempo

frameTransition
Syntax

the frameTransition
Description

Frame property; specifies the number of the transition cast member assigned to the current frame.
This property can be set during a Score recording session to specify transitions.

260

Example

When used in a Score recording session, this statement makes the cast member Fog the transition
for the frame that Lingo is currently recording:
set the frameTransition to member "Fog"

freeBlock()
Syntax

the freeBlock
Description

Function; indicates the size of the largest free contiguous block of memory, in bytes. A kilobyte
(K) is 1024 bytes. A megabyte (MB) is 1024 kilobytes. Loading a cast member requires a free
block at least as large as the cast member.
Example

This statement determines whether the largest contiguous free block is smaller than 10K and
displays an alert if it is:
if (the freeBlock < (10 * 1024)) then alert "Not enough memory!"
See also

freeBytes(), memorySize, ramNeeded(), size

freeBytes()
Syntax

the freeBytes
Description

Function; indicates the total number of bytes of free memory, which may not be contiguous. A
kilobyte (K) is 1024 bytes. A megabyte (MB) is 1024 kilobytes.
This function differs from freeBlock in that it reports all free memory, not just
contiguous memory.
On the Macintosh, selecting Use System Temporary Memory in the Director General Preferences
or in a projectors Options dialog box tells the freeBytes function to return all the free memory
that is available to the application. This amount equals the applications allocation shown in its
Get Info dialog box and the Largest Unused Block value in the About This Macintosh dialog box.
Example

This statement checks whether more than 200K of memory is available and plays a color movie
if it is:
if (the freeBytes > (200 * 1024)) then play movie "colorMovie"
See also

freeBlock(), memorySize, objectP(), ramNeeded(), size

261

front
Syntax

member(whichCastmember).modelResource(whichModelResource).front
Description

3D #box model resource property; indicates whether the side of the box intersected by its -Z axis
is sealed (TRUE) or open (FALSE).
The default value for this property is TRUE.
Example

This statement sets the front property of the model resource named Crate to FALSE, meaning
the front of this box will be open:
member("3D World").modelResource("Crate").front = FALSE
See also

back, bottom (3D), top (3D), left (3D), right (3D)

frontWindow
Syntax

the frontWindow
Description

System property; indicates which movie in a window (MIAW) is currently frontmost on the
screen. When the Stage is frontmost, front window is the Stage. When a media editor or
floating palette is frontmost, frontWindow returns VOID.
This property can be tested but not set.
Example

This statement determines whether the window "Music" is currently the frontmost window and,
if it is, brings the window "Try This" to the front:
if the frontWindow = "Music" then window("Try This").moveToFront
See also

activeWindow, on activateWindow, on deactivateWindow, moveToFront

generateNormals()
Syntax

member(whichCastmember).modelResource(whichModelResource).
generateNormals(style)
Description

3D #mesh model resource command; calculates the normal vectors for each vertex of the mesh.

262

If the style parameter is set to #flat, each vertex receives a normal for each face to which it
belongs. Furthermore, all three of the vertices of a face will have the same normal. For example, if
the vertices of face[1] all receive normal[1] and the vertices of face[2] all receive normal[2],
and the two faces share vertex[8], then the normal of vertex[8] is normal[1] in face[1] and
normal[2] in face[2]. Use of the #flat parameter results in very clear delineation of the
faces of the mesh.
If the style parameter is set to #smooth, each vertex receives only one normal, regardless of the
number of faces to which it belongs, and the three vertices of a face can have different normals.
Each vertex normal is the average of the face normals of all of the faces that share the vertex. Use
of the #smooth parameter results in a more rounded appearance of the faces of the mesh, except at
the outer edges of the faces at the silhouette of the mesh, which are still sharp.
A vertex normal is a direction vector which indicates the forward direction of a vertex. If the
vertex normal points toward the camera, the colors displayed in the area of the mesh controlled by
that normal are determined by the shader. If the vertex normal points away from the camera, the
area of the mesh controlled by that normal will be non-visible.
After using the generateNormals() command, you must use the build() command to rebuild
the mesh.
Example

The following statement calculates vertex normals for the model resource named FloorMesh. The
style parameter is set to #smooth, so each vertex in the mesh will receive only one normal.
member("Room").modelResource("FloorMesh").generateNormals(#smooth)
See also

build(), face, normalList, normals, flat

getaProp
Syntax

propertyList.propertyName
getaProp(list, item)
list[listPosition]
propertyList [ #propertyName ]
propertyList [ "propertyName" ]
Description

List command; for linear and property lists, identifies the value associated with the item specified
by item, listPosition, or propertyName in the list specified by list.

When the list is a linear list, replace item with the number for an items position in a list as
shown by listPosition. The result is the value at that position.

When the list is a property list, replace item with a property in the list as in propertyName.
The result is the value associated with the property.
The getaProp command returns VOID when the specified value is not in the list.
When used with linear lists, the getaProp command has the same function as the getAt command.

263

Examples

This statement identifies the value associated with the property #joe in the property list ages,
which consists of [#john:10, #joe:12, #cheryl:15, #barbara:22]:
put getaProp(ages, #joe)

The result is 12, because this is the value associated with the property #joe.
The same result can be achieved using bracket access on the same list:
put ages[#joe]

The result is again 12.

If you want the value at a certain position in the list, you can also use bracket access. To get the
third value in the list, associated with the third property, use this syntax:
put ages[3]
-- 15
Note: Unlike the getAProp command where VOID is returned when a property doesnt exist, a script error will occur
if the property doesnt exist when using bracket access.

See also

getAt, getOne(), getProp(), setaProp, setAt

getAt
Syntax

getAt(list, position)
list [position]
Description

List command; identifies the item in the position specified by position in the specified list. If
the list contains fewer elements than the specified position, a script error occurs.
The getAt command works with linear and property lists. This command has the same function
as the getaProp command for linear lists.
This command is useful for extracting a list from within another list, such as the
deskTopRectList.
Examples

This statement causes the Message window to display the third item in the answers list, which
consists of [10, 12, 15, 22]:
put getAt(answers, 3)
-- 15

The same result can be returned using bracket access:

put answers[3]
-- 15

264

The following example extracts the first entry in a list containing two entries that specify name,
department, and employee number information. Then the second element of the newly extracted
list is returned, identifying the department in which the first person in the list is employed. The
format of the list is [[Dennis, consulting, 510], [Sherry, Distribution, 973]], and the list is
called employeeInfoList.
firstPerson = getAt(employeeInfoList, 1)
put firstPerson
-- ["Dennis", "consulting", 510]
firstPersonDept = getAt(firstPerson, 2)
put firstPersonDept
-- "consulting"

Its also possible to nest getAt commands without assigning values to variables in intermediate
steps. This format can be more difficult to read and write, but less verbose.
firstPersonDept = getAt(getAt(employeeInfoList, 1), 2)
put firstPersonDept
-- "consulting"

You can also use the bracket list access:

firstPerson = employeeInfoList[1]
put firstPerson
-- ["Dennis", "consulting", 510]
firstPersonDept = firstPerson[2]
put firstPersonDept
-- "consulting"

As with getAt, brackets can be nested:

firstPersonDept = employeeInfoList[1][2]
See also

getaProp, setaProp, setAt

on getBehaviorDescription
Syntax

on getBehaviorDescription
statement(s)
end
Description

System message and event handler; contains Lingo that returns the string that appears in a
behaviors description pane in the Behavior Inspector when the behavior is selected.
The description string is optional.
Director sends the getBehaviorDescription message to the behaviors attached to a sprite when
the Behavior Inspector opens. Place the on getBehaviorDescription handler within a behavior.
The handler can contain embedded Return characters for formatting multiple-line descriptions.
Example

This statement displays Vertical Multiline textField Scrollbar in the description pane:
on getBehaviorDescription
return "Vertical Multiline textField Scrollbar"
end
See also

on getPropertyDescriptionList, on getBehaviorTooltip, on runPropertyDialog

265

on getBehaviorTooltip
Syntax

on getBehaviorTooltip
statement(s)
end
Description

System message and event handler; contains Lingo that returns the string that appears in a tooltip
for a script in the Library palette.
Director sends the getBehaviorTooltip message to the script when the cursor stops over it in
the Library palette. Place the on getBehaviorTooltip handler within the behavior.
The use of the handler is optional. If no handler is supplied, the cast member name appears in
the tooltip.
The handler can contain embedded Return characters for formatting multiple-line descriptions.
Example

This statement displays Jigsaw puzzle piece in the description pane:

on getBehaviorTooltip
return "Jigsaw puzzle piece"
end
See also

on getPropertyDescriptionList, on getBehaviorDescription, on runPropertyDialog

getBoneID
Syntax

memberReference.modelResource.getBoneID("boneName")
Description

3D model resource property; returns the index number of the bone named boneName in the
model resource. This property returns 0 if no bone by that name can be found.
Example

This statement returns an ID number for the bone ShinL:

put member("ParkScene").modelResource("LittleKid").getBoneId("ShinL")
-- 40
See also

bone

getError()
Syntax

member(whichSWAmember).getError()
getError(member whichSWAmember)
member(whichFlashmember).getError()
getError(member whichFlashmember)

266

Description

Function; for Shockwave Audio (SWA) or Flash cast members, indicates whether an error
occurred as the cast member streamed into memory and returns a value.
Shockwave Audio cast members have the following possible getError() integer values and
corresponding getErrorString() messages:
getError() value

getErrorString() message

OK

memory

network

playback device

99

other

Flash movie cast members have the following possible getError values:

FALSENo

error occurred.

#memoryThere

is not enough memory to load the cast member.

#fileNotFoundThe
#networkA

file containing the cast members assets could not be found.

network error prevented the cast member from loading.

#fileFormatThe file was found, but it appears to be of the wrong type, or an error occurred
while reading the file.
#otherSome

other error occurred.

When an error occurs as a cast member streams into memory, Director sets the cast members
state property to -1. Use the getError function to determine what type of error occurred.
Examples

This handler uses getError to determine whether an error involving the Shockwave Audio cast
member Norma Desmond Speaks occurred and displays the appropriate error string in a field if it did:
on exitFrame
if member("Norma Desmond Speaks").getError() <> 0 then
member("Display Error Name").text = member("Norma Desmond \
Speaks").getErrorString()
end if
end

267

The following handler checks to see whether an error occurred for a Flash cast member named
Dali, which was streaming into memory. If an error occurred, and it was a memory error, the
script uses the unloadCast command to try to free some memory; it then branches the playhead
to a frame in the Director movie named Artists, where the Flash movie sprite first appears, so
Director can again try to load and play the Flash movie. If something other than an out-ofmemory error occurred, the script goes to a frame named Sorry, which explains that the requested
Flash movie cant be played.
on CheckFlashStatus
errorCheck = member("Dali").getError()
if errorCheck <> 0 then
if errorCheck = #memory then
member("Dali").clearError()
unloadCast
go to frame ("Artists")
else
go to frame ("Sorry")
end if
end if
end
See also

clearError, getErrorString(), state (Flash, SWA)

getError() (XML)
Syntax

parserObject.getError()
Description

Function; returns the descriptive error string associated with a given error number (including the
line and column number of the XML where the error occurred). When there is no error, this
function returns <VOID>.
Example

These statements check an error after parsing a string containing XML data:
errCode = parserObj.parseString(member("XMLtext").text)
errorString = parserObj.getError()
if voidP(errorString) then
-- Go ahead and use the XML in some way
else
alert "Sorry, there was an error " & errorString
-- Exit from the handler
exit
end if

getErrorString()
Syntax

member(whichCastMember). getErrorString()
getErrorString(member whichCastMember)
Description

Function; for Shockwave Audio (SWA) cast members, returns the error message string that
corresponds to the error value returned by the getError() function.

268

Possible getError() integer values and corresponding getErrorString() messages are:

getError() value

getErrorString() message

OK

memory

network

playback device

99

other

Example

This handler uses getError() to determine whether an error occurred for Shockwave Audio cast
member Norma Desmond Speaks, and if so, uses getErrorString to obtain the error message
and assign it to a field cast member:
on exitFrame
if member("Norma Desmond Speaks").getError() <> 0 then
member("Display Error Name").text = member("Norma Desmond \
Speaks").getErrorString()
end if
end
See also

getError()

getFlashProperty()
Syntax

sprite(spriteNum).getFlashProperty("targetName", #property)
Description

This function allows Lingo to invoke the Flash action script function getProperty() on the
given Flash sprite. This Flash action script function is used to get the value of properties of movie
clips or levels within a Flash movie. This is similar to testing sprite properties within Director.
The targetName is the name of the movie clip or level whose property you want to get within the
given Flash sprite.
The #property parameter is the name of the property to get. These movie clip properties can be
tested: #posX, #posY, #scaleX, #scaleY, #visible, #rotate, #alpha, #name, #width, #height,
#target, #url, #dropTarget, #totalFrames, #currentFrame, #cursor, and
#lastframeLoaded.
To get a global property of the Flash sprite, pass an empty string as the targetName. These global
Flash properties can be tested: #focusRect and #spriteSoundBufferTime.
See the Flash documentation for descriptions of these properties.
Example

This statement gets the value of the #rotate property of the movie clip Star in the Flash member
in sprite 3:
sprite(3).setFlashProperty("Star", #rotate)
setFlashProperty()

269

getFrameLabel()
Syntax

sprite(whichFlashSprite).getFrameLabel(whichFlashFrameNumber)
getFrameLabel(sprite whichFlashSprite, whichFlashFrameNumber)
Description

Function; returns the frame label within a Flash movie that is associated with the frame number
requested. If the label doesnt exist, or that portion of the Flash movie has not yet been streamed
in, this function returns an empty string.
Example

The following handler looks to see if the marker on frame 15 of the Flash movie playing in sprite
1 is called "Lions". If it is, the Director movie navigates to frame "Lions". If it isnt, the Director
movie stays in the current frame and the Flash movie continues to play.
on exitFrame
if sprite(1).getFrameLabel(15) = "Lions" then
go "Lions"
else
go the frame
end if
end

getHardwareInfo()
Syntax

getRendererServices().getHardwareInfo()
Description

3D rendererServices method; returns a property list with information about the users video
card. The list contains the following properties:
#present
#vendor
#model

is a Boolean value indicating whether the computer has hardware video acceleration.

indicates the name of the manufacturer of the video card.

indicates the model name of the video card.

#version

indicates the version of the video driver.

#maxTextureSize is a linear list containing the maximum width and height of a texture, in
pixels. Textures that exceed this size are downsampled until they do not. To avoid texture
sampling artifacts, author textures of various sizes and choose the ones that do not exceed the
#maxTextureSize value at run time.
#supportedTextureRenderFormats is a linear list of
video card. For details, see textureRenderFormat.
#textureUnits

texture pixel formats supported by the

indicates the number of texture units available to the card.

#depthBufferRange

is a linear list of bit-depth resolutions to which the depthBufferDepth

property can be set.

#colorBufferRange

property can be set.

270

is a linear list of bit-depth resolutions to which the colorBufferDepth

Example

This statement displays a detailed property list of information about the users hardware:
put getRendererServices().getHardwareInfo()
-- [#present: 1, #vendor: "NVIDIA Corporation", #model: \
"32MB DDR NVIDIA GeForce2 GTS (Dell)", #version: "4.12.01.0532", \
#maxTextureSize: [2048, 2048], #supportedTextureRenderFormats: \
[#rgba8888, #rgba8880, #rgba5650, #rgba5551, #rgba5550, \
#rgba4444], #textureUnits: 2, #depthBufferRange: [16, 24], \
#colorBufferRange: [16, 32]]
See also

getRendererServices()

getHotSpotRect()
Syntax

sprite(whichQTVRSprite).getHotSpotRect(hotSpotID)
getHotSpotRect(whichQTVRSprite, hotSpotID)
Description

QuickTime VR function; returns an approximate bounding rectangle for the hot spot specified
by hotSpotId. If the hot spot doesnt exist or isnt visible on the Stage, this function returns
rect(0, 0, 0, 0). If the hot spot is partially visible, this function returns the bounding rectangle for
the visible portion.

getLast()
Syntax

list.getLast()
getLast(list)
Description

List function; identifies the last value in a linear or property list specified by list.
Examples

This statement identifies the last item, 22, in the list Answers, which consists of [10, 12, 15, 22]:
put Answers.getLast()

This statement identifies the last item, 850, in the list Bids, which consists of [#Gee:750,
#Kayne:600, #Ohashi:850]:
put Bids.getLast()

getLatestNetID
Syntax

getLatestNetID
Description

This function returns an identifier for the last network operation that started.
The identifier returned by getLatestNetID can be used as a parameter in the netDone,
netError, and netAbort functions to identify the last network operation.

271

Note: This function is included for backward compatibility. It is recommended that you use the network ID returned
from a net lingo function rather than getLatestNetID. However, if you use getLatestNetID, use it immediately
after issuing the netLingo command.

Example

This script assigns the network ID of a getNetText operation to the field cast member Result so
results of that operation can be accessed later:
on startOperation
global gNetID
getNetText("url")
set gNetID = getLatestNetID()
end
on checkOperation
global gNetID
if netDone(gNetID) then
put netTextResult into member "Result"
end if
end
See also

netAbort, netDone(), netError()

getNetText()
Syntax

getNetText(URL {, serverOSString} {, characterSet})

getNetText(URL, propertyList {, serverOSString} {, characterSet})
Description

Function; starts the retrieval of text from a file usually on an HTTP or FTP server, or initiates a
CGI query.
The first syntax shown starts the text retrieval. You can submit HTTP CGI queries this way and
must properly encode them in the URL. The second syntax includes a property list and submits a
CGI query, providing the proper URL encoding.
Use the optional parameter propertyList to take a property list for CGI queries. The property
list is URL encoded and the URL sent is (urlstring & "?" & encodedproplist).
Use the optional parameter serverOSString to encode any return characters in propertylist.
The value defaults to UNIX but may be set to Win or Mac and translates any carriage returns in the
propertylist argument into those used on the server. For most applications, this setting is
unnecessary because line breaks are usually not used in form responses.
The optional parameter characterSet applies only if the user is running Director on a
(Japanese) system. Possible character set settings are JIS, EUC, ASCII, and AUTO.
Lingo converts the retrieved data from shift-JIS to the named character set. Using the AUTO
setting, character set tries to determine what character set the retrieved text is in and translate it to
the character set on the local machine. The default setting is ASCII.

shift-JIS

For a movie that plays back as an applet, the getNetText command retrieves text only from the
domain that contains the applet. This behavior differs from Shockwave and is necessary due to
Javas security model.
Use netDone to find out when the getNetText operation is complete, and netError to find out
if the operation was successful. Use netTextResult to return the text retrieved by getNetText.

272

The function works with relative URLs.

To see an example of getNetText() used in a completed movie, see the Forms and Post movie in
the Learning/Lingo Examples folder inside the Director application folder.
Examples

This script retrieves text from the URL http://BigServer.com/sample.txt and updates the field cast
member the mouse pointer is on when the mouse button is clicked:
property spriteNum
property theNetID
on mouseUp me
theNetID = getNetText ("http://BigServer.com/sample.txt")
end
on exitFrame me
if netDone(theNetID) then
sprite(spriteNum).member.text = netTextResult(theNetID)
end if
end

This example retrieves the results of a CGI query:

getNetText("http://www.yourserver.com/cgi-bin/query.cgi?name=Bill")

This is the same as the previous example, but it uses a property list to submit a CGI query, and
does the URL encoding for you:
getNetText("http://www.yourserver.com/cgi-bin/query.cgi", [#name:"Bill"])
See also

netDone(), netError(), netTextResult()

getNormalized
Syntax

getNormalized(vector)
vector.getNormalized()
Description

3D vector method; copies the vector and divides the x, y, and z components of the copy by the
length of the original vector. The resulting vector has a length of 1 world unit.
This method returns the copy and leaves the original vector unchanged. To normalize the original
vector, use the normalize command.
Example

The following statement stores the normalized value of the vector MyVec in the variable Norm.
The value of Norm is vector( -0.1199, 0.9928, 0.0000 ) and the magnitude of Norm is 1.
MyVec = vector(-209.9019, 1737.5126, 0.0000)
Norm = MyVec.getNormalized()
put Norm
-- vector( -0.1199, 0.9928, 0.0000 )
put Norm.magnitude
-- 1.0000
See also

normalize

273

getNthFileNameInFolder()
Syntax

getNthFileNameInFolder(folderPath, fileNumber)
Description

Function; returns a filename from the directory folder based on the specified path and number
within the folder. To be found by the getNthFileNameInFolder function, Director movies must
be set to visible in the folder structure. (On the Macintosh, other types of files are found whether
they are visible or invisible.) If this function returns an empty string, you have specified a number
greater than the number of files in the folder.
The getNthFileNameInFolder function doesnt work with URLs.
To specify other folder names, use the @ pathname operator or the full path defined in the format
for the specific platform on which the movie is running. For example:

In Windows, use a directory path such as C:/Director/Movies.

On the Macintosh, use a pathname such as HardDisk:Director:Movies. To look for files on the
Macintosh desktop, use the path HardDisk:Desktop Folder

This function is not available in Shockwave.

Example

The following handler returns a list of filenames in the folder on the current path. To call the
function, use parentheses, as in put currentFolder().
on currentFolder
fileList = [ ]
repeat with i = 1 to 100
n = getNthFileNameInFolder(the moviePath, i)
if n = EMPTY then exit repeat
fileList.append(n)
end repeat
return fileList
end currentFolder
See also

@ (pathname)

getOne()
Syntax

list.getOne(value)
getOne(list, value)
Description

List function; identifies the position (linear list) or property (property list) associated with the
value specified by value in the list specified by list.
For values contained in the list more than once, only the first occurrence is displayed. The
command returns the result 0 when the specified value is not in the list.

getOne

When used with linear lists, the getOne command performs the same functions as the
command.

getPos

274

Examples

This statement identifies the position of the value 12 in the linear list Answers, which consists of
[10, 12, 15, 22]:
put Answers.getOne(12)

The result is 2, because 12 is the second value in the list.

This statement identifies the property associated with the value 12 in the property list Answers,
which consists of [#a:10, #b:12, #c:15, #d:22]:
put Answers.getOne(12)

The result is #b, which is the property associated with the value 12.
See also

getPos()

getPixel()
Syntax

imageObject.getPixel(x, y {, #integer})
imageObject.getPixel(point(x, y) {, #integer})
Description

This function returns the color value of the pixel at the specified point in the given image object.
This value is normally returned as an indexed or RGB color object, depending on the bit depth
of the image.
If you include the optional parameter value #integer, however, its returned as a raw number. If
youre setting a lot pixels to the color of another pixel, its faster to set them as raw numbers. Raw
integer color values are also useful because they contain alpha layer information as well as color
when the image is 32-bit. The alpha channel information can be extracted from the raw integer
by dividing the integer by 2^8+8+8.
GetPixel()

returns 0 if the given pixel is outside the specified image object.

Examples

These statements get the color of the pixel at point (90, 20) in member Happy and set sprite 2 to
that color:
myColor=member("Happy").image.getPixel(90, 20)
sprite(2).color=myColor

This statement sets the variable alpha to the alpha channel value of the point (25, 33) in the 32bit image object myImage:
alpha = myImage.getPixel(25, 33, #integer) / power(2, 8+8+8)
See also

depth, color(), setPixel(), power()

275

getPlaylist()
Syntax

sound(channelNum).getPlaylist()
getPlaylist(sound(channelNum))
Description

This function returns a copy of the list of queued sounds for soundObject. This list does not
include the currently playing sound.
The list of queued sounds may not be edited directly. You must use setPlayList().
The playlist is a linear list of property lists. Each property list corresponds to one queued sound
cast member. Each queued sound may specify these properties:
Property

Description

#member

The sound cast member to play. This property will always be present; all others are optional.

#startTime

The time within the sound at which playback begins, in milliseconds. See startTime.

#endTime

The time within the sound at which playback ends, in milliseconds. See endTime.

#loopCount

The number of times to play a portion of the sound. See loopCount.

#loopStartTime

The time within the sound at which a loop begins, in milliseconds. See loopStartTime.

#loopEndTime

The time within the sound at which a loop ends, in milliseconds. See loopEndTime.

#preloadTime

The amount of the sound to buffer before playback, in milliseconds. See preloadTime.

Example

The following handler queues two sounds in sound channel 2, starts playing them, and then
displays the playList in the message window. The playlist includes only the second sound queued,
because the first sound is already playing.
on playMusic
sound(2).queue([#member:member("chimes")])
sound(2).queue([#member:member("introMusic"), #startTime:3000,\
#endTime:10000, #loopCount:5,#loopStartTime:8000, #loopEndTime:8900])
sound(2).play()
put sound(2).getPlaylist()
end
-- [[#member: (member 12 of castLib 2), #startTime: 3000, #endTime: 10000,
#loopCount: 5, #loopStartTime: 8000, #loopEndTime: 8900]]
See also

endTime, loopCount, loopEndTime, loopStartTime, member (keyword), preLoadTime,

queue(), setPlaylist(), startTime

276

getPos()
Syntax

list.getPos(value)
getPos(list, value)
Description

List function; identifies the position of the value specified by value in the list specified by list.
When the specified value is not in the list, the getPos command returns the value 0.
For values contained in the list more than once, only the first occurrence is displayed. This
command performs the same function as the getOne command when used for linear lists.
Example

This statement identifies the position of the value 12 in the list Answers, which consists of [#a:10,
#b:12, #c:15, #d:22]:
put Answers.getPos(12)

The result is 2, because 12 is the second value in the list.

See also

getOne()

getPref()
Syntax

getPref(prefFileName)
Description

Function; retrieves the content of the specified file.

When you use this function, replace prefFileName with the name of a file created by the
setPref function. If no such file exists, getPref returns VOID.
The filename used for prefFileName must be a valid filename only, not a full path; Director
supplies the path. The path to the file is handled by Director. The only valid file extensions for
prefFileName are .txt and .htm; any other extension is rejected.
Do not use this command to access read-only or locked media.
Note: In a browser, data written by setPref is not private. Any Shockwave movie can read this information and
upload it to a server. Confidential information should not be stored using setPref.

To see an example of getPref() used in a completed movie, see the Read and Write Text movie
in the Learning/Lingo Examples folder inside the Director application folder.
Example

This handler retrieves the content of the file Test and then assigns the files text to the field Total Score:
on mouseUp
theText = getPref("Test")
member("Total Score").text = theText
end
See also

setPref

277

getProp()
Syntax

getProp(list, property)
list.property
Description

Property list function; identifies the value associated with the property specified by property in
the property list specified by list.
Almost identical to the getaProp command, the getProp command displays an error message if
the specified property is not in the list or if you specify a linear list.
Example

This statement identifies the value associated with the property #c in the property list Answers,
which consists of [#a:10, #b:12, #c:15, #d:22]:
getProp(Answers, #c)

The result is 15, because 15 is the value associated with #c.

See also

getOne()

getPropAt()
Syntax

list.getPropAt(index)
getPropAt(list, index)
Description

Property list function; for property lists only, identifies the property name associated with the
position specified by index in the property list specified by list. If the specified item isnt in the
list, or if you use getPropAt() with a linear list, a script error occurs.
Example

This statement displays the second property in the given list:

put Answers.getPropAt(2)
-- #b

The result is 20, which is the value associated with #b.

on getPropertyDescriptionList
Syntax

on getPropertyDescriptionList
statement(s)
end
Description

System message and event handler; contains Lingo that generates a list of definitions and labels
for the parameters that appear in a behaviors Parameters dialog box.
Place the on getPropertyDescriptionList handler within a behavior script. Behaviors that
dont contain an on getPropertyDescriptionList handler dont appear in the Parameters
dialog box and cant be edited from the Director interface.

278

The on getPropertyDescriptionList message is sent when any action that causes the
Behavior Inspector to open occurs: either when the user drags a behavior to the Score or the user
double-clicks a behavior in the Behavior Inspector.
The #default, #format, and #comment settings are mandatory for each parameter. The
following are possible values for these settings:
#default

The parameters initial setting.

#format

#integer #float #string #symbol #member #bitmap #filmloop #field #palette

#picture #sound #button #shape #movie #digitalvideo #script #richtext
#ole #transition #xtra #frame #marker #ink #boolean

#comment

A descriptive string that appears to the left of the parameters editable field in the Parameters
dialog box.

#range

A range of possible values that can be assigned to a property. The range is specified as a linear
list with several values or as a minimum and maximum in the form of a property list: [#min:
minValue, #max: maxValue].

Example

The following handler defines a behaviors parameters that appear in the Parameters dialog box.
Each statement that begins with addProp adds a parameter to the list named description. Each
element added to the list defines a property and the propertys #default, #format, and
#comment values:
on getPropertyDescriptionList
description = [:]
addProp description,#dynamic, [#default:1, #format:#boolean,
#comment:"Dynamic"]
addProp description,#fieldNum, [#default:1, #format:#integer, \
#comment:"Scroll which sprite:"]
addProp description, #extentSprite,[#default:1,#format:#integer, \
#comment: "Extend Sprite:"]
addProp description,#proportional,[#default:1,#format:#boolean, \
#comment: "Proportional:"]
return description
end
See also

addProp, on getBehaviorDescription, on runPropertyDialog

getRendererServices()
Syntax

getRendererServices()
getRendererServices().whichGetRendererServicesProperty
Description

3D command; returns the rendererServices object. This object contains hardware information
and properties that affect all 3D sprites and cast members.
The rendererServices object has the following properties:

renderer

indicates the software rasterizer used to render all 3D sprites.

returns a list of software rasterizers available on the users system.

Possible values include #openGL, #directX5_2, #directX7_0, and #software. The value of
renderer must be one of these. This property can be tested but not set.
rendererDeviceList

279

textureRenderFormat indicates the pixel format used by the renderer. Possible values include
#rgba8888, #rgba8880, #rgba5650, #rgba5550, #rgba5551, and #rgba4444. The four digits

in each symbol indicate how many bits are used for each red, green, blue, and alpha component.

depthBufferDepth

indicates the bit depth of the hardware output buffer.

colorBufferDepth

indicates the bit depth of the color buffer. This property can be tested

but not set.

modifiers is a linear list of modifiers available for use by models in 3D cast members. Possible
values include #collision, #bonesPlayer, #keyframePlayer, #toon, #lod, #meshDeform,
#sds, #inker, and third-party Xtra-based modifiers. This property can be tested but not set.

primitives

is a linear list of primitive types available for use in the creation of new model
resources. Possible values include #sphere, #box, #cylinder, #plane, #particle, and
third-party Xtra-based primitive types. This property can be tested but not set.

Note: For more detailed information about these properties, see the individual property entries.

See also

renderer, preferred3DRenderer, active3dRenderer, rendererDeviceList

getStreamStatus()
Syntax

getStreamStatus(netID)
getStreamStatus(URLString)
Description

Function; returns a property list matching the format used for the globally available
tellStreamStatus function that can be used with callbacks to sprites or objects. The list
contains the following strings:
#URL

String containing the URL location used to start the network operation.

#state

String consisting of Connecting, Started, InProgress, Complete, Error, or NoInformation (this

last string is for the condition when either the net ID is so old that the status information has been
dropped or the URL specified in URLString was not found in the cache).

#bytesSoFar

Number of bytes retrieved from the network so far.

#bytesTotal

Total number of bytes in the stream, if known. The value may be 0 if the HTTP server does not
include the content length in the MIME header.

#error

String containing (EMPTY) if the download is not complete, OK if it completed successfully, or an

error code if the download ended with an error.

For example, you can start a network operation with getNetText() and track its progress with
getStreamStatus().
Example

This statement displays in the message window the current status of a download begun with
getNetText() and the resulting net ID placed in the variable netID:
put getStreamStatus(netID)
-- [#URL: "www.macromedia.com", #state: "InProgress", #bytesSoFar: 250,
#bytesTotal: 50000, #error: EMPTY]
See also

on streamStatus, tellStreamStatus()

280

getVariable()
Syntax

sprite(flashSpriteNum).getVariable("variableName" {, returnValueOrReference})
getVariable(sprite flashSpriteNum, "variableName" {, returnValueOrReference})
Description

Function; returns the current value of the given variable from the specified Flash sprite. Flash
variables were introduced in Flash version 4.
This function can be used in two ways.
Setting the optional returnValueOrReference parameter to TRUE (the default) returns the
current value of the variable as a string. Setting the returnValueOrReference parameter to
FALSE returns the current literal value of the Flash variable.
If the value of the Flash variable is an object reference, you must set the
returnValueOrReference parameter to FALSE in order for the returned value to have meaning
as an object reference. If it is returned as a string, the string will not be a valid object reference.
Examples

This statement sets the variable tValue to the string value of the Flash variable named gOtherVar
in the Flash movie in sprite 3:
tValue = sprite(3).getVariable("gOtherVar",TRUE)
put tValue
-- "5"

This statement sets the variable tObject to refer to the same object that the variable named gVar
refers to in the Flash movie in sprite 3:
tObject = sprite(3).getVariable("gVar",FALSE)

This statement returns the value of the variable currentURL from the Flash cast member in sprite
3 and displays it in the Message window:
put getVariable(sprite 3, "currentURL")
-- "http://www.macromedia.com/software/flash/"
See also

setVariable()

getWorldTransform()
Syntax

member(whichCastmember).node(whichNode).getWorldTransform()
member(whichCastmember).node(whichNode).getWorldTransform().\
position
member(whichCastmember).node(whichNode).getWorldTransform().\
rotation
member(whichCastmember).node(whichNode).getWorldTransform().scale
Description

3D command; returns the world-relative transform of the model, group, camera, or light
represented by node.

281

The transform property of a node is calculated relative to the transform of the nodes parent, and
is therefore parent-relative. The getWorldTransform() command calculates the nodes transform
relative to the origin of the 3D world, and is therefore world-relative.
Use member(whichCastmember).node(whichNode).getWorldTransform().
position to find the position property of the nodes world-relative transform. You can also use
worldPosition as a shortcut for getWorldTransform().position.
Use member(whichCastmember).node(whichNode).getWorldTransform().
rotation to find the rotation property of the nodes world-relative transform.
Use member(whichCastmember).node(whichNode).getWorldTransform().
scale to find the scale property of the nodes world-relative transform.
These properties can be tested but not set.
Example

This statement shows the world-relative transform of the model named Box, followed by its
position and rotation properties:
put member("3d world").model("Box").getworldTransform()
-- transform(1.000000,0.000000,0.000000,0.000000, \
0.000000,1.000000,0.000000,0.000000, \
0.000000,0.000000,1.000000,0.000000, - \
94.144844,119.012825,0.000000,1.000000)
put member("3d world").model("Box"). getworldTransform().position
-- vector(-94.1448, 119.0128, 0.0000)
put member("3d world").model("Box"). getworldTransform().rotation
--vector(0.0000, 0.0000, 0.0000)
See also

worldPosition, transform (property)

global
Syntax

global variable1 {, variable2} {, variable3}...

Description

Keyword; defines a variable as a global variable so that other handlers or movies can share it.
Every handler that examines or changes the content of a global variable must use the global
keyword to identify the variable as global. Otherwise, the handler treats the variable as a local
variable, even if it is declared to be global in another handler.
Note: To ensure that global variables are available throughout a movie, declare and initialize them in the
prepareMovie handler. Then, if you leave and return to the movie from another movie, your global variables will be
reset to the initial values unless you first check to see that they arent already set.

A global variable can be declared in any handler or script. Its value can be used by any other
handlers or scripts that also declare the variable as global. If the script changes the variables value,
the new value is available to every other handler that treats the variable as global.
A global variable is available in any script or movie, regardless of where it is first declared; it is not
automatically cleared when you navigate to another frame, movie, or window.
Any variables manipulated in the Message window are automatically global, even though they are
not explicitly declared as such.

282

Shockwave movies playing on the Internet cannot access global variables within other movies,
even movies playing on the same HTML page. The only way movies can share global variables is
if an embedded movie navigates to another movie and replaces itself through either
goToNetMovie or go movie.
Example

The following example sets the global variable StartingPoint to an initial value of 1 if it doesnt
already contain a value. This allows navigation to and from the movie without loss of stored data.
global gStartingPoint
on prepareMovie
if voidP(gStartingPoint) then gStartingPoint = 1
end
See also

showGlobals, property, gotoNetMovie

globals
Syntax

the globals
Description

System property; this property contains a special property list of all current global variables with a
value other than VOID. Each global variable is a property in the list, with the associated paired value.
You can use the following list operations on globals:

count()Returns

the number of entries in the list.

getPropAt(n)Returns
getProp(x)Returns

the name of the nth entry.

the value of an entry with the specified name.

getAProp(x)Returns

the value of an entry with the specified name.

Note: The globals property automatically contains the property #version, which is the version of Director running.
This means there will always be at least one entry in the list, even if no global variables have been declared yet.

This property differs from showGlobals in that the globals can be used in contexts other than
the Message window. To display the globals in the Message window, use showGlobals.
See also

showGlobals, clearGlobals

glossMap
Syntax

member(whichCastmember).shader(whichShader).glossMap
member(whichCastmember).model(whichModel).shader.glossMap
member(whichCastmember).model(whichModel).shaderList{[index]}.\
glossMap
Description

3D #standard shader property; specifies the texture to use for gloss mapping.

283

When you set this property, the following properties are automatically set:

The fourth texture layer of the shader is set to the texture you specified.
The value of textureModeList[4] is set to #none.
The value of blendFunctionList[4] is set to #multiply.
Example

This statement sets the texture named Oval as the glossMap value for the shader used by the
model named GlassBox:
member("3DPlanet").model("GlassBox").shader.glossMap = \
member("3DPlanet").texture("Oval")
See also

blendFunctionList, textureModeList, region, specularLightMap, diffuseLightMap

gravity
Syntax

member(whichCastmember).modelResource(whichModelResource).gravity
Description

3D particle model resource property; when used with a model resource whose type is #particle,
allows you to get or set the gravity property of the resource as a vector.
This property defines the gravity force applied to all particles in each simulation step.
The default value for this property is vector(0,0,0).
Example

In this example, ThermoSystem is a model resource of the type #particle. This statement sets the
gravity property of ThermoSystem to the vector (0, -.1, 0), which pulls the particles of
thermoSystem gently down the y axis.
member("Fires").modelResource("ThermoSystem").gravity = \
vector(0, -.1, 0)
See also

drag, wind

go
Syntax

go {to} {frame} whichFrame

go {to} movie whichMovie
go {to} {frame} whichFrame of movie whichMovie
Description

Command; causes the playhead to branch to the frame specified by whichFrame in the movie
specified by whichMovie. The expression whichFrame can be a marker label or an integer frame
number. The expression whichMovie must specify a movie file. (If the movie is in another folder,
whichMovie must specify the path.)

284

The phrase go loop tells the playhead to loop to the previous marker and is a convenient means
of keeping the playhead in the same section of the movie while Lingo remains active and avoids
the use of go to the frame in a frame that has a transition which would slow the movie and
overwhelm the processor.
It is best to refer to marker labels instead of frame numbers; editing a movie can cause frame
numbers to change. Using marker labels also makes it easier to read scripts.
The go to movie command loads frame 1 of the movie. If the command is called from within a
handler, the handler in which it is placed continues executing. To suspend the handler while playing
the movie, use the play command, which may be followed by a subsequent play done to return.
When you specify a movie to play, specify its path if the movie is in a different folder, but to
prevent a potential load failure, dont include the movies .dir, .dxr or .dcr file extension.
To more efficiently go to a movie at a URL, use the downloadNetThing command to download
the movie file to a local disk first and then use the go to movie command to go to that movie on
the local disk.
The following are reset when a movie is loaded: beepOn and constraint properties;
keyDownScript, mouseDownScript, and mouseUpScript; cursor and immediate sprite
properties; cursor and puppetSprite commands; and custom menus. However, the
timeoutScript is not reset when loading a movie.
Examples

This statement sends the playhead to the marker named start:

go to "start"

This statement sends the playhead to the marker named Memory in the movie named
Noh Tale to Tell:
go frame("Memory") of movie("Noh Tale to Tell")

The following handler tells the movie to loop in the current frame. This handler is useful for
making the movie wait in a frame while it plays so the movie can respond to events.
on exitFrame
go the frame
end
See also

downloadNetThing, gotoNetMovie, label(), marker(), pathName (movie property), play,

play done

go loop
Syntax

go loop
Description

Command; sends the playhead to the previous marker in the movie, either one marker back from
the current frame if the current frame does not have a marker, or to the current frame if the
current frame has a marker.
Note: This command is equivalent to marker(0) in versions of Director prior to Director 7.

285

If no markers are to the left of the playhead, the playhead branches to:

The next marker to the right if the current frame does not have a marker.
The current frame if the current frame has a marker.
Frame 1 if the movie contains no markers.
The go loop command is equivalent to the statement go
versions of Lingo.

to the marker(0)

used in earlier

Example

This statement causes the movie to loop between the current frame and the previous marker:
go loop
See also

go, go next, go previous

go next
Syntax

go next
Description

Command; sends the playhead to the next marker in the movie. If no markers are to the right of
the playhead, the playhead goes to the last marker in the movie or to frame 1 if there are no
markers in the movie.
The go next command is equivalent to the statement go
versions of Lingo.

marker(1)

that was used in earlier

Example

This statement sends the playhead to the next marker in the movie:
go next
See also

go, go loop, go previous

go previous
Syntax

go previous
Description

Command; sends the playhead to the previous marker in the movie. This marker is two markers
back from the current frame if the current frame does not have a marker or one marker back from
the current frame if the current frame has a marker.
Note: This command is equivalent to marker(-1) in previous versions of Director.

If no markers are to the left of the playhead, the playhead branches to one of the following:

The next marker to the right if the current frame does not have a marker
The current frame if the current frame has a marker
Frame 1 if the movie contains no markers
286

Example

This statement sends the playhead to the previous marker in the movie:
go previous
See also

go, go next, go loop

goToFrame
Syntax

sprite(whichFlashSprite).goToFrame(frameNumber)
goToFrame(sprite whichFlashSprite, frameNumber)
sprite(whichFlashSprite).goToFrame(labelNameString)
goToFrame(sprite whichFlashSprite, labelNameString)
Description

Command; plays a Flash movie sprite beginning at the frame identified by the frameNumber
parameter. You can identify the frame by either an integer indicating a frame number or by a
string indicating a label name. Using the goToFrame command has the same effect as setting a
Flash movie sprites frame property.
Example

The following handler branches to different points within a Flash movie in channel 5. It accepts a
parameter that indicates which frame to go to.
on Navigate whereTo
sprite(5).goToFrame(whereTo)
end

gotoNetMovie
Syntax

gotoNetMovie URL
gotoNetMovie (URL)
Description

Command; retrieves and plays a new Shockwave movie from an HTTP or FTP server. The
current movie continues to run until the new movie is available.
Only URLs are supported as valid parameters. The URL can specify either a filename or a marker
within a movie. Relative URLs work if the movie is on an Internet server, but you must include
the extension with the filename.
When performing testing on a local disk or network, media must be located in a directory
named dswmedia.
If a gotoNetMovie operation is in progress and you issue a second gotoNetMovie command
before the first is finished, the second command cancels the first.

287

Examples

In this statement, the URL indicates a Director filename:

gotoNetMovie "http://www.yourserver.com/movies/movie1.dcr"

In this statement, the URL indicates a marker within a filename:

gotoNetMovie "http://www.yourserver.com/movies/buttons.dcr#Contents"

In the following statement, gotoNetMovie is used as a function. The function returns the
network ID for the operation.
myNetID = gotoNetMovie ("http://www.yourserver.com/movies/
buttons.dcr#Contents")

gotoNetPage
Syntax

gotoNetPage "URL", {"targetName"}

Description

Command; opens a Shockwave movie or another MIME file in the browser.

Only URLs are supported as valid parameters. Relative URLs work if the movie is on an
HTTP or FTP server.
The targetName argument is an optional HTML parameter that identifies the frame or window
in which the page is loaded.

If targetName is a window or frame in the browser, gotoNetPage replaces the contents of that
window or frame.

If targetName isnt a frame or window that is currently open, goToNetPage opens a

new window. Using the string "_new" always opens a new window.

If targetName is not included, gotoNetPage replaces the current page, wherever it is located.
In the authoring environment, the gotoNetPage command launches the preferred browser if it is
enabled. In projectors, this command tries to launch the preferred browser set with the Network
Preferences dialog box or browserName command. If neither has been used to set the preferred
browser, the goToNetPage command attempts to find a browser on the computer.
Examples

The following script loads the file Newpage.html into the frame or window named frwin. If a
window or frame in the current window called frwin exists, that window or frame is used. If the
window frwin doesnt exist, a new window named frwin is created.
on keyDown
gotoNetPage "Newpage.html", "frwin"
end

This handler opens a new window regardless of what window the browser currently has open:
on mouseUp
goToNetPage "Todays_News.html", "_new"
end
See also

browserName(), netDone()

288

gradientType
Syntax

member(whichCastMember).gradientType
Description

Vector shape cast member property; specifies the actual gradient used in the cast members fill.
Possible values are #linear or #radial. The gradientType is only valid when the fillMode is
set to #gradient.
This property can be tested and set.
Example

This handler toggles between linear and radial gradients in cast member "backdrop":
on mouseUp me
if member("backdrop").gradientType = #radial then
member("backdrop").gradientType = #linear
else
member("backdrop").gradientType = #radial
end if
end
See also

fillMode

group
Syntax

member(whichCastmember).group(whichGroup)
member(whichCastmember).group[index]
Description

3D element; a node in the 3D world that has a name, transform, parent, and children, but no
other properties.
Every 3D cast member has a default group named World that cannot be deleted. The parent
hierarchy of all models, lights, cameras, and groups that exist in the 3D world terminates in
group("world").
Examples

This statement shows that the fourth group of the cast member newAlien is the group Direct01:
put member("newAlien").group[4]
-- group("Direct01")
See also

newGroup, deleteGroup, child, parent

289

halt
Syntax

halt
Description

Command; exits the current handler and any handler that called it and stops the movie during
authoring or quits the projector during run time from a projector.
Example

This statement checks whether the amount of free memory is less than 50K and, if it is, exits all
handlers that called it and then stops the movie:
if the freeBytes < 50*1024 then halt
See also

abort, exit, pass, quit

handler()
Syntax

scriptObject.handler(#handlerSymbol)
Description

This function returns TRUE if the given scriptObject contains a handler whose name is
#handlerSymbol, and FALSE if it does not. The script object must be a parent script, a child
object, or a behavior.
Example

This Lingo code invokes a handler on an object only if that handler exists:
if spiderObject.handler(#pounce) = TRUE then
spiderObject.pounce()
end if
See also

handlers(), new(), rawNew(), script

handlers()
Syntax

scriptObject.handlers()
Description

This function returns a linear list of the handlers in the given scriptObject. Each handler name
is presented as a symbol in the list. This function is useful for debugging movies.
Note that you cannot get the handlers of a script cast member directly. You have to get them via
the script property of the member.
Examples

This statement displays the list of handlers in the child object RedCar in the Message window:
put RedCar.handlers()
-- [#accelerate, #turn, #stop]

290

This statement displays the list of handlers in the parent script member CarParentScript in the
Message window:
put member(CarParentScript).script.handlers()
-- [#accelerate, #turn, #stop]
See also

handler(), script

height
Syntax

member(whichCastMember).height
the height of member whichCastMember
imageObject.height
sprite(whichSprite).height
the height of sprite whichSprite
Description

Cast member, image object and sprite property; for vector shape, Flash, animated GIF, bitmap, and
shape cast members, determines the height, in pixels, of the cast member displayed on the Stage.

For cast members, works with bitmap and shape cast members only. This property can be
tested but not set.

For image objects, this property can be tested but not set.
For sprites, setting the sprites height automatically sets the sprites stretch property to TRUE.
For the value set by Lingo to last beyond the current sprite, the sprite must be a puppet. This
property can be tested and set.
Examples

This statement assigns the height of cast member Headline to the variable vHeight:
vHeight = member("Headline").height

This statement sets the height of sprite 10 to 26 pixels:

sprite(10).height = 26

This statement assigns the height of sprite (i + 1) to the variable vHeight:

vHeight = sprite(i + 1).height
See also

height, rect (sprite), width

height (3D)
Syntax

member(whichCastmember).modelResource(whichModelResource).height
member(whichCastmember).texture(whichTexture).height
Description

3D #box model resource, #cylinder model resource, and texture property; indicates the height
of the object.
The height of a #box or #cylinder model resource is measured in world units and can be tested
and set. The default value for this property is 50.

291

The height of a texture is measured in pixels and can be tested but not set. The height of the
texture is rounded from the height of the source of the texture to the nearest power of 2.
Examples

This statement sets the height of the model resource named Tower to 225.0 world units:
member("3D World").modelResource("Tower").height = 225.0

This statement shows that the height of the texture named Marsmap is 512 pixels.
put member("scene").texture("Marsmap").height
-- 512
See also

length (3D), width (3D)

heightVertices
Syntax

member(whichCastmember).modelResource(whichModelResource).\
heightVertices
Description

3D #box model resource property; indicates the number of mesh vertices along the height of the
box. Increasing this value increases the number of faces, and therefore the fineness, of the mesh.
The height of a box is measured along its Y axis.
Set the renderStyle property of a models shader to #wire to see the faces of the mesh of the
models resource. Set the renderStyle property to #point to see just the vertices of the mesh.
The value of this property must be greater than or equal to 2. The default value is 4.
Example

The following statement sets the heightVertices property of the model resource named Tower
to 10. Nine polygons will be used to define the geometry of the model resource along its Z axis;
therefore, there will be ten vertices.
member("3D World").modelResource("Tower").heightVertices = 10
See also

height (3D)

highlightPercentage
Syntax

member(whichCastmember).model(whichModel).toon.highlightPercentage
member(whichCastmember).model(whichModel).shader.highlight\
Percentage
member(whichCastmember).shader(whichShader).highlightPercentage
Description

3D toon modifier and #painter shader property; indicates the percentage of available colors that
are used in the area of the models surface where light creates highlights.
The range of this property is 0 to 100, and the default value is 50.
The number of colors used by the toon modifier and #painter shader for a model is determined
by the colorSteps property of the models toon modifier or #painter shader.

292

Example

The following statement sets the highlightPercentage property of the toon modifier for the
model named Sphere to 50. Half of the colors available to the toon modifier for this model will
be used for the highlight area of the models surface.
member("shapes").model("Sphere").toon.highlightPercentage = 50
See also

highlightStrength, brightness

highlightStrength
Syntax

member(whichCastmember).model(whichModel).toon.highlightStrength
member(whichCastmember).model(whichModel).shader.highlightStrength
member(whichCastmember).shader(whichShader).highlightStrength
Description

3D toon modifier and #painter shader property; indicates the brightness of the area of the
models surface where light creates highlights.
The default value of this property is 1.0.
Example

The following statement sets the highlightStrength property of the toon modifier for the
model named Teapot to 0.5. The models highlights will be moderately bright.
member("shapes").model("Teapot").toon.highlightStrength = 0.5
See also

highlightPercentage, brightness

hilite (command)
Syntax

fieldChunkExpression.hilite()
hilite fieldChunkExpression
Description

Command; highlights (selects) in the field sprite the specified chunk, which can be any chunk
that Lingo lets you define, such as a character, word, or line. On the Macintosh, the highlight
color is set in the Color control panel.
Examples

This statement highlights the fourth word in the field cast member Comments, which contains
the string Thought for the Day:
member("Comments").word[4].hilite()

This statement causes highlighted text within the sprite for field myRecipes to be displayed
without highlighting:
myLineCount = member("myRecipes").line.count
member("myRecipes").line[myLineCount + 1].hilite()
See also

char...of, item...of, line...of, word...of, delete, mouseChar, mouseLine, mouseWord,

field, selection() (function), selEnd, selStart

293

hilite (cast member property)

Syntax

member(whichCastMember).hilite
the hilite of member whichCastMember
Description

Cast member property; determines whether a check box or radio button created with the button
tool is selected (TRUE) or not (FALSE, default).
If whichCastMember is a string, it specifies the cast member
whichCastMember specifies the cast member number.

name. If it is an integer,

This property can be tested and set.

Examples

This statement checks whether the button named Sound on is selected and, if it is, turns sound
channel 1 all the way up:
if member("Sound on").hilite = TRUE then sound(1).volume = 255

This statement uses Lingo to select the button cast member powerSwitch by setting the hilite
member property for the cast member to TRUE:
member("powerSwitch").hilite = TRUE
See also

checkBoxAccess, checkBoxType

hitTest()
Syntax

sprite(whichFlashSprite).hitTest(point)
hitTest(sprite whichFlashSprite, point)
Description

Function; indicates which part of a Flash movie is directly over a specific Director Stage location.
The Director Stage location is expressed as a Director point value: for example, point(100,50).
The hitTest function returns these values:

294

#backgroundThe specified Stage location falls within the background of the Flash movie sprite.
#normalThe

specified Stage location falls within a filled object.

#buttonThe

specified Stage location falls within the active area of a button.

#editTextThe

specified Stage location falls within a Flash editable text field.

Example

This frame script checks to see if the mouse is currently located over a button in a Flash movie
sprite in channel 5 and, if it is, the script sets a text field used to display a status message:
on exitFrame
if sprite(5).hitTest(the mouseLoc) = #button then
member("Message Line").text = "Click here to play the movie."
updateStage
else
member("Message Line").text = ""
end if
go the frame
end

hither
Syntax

member(whichCastmember).camera(whichCamera).hither
sprite(whichSprite).camera{(index)}.hither
Description

3D camera property; indicates the distance in world units from the camera beyond which models
are drawn. Objects closer to the camera than hither are not drawn.
The value of this property must be greater than or equal to 1.0 and has a default value of 5.0.
Example

The following statement sets the hither property of camera 1 to 1000. Models closer than 1000
world units from the camera will not be visible.
member("SolarSystem").camera[1].hither = 1000
See also

yon

HMStoFrames()
Syntax

HMStoFrames(hms, tempo, dropFrame, fractionalSeconds)

Description

Function; converts movies measured in hours, minutes, and seconds to the equivalent number of
frames or converts a number of hours, minutes, and seconds into time if you set the tempo
argument to 1 (1 frame = 1 second).

295

hmsString

expression that specifies the time in the form sHH:MM:SS.FFD, where:

A character is used if the time is less than zero, or a space if the time is greater than or equal to zero.

HH

Hours.

MM

Minutes.

SS

Seconds.

FF

Indicates a fraction of a second if fractionalSeconds is TRUE or frames if

fractionalSeconds is FALSE.

A d is used if dropFrame is TRUE, or a space if dropFrame is FALSE.

tempoSpecifies

fractionalSecondsLogical expression that determines the meaning of the numbers after

the seconds; they can be either fractional seconds rounded to the nearest hundredth of a second
(TRUE) or the number of residual frames (FALSE).

the tempo in frames per second.

dropFrameLogical expression that determines whether the frame is a drop frame (TRUE) or
not (FALSE). If the string hms ends in a d, the time is treated as a drop frame, regardless of the
value of dropFrame.

Examples

This statement determines the number of frames in a 1-minute, 30.1-second movie when the tempo
is 30 frames per second. Neither the dropFrame nor fractionalSeconds arguments is used.
put HMStoFrames(" 00:01:30.10 ", 30, FALSE, FALSE)
-- 2710

This statement converts 600 seconds into minutes:

>> put framesToHMS(600, 1,0,0)
>> -- " 00:10:00.00 "

This statement converts an hour and a half into seconds:

>> put HMStoFrames("1:30:00", 1,0,0)
>> -- 5400
See also

framesToHMS()

hold
Syntax

sprite(whichFlashSprite).hitTest(point)
hold sprite whichFlashSprite
Description

Flash command; stops a Flash movie sprite that is playing in the current frame, but any audio
continues to play.

296

Example

This frame script holds the Flash movie sprites playing in channels 5 through 10 while allowing
the audio for these channels to continue playing:
on enterFrame
repeat with i = 5 to 10
sprite(i).hold()
end repeat
end
See also

movieRate, pause (movie playback)

hotSpot
Syntax

member(whichCursorCastMember).hotspot
the hotspot of member whichCursorCastMember
Description

Cursor cast member property; specifies the horizontal and vertical point location of the pixel that
represents the hotspot within the animated color cursor cast member whichCursorCastMember.
Director uses this point to track the cursors position on the screen (for example, when it returns
the values for the Lingo functions mouseH and mouseV) and to determine where a rollover
(signaled by the Lingo message mouseEnter) occurs.
The upper left corner of a cursor is point(0,0), which is the default hotSpot value. Trying to set a
point outside the bounds of the cursor produces an error. For example, setting the hotspot of a
16-by-16-pixel cursor to point(16,16) produces an error (because the starting point is 0,0, not 1,1).
This property can be tested and set.
Example

This handler sets the hotspot of a 32-by-32-pixel cursor (whose cast member number is stored in
the variable cursorNum) to the middle of the cursor:
on startMovie
member(cursorNum).hotSpot = point(16,16)
end

hotSpotEnterCallback
Syntax

sprite(whichQTVRSprite).hotSpotEnterCallback
the hotSpotEnterCallback of sprite whichQTVRSprite
Description

QuickTime VR sprite property; contains the name of the handler that runs when the cursor
enters a QuickTime VR hot spot that is visible on the Stage. The QuickTime VR sprite receives
the message first. The message has two arguments: the me parameter and the ID of the hot spot
that the cursor entered.
To clear the callback, set this property to 0.
To avoid a performance penalty, set a callback property only when necessary.
This property can be tested and set.
See also

hotSpotExitCallback, nodeEnterCallback, nodeExitCallback, triggerCallback

297

hotSpotExitCallback
Syntax

sprite(whichQTVRSprite).hotSpotExitCallback
the hotSpotExitCallback of sprite whichQTVRSprite
Description

QuickTime VR sprite property; contains the name of the handler that runs when the cursor
leaves a QuickTime VR hot spot that is visible on the Stage. The QuickTime VR sprite receives
the message first. The message has two arguments: the me parameter and the ID of the hot spot
that the cursor entered.
To clear the callback, set this property to 0.
To avoid a performance penalty, set a callback property only when necessary.
This property can be tested and set.
See also

hotSpotEnterCallback, nodeEnterCallback, nodeExitCallback, triggerCallback

HTML
Syntax

member(whichMember).HTML
Description

Cast member property; accesses text and tags that control the layout of the text within an
HTML-formatted text cast member.
This property can be tested and set.
Example

This statement displays in the message window the HTML formatting information embedded in
the text cast member Home Page:
put member("Home Page").HTML
See also

importFileInto, RTF

hyperlink
Syntax

chunkExpression.hyperlink
Description

Text cast member property; returns the hyperlink string for the specified chunk expression in the
text cast member.
This property can be both tested and set.
When retrieving this property, the link containing the first character of chunkExpression is used.
Hyperlinks may not overlap. Setting a hyperlink over an existing link, even partially over it),
replaces the initial link with the new one.
Setting a hyperlink to an empty string removes it.

298

Example

The following handler creates a hyperlink in the first word of text cast member MacroLink. The
text is linked to Macromedias website.
on startMovie
member("MacroLink").word[1].hyperlink = \
"http://www.macromedia.com"
end
See also

hyperlinkRange, hyperlinkState

on hyperlinkClicked
Syntax

on hyperlinkClicked me, data, range

statement(s)
end
Description

System message and event handler; used to determine when a hyperlink is actually clicked.
This event handler has the following parameters:

meUsed

in a behavior to identify the sprite instance

dataThe hyperlink

data itself; the string entered in the Text Inspector when editing the text

cast member

rangeThe character range of the hyperlink in the text (Its possible to get the text of the
range itself by using the syntax member Ref.char[range[1]..range[2]]

This handler should be attached to a sprite as a behavior script. Avoid placing this handler in a
cast member script.
Example

This behavior shows a link examining the hyperlink that was clicked, jump to a URL if needed,
then output the text of the link itself to the message window:
property spriteNum
on hyperlinkClicked me, data, range
if data starts "http://" then
goToNetPage(data)
end if
currentMember = sprite(spriteNum).member
anchorString = currentMember.char[range[1]..range[2]]
put "The hyperlink on"&&anchorString&&"was just clicked."
end

hyperlinkRange
Syntax

chunkExpression.hyperlinkRange
Description

Text cast member property; returns the range of the hyperlink that contains the first character of
the chunk expression.

299

This property can be tested but not set.

Like hyperLink and hyperLinkState, the returned range of the link contains the first character
of chunkExpression.
See also

hyperlink, hyperlinkState

hyperlinks
Syntax

chunkExpression.hyperlinks
Description

Text cast member property; returns a linear list containing all the hyperlink ranges for the
specified chunk of a text cast member. Each range is given as a linear list with two elements, one
for the starting character of the link and one for the ending character.
Example

This statement returns all the links for the text cast member Glossary to the message window:
put member("Glossary").hyperlinks
-- [[3, 8], [10, 16], [41, 54]]

hyperlinkState
Syntax

textChunk.hyperlinkState
Description

Text cast member property; contains the current state of the hyperlink. Possible values for the
state are: #normal, #active, and #visited.
This property can be tested and set.
Like hyperLink and hyperLinkRange, the returned range of the link contains the first character
of chunkExpression.
Example

The following handler checks to see if the hyperlink clicked is a web address. If it is, the state of
the hyperlink text state is set to #visited, and the movie branches to the web address.
property spriteNum
on hyperlinkClicked me, data, range
if data starts "http://" then
currentMember = sprite(spriteNum).member
currentMember.word[4].hyperlinkState = #visited
goToNetPage(data)
end if
end
See also

hyperlink, hyperlinkRange

300

identity()
Syntax

member(whichCastmember).model(whichModel).transform.identity()
member(whichCastmember).group(whichGroup).transform.identity()
member(whichCastmember).camera(whichCamera).transform.identity()
sprite(whichSprite).camera{(index)}.transform.identity()
member(whichCastmember).light(whichLight).transform.identity()
transformReference.identity()
Description

3D command; sets the transform to the identity transform, which is

transform(1.0000,0.0000,0.0000,0.0000, 0.0000,1.0000,0.0000,0.0000,
0.0000,0.0000,1.0000,0.0000, 0.0000,0.0000,0.0000,1.0000).

The position property of the identity transform is vector(0,

0, 0).

The rotation property of the identity transform is vector(0,

0, 0).

The scale property of the identity transform is vector(1,

1, 1).

The identity transform is parent-relative.

Example

This statement sets the transform of the model named Box to the identity transform:
member("3d world").model("Box").transform.identity()
See also

transform (property), getWorldTransform()

on idle
Syntax

on idle
statement(s)
end
Description

System message and event handler; contains statements that run whenever the movie has no other
events to handle and is a useful location for Lingo statements that you want to execute as
frequently as possible, such as statements that update values in global variables and displays
current movie conditions.
Because statements in on idle handlers run frequently, it is good practice to avoid placing Lingo
that takes a long time to process in an on idle handler.
It is often preferable to put on idle handlers in frame scripts instead of movie scripts to take
advantage of the on idle handler only when appropriate.
Director can load cast members from an internal or external cast during an idle event. However,
it cannot load linked cast members during an idle event.
The idle message is only sent to frame scripts and movie scripts.

301

Example

This handler updates the time being displayed in the movie whenever there are no other events to
handle:
on idle
member("Time").text = the short time
end idle
See also

idleHandlerPeriod

idleHandlerPeriod
Syntax

the idleHandlerPeriod
Description

Movie property; determines the maximum number of ticks that passes until the movie sends an
idle message. The default value is 1, which tells the movie to send idle handler messages no
more than 60 times per second.
When the playhead enters a frame, Director starts a timer, repaints the appropriate sprites on the
Stage, and issues an enterFrame event. Then, if the amount of time set for the tempo has elapsed,
Director generates an exitFrame event and goes to the next specified frame; if the amount of
time set for this frame hasnt elapsed, Director waits until the time runs out and periodically
generates an idle message. The amount of time between idle events is determined by
idleHandlerPeriod.
Possible settings for idleHandlerPeriod are:

0As many idle events as possible

1Up to 60 per second
2Up to 30 per second
3Up to 20 per second
nUp to 60/n per second

The number of idle events per frame also depends on the frame rate of the movie and other
activity, including whether Lingo scripts are executing. If the tempo is 60 frames per second (fps)
and the idleHandlerPeriod value is 1, one idle event per frame occurs. If the tempo is 20 fps,
three idle events per frame occur. Idle time results from Director doesnt have a current task to
perform and cannot generate any events.
In contrast, if the idleHandlerPeriod property is set to 0 and the tempo is very low, thousands
of idle events can be generated.
The default value for this property is 1, which differs from previous versions in which it defaulted to 0.
Example

The following statement causes the movie to send an idle message a maximum of once per second:
the idleHandlerPeriod = 60
See also

idleLoadDone(), idleLoadMode, idleLoadTag, idleReadChunkSize

302

idleLoadDone()
Syntax

idleLoadDone(loadTag)
Description

Function; reports whether all cast members with the given tag have been loaded (TRUE) or are still
waiting to be loaded (FALSE).
Example

This statement checks whether all cast members whose load tag is 20 have been loaded and then
plays the movie Kiosk if they are:
if idleLoadDone(20) then play movie("on idle")
See also

idleHandlerPeriod, idleLoadMode, idleLoadPeriod, idleLoadTag, idleReadChunkSize

idleLoadMode
Syntax

the idleLoadMode
Description

System property; determines when the preLoad and preLoadMember commands try to load cast
members during idle periods according to the following values:

0Does not perform idle loading

1Performs idle loading when there is free time between frames
2Performs idle loading during idle events
3Performs idle loading as frequently as possible

The idleLoadMode system property performs no function and works only in conjunction with
the preLoad and preLoadMember commands.
Cast members that were loaded using idle loading remain compressed until the movie uses them.
When the movie plays back, it may have noticeable pauses while it decompresses the
cast members.
Example

This statement causes the movie to try as frequently as possible to load cast members designated
for preloading by the preLoad and preLoadMember commands:
the idleLoadMode = 3
See also

idleHandlerPeriod, idleLoadDone(), idleLoadPeriod, idleLoadTag, idleReadChunkSize

303

idleLoadPeriod
Syntax

the idleLoadPeriod
Description

System property; determines the number of ticks that Director waits before trying to load cast
members waiting to be loaded. The default value for idleLoadPeriod is 0, which instructs
Director to service the load queue as frequently as possible.
Example

This statement instructs Director to try loading every 1/2 second (30 ticks) any cast members
waiting to be loaded:
set the idleLoadPeriod = 30
See also

idleLoadDone(), idleLoadMode, idleLoadTag, idleReadChunkSize

idleLoadTag
Syntax

the idleLoadTag
Description

System property; identifies or tags with a number the cast members that have been queued for
loading when the computer is idle. The idleLoadTag is a convenience that identifies the cast
members in a group that you want to preload.
The property can be tested and set using any number that you choose.
Example

This statement makes the number 10 the idle load tag:

the idleLoadTag = 10
See also

idleHandlerPeriod, idleLoadDone(), idleLoadMode, idleLoadPeriod, idleReadChunkSize

idleReadChunkSize
Syntax

the idleReadChunkSize
Description

System property; determines the maximum number of bytes that Director can load when it
attempts to load cast members from the load queue. The default value is 32K.
This property can be tested and set.
Example

This statement specifies that 500K is the maximum number of bytes that Director can load in
one attempt at loading cast members in the load queue:
the idleReadChunkSize = 500 * 1024
See also

idleHandlerPeriod, idleLoadDone(), idleLoadMode, idleLoadPeriod, idleLoadTag

304

if
Syntax

if logicalExpression then statement

if logicalExpression then statement
else statement
end if
if logicalExpression then
statement(s)
end if
if logicalExpression then
statement(s)
else
statement(s)
end if
if logicalExpression1 then
statement(s)
else if logicalExpression2 then
statement(s)
else if logicalExpression3 then
statement(s)
end if
if logicalExpression1 then
statement(s)
else logicalExpression2
end if
Description

Keyword; if...then structure that evaluates the logical expression specified by

logicalExpression.

If the condition is TRUE, Lingo executes the statement(s) that follow then.
If the condition is FALSE, Lingo executes the statement(s) following else. If no statements
follow else, Lingo exits the if...then structure.

All parts of the condition must be evaluated; execution does not stop at the first condition that
is met or not met. Thus, faster code may be created by nesting if...then statements on
separate lines instead of placing them all on the first line to be evaluated.
When the condition is a property, Lingo automatically checks whether the property is TRUE. You
dont need to explicitly add the phrase = TRUE after the property.
The else portion of the statement is optional. To use more
else-statement, you must end with the form end if.

than one then-statement or

The else portion always corresponds to the previous if statement; thus, sometimes you must
include an else nothing statement to associate an else keyword with the proper if keyword.
Note: A quick way to determine in the script window if a script is paired properly is to press Tab. This forces Director to
check the open Script window and show the indentation for the contents. Any mismatches will be immediately apparent.

Examples

This statement checks whether the carriage return was pressed and then continues if it was:
if the key = RETURN then go the frame + 1

305

This handler checks whether the Command and Q keys were pressed simultaneously and, if so,
executes the subsequent statements:
on keyDown
if (the commandDown) and (the key = "q") then
cleanUp
quit
end if
end keyDown

Compare the following two constructions and the performance results. The first construction
evaluates both conditions, and so must determine the time measurement, which may take a while.
The second construction evaluates the first condition; the second condition is checked only if the
first condition is TRUE.
spriteUnderCursor = rollOver()
if (spriteUnderCursor > 25) AND MeasureTimeSinceIStarted() then
alert "You found the hidden treasure!"
end if

The alternate, and faster, construction would be as follows:

spriteUnderCursor = rollOver()
if (spriteUnderCursor > 25) then
if MeasureTimeSinceIStarted() then
alert "You found the hidden treasure!"
end if
end if
See also

case

ignoreWhiteSpace()
Syntax

XMLparserObject.ignoreWhiteSpace(trueOrFalse)
Description

XML Command; specifies whether the parser should ignore or retain white space when generating
a Lingo list. When ignoreWhiteSpace() is set to TRUE (the default), the parser ignores white
space.When set to FALSE, the parser will retain white space and treat it as actual data.
If an element has separate beginning and ending tags, such as <sample> </sample>, character
data within the element will be ignored if, and only if, it is composed of white space only. If there
is any non-white space, or if ignoreWhiteSpace() is set to FALSE, there will be a CDATA node
with the exact text, including any white space.
Examples

These Lingo statements leave ignoreWhiteSpace() set to the default of TRUE and parse the given
XML into a list. Note that the element <sample> has no children in the list.
XMLtext = "<sample> </sample>"
parserObj.parseString(XMLtext)
theList = parserObj.makelist()
put theList
-- ["ROOT OF XML DOCUMENT": ["!ATTRIBUTES": [:], "sample": ["!ATTRIBUTES":
[:]]]]

306

These Lingo statements set ignoreWhiteSpace() to FALSE and then parse the given XML into a
list. Note that the element <sample> now has a child containing one space character.
XMLtext = "<sample> </sample>"
parserObj.ignorewhitespace(FALSE)
parserObj.parseString(XMLtext)
theList = parserObj.makelist()
put theList
-- ["ROOT OF XML DOCUMENT": ["!ATTRIBUTES": [:], "sample": ["!ATTRIBUTES":
[:], "!CHARDATA": " "]]]

These Lingo statements leave ignoreWhiteSpace() set to the default of TRUE and parse the given
XML. Note that there is only one child node of the <sample> tag and only one child node of the
<sub> tag.
XMLtext = "<sample> _{phrase 1}</sample>"
parserObj.parseString(XMLtext)
theList = parserObj.makeList()
put theList
-- ["ROOT OF XML DOCUMENT": ["!ATTRIBUTES": [:], "sample": ["!ATTRIBUTES":
[:], "sub": ["!ATTRIBUTES": [:], "!CHARDATA": " phrase 1 "]]]]

These Lingo statements set ignoreWhiteSpace() to FALSE and parse the given XML. Note that
there are now two child nodes of the <sample> tag, the first one being a single space character.
XMLtext = "<sample> _{phrase 1}</sample>"
gparser.ignoreWhiteSpace(FALSE)
gparser.parseString(XMLtext)
theList = gparser.makeList()
put theList
-- ["ROOT OF XML DOCUMENT": ["!ATTRIBUTES": [:], "sample": ["!ATTRIBUTES":
[:], "!CHARDATA": " ", "sub": ["!ATTRIBUTES": [:], "!CHARDATA": " phrase 1
"]]]]

ilk()
Syntax

ilk(object)
ilk(object, type)
Description

Function; indicates the type of an object.

The syntax ilk(object) returns a value indicating the type of an object. If the object is a list,
ilk(object)

returns #list; if the object is a property list, ilk(object) returns #propList.

The syntax ilk(object,

type) compares the object represented by object to the specified

type. If the object is of the specified type, the ilk() function returns TRUE. If the object is not
of the specified type, the ilk() function returns FALSE.

The following table shows the return value for each type of object recognized by ilk():
Type of Object ilk(Object)
returns

ilk(Object, Type)
returns 1 only if Type =

Example

linear list

#list

#list or #linearlist ilk ([1,2,3])

property list

#proplist

#list or #proplist

ilk ([#his: 1234, #hers: 7890])

integer

#integer

#integer or #number

ilk (333)

float

#float

#float or #number

ilk (123.456)

307

Type of Object ilk(Object)

returns

ilk(Object, Type)
returns 1 only if Type =

Example

string

#string

#string

ilk ("asdf")

rect

#rect

#rect or #list

ilk (sprite(1).rect)

point

#point

#point or #list

ilk (sprite(1).loc)

color

#color

#color

ilk (sprite(1).color)

date

#date

#date

ilk (the systemdate)

symbol

#symbol

#symbol

ilk (#hello)

void

#void

#void

ilk (void)

picture

#picture

#picture

ilk (member (2).picture)

parent script
instance

#instance

#object

ilk (new (script "blahblah"))

xtra instance

#instance

#object

ilk (new (xtra "fileio"))

member

#member

#object or #member

ilk (member 1)

xtra

#xtra

#object or #xtra

ilk (xtra "fileio")

script

#script

#object or #script

ilk (script "blahblah")

castlib

#castlib

#object or #castlib

ilk (castlib 1)

sprite

#sprite

#object or #sprite

ilk (sprite 1)

sound

#instance or
#sound (when
Sound Control
Xtra is not
present)

#instance or #sound

ilk (sound "yaddayadda")

window

#window

#object or #window

ilk (the stage)

media

#media

#object or #media

ilk (member (2).media)

timeout

#timeout

#object or #timeout

ilk (timeOut("intervalTimer"))

image

#image

#object or #image

ilk ((the stage).image)

Examples

The following ilk statement identifies the type of the object named Bids:
Bids = [:]
put ilk( Bids )
-- #proplist

The following ilk statement tests whether the variable Total is a list and displays the result in the
Message window:
Total = 2+2
put ilk( Total, #list )
-- 0

In this case, since the variable Total is not a list, the Message window displays 0, which is the
numeric equivalent of FALSE.

308

The following example tests a variable named myVariable and verifies that it is a date object
before displaying it in the Message window:
myVariable = the systemDate
if ilk(myVariable, #date) then put myVariable
-- date( 1999, 2, 19 )

ilk (3D)
Syntax

ilk(object)
ilk(object,type)
object.ilk
object.ilk(type)
Description

Lingo function; indicates the type of an object.

The syntax ilk(object) and object.ilk return a value indicating the type of object. If the
object is a model, ilk(object) returns #model; if the object is a motion, ilk(object)
returns #motion. See the following table for a complete list of values returned by 3D objects.

The syntax ilk(object,

type) and object.ilk(type) compare the object represented by

the object to the specified type. If the object is of the specified type, the ilk() function returns
TRUE. It the object is not of the specified type, the ilk() function returns FALSE.

The following table shows the return value for each type of 3D object recognized by ilk(). See
the main Lingo Dictionary for a list of return values of non-3D objects which are not discussed in
this dictionary.
Type of object

ilk(object) returns

ilk(object, Type) if only Type =

render services

#renderer

#renderer

model resource

#modelresource, #plane, #box, #sphere,

#cylinder, #particle, #mesh

Same as ilk(object), except for

#modelresource which is the ilk of resources
generated by an imported W3D file

model

#model

#model

motion

#motion

#motion or #list

shader

#shader

#shader or #list

texture

#texture

#texture or #list

group

#group

#group

camera

#camera

#camera

collision data

#collisiondata

#collisiondata

vector

#vector

#vector

transform

#transform

#transform

309

Examples

This statement shows that MyObject is a motion object:

put MyObject.ilk
-- #motion

The following statement tests whether MyObject is a motion object. The return value of 1 shows
that it is.
put MyObject.ilk(#motion)
-- 1
See also

tweenMode

image
Syntax

whichMember.image
(the stage).image
window(windowName).image
Description

This property refers to the image object of a bitmap or text cast member, of the Stage, or of a window.
You can get or set a cast members image, but you can only get the image of the Stage or a window.
Setting a cast members image property immediately changes the contents of the member.
However, when you get the image of a member or window, Director creates a reference to the
image of the specified member or window. If you make changes to the image, the contents of the
cast member or window change immediately.
If you plan to make a lot of changes to an items image property, it is faster to copy the items
image property into a new image object using the duplicate() function, apply your changes to
the new image object, and then set the original items image to the new image object. For nonbitmap members, it is always faster to use the duplicate() function.
Examples

This statement puts the image of cast member originalFlower into cast member newFlower:
member("newFlower").image = member("originalFlower").image

These statements place a reference to the image of the stage into the variable myImage and then
put that image into cast member flower:
myImage=(the stage).image
member("flower").image = myImage
See also

setPixel(), draw(), image(), fill(), duplicate() (image function),

copyPixels()

310

image()
Syntax

image(width, height, bitDepth {, alphaDepth} {, paletteSymbolOrMember})

Description

Function; creates and returns a new image object of the dimensions specified by width, height,
and bitDepth, with optional alphaDepth and paletteObject values.
The bitDepth can be 1, 2, 4, 8, 16, or 32. The alphaDepth, if given, is used only for 32-bit
images and must be 0 or 8. The paletteObject, if given, is used only for 2-, 4-, and 8-bit images
and can be either a palette symbol, such as #grayscale, or a palette cast member. If no palette is
specified, the movies default palette is used.
Image objects created with image() are independent and do not refer to any cast member or window.
To see an example of image() used in a completed movie, see the Imaging movie in the Learning/
Lingo Examples folder inside the Director application folder.
Example

These statements create a 200 x 200 pixel, 8-bit image object and fill the image object with red:
redSquare = image(200, 200, 8)
redSquare.fill(0, 0, 200, 200, rgb(255, 0, 0))
See also

palette, image, duplicate() (image function), fill()

image (RealMedia)
Syntax

sprite(whichSprite).image
member(whichCastmember).image
Description

RealMedia sprite or cast member property; returns a Lingo image object containing the current
frame of the RealMedia video stream. You can use this property to map RealVideo onto a 3D
model (see the example below).
Example

This statement copies the current frame of the RealMedia cast member Real to the bitmap cast
member Still:
member("Still").image = member("Real").image

311

This handler is called by a frame script once per Director frame. The handler creates a new texture
from the image of the RealMedia cast member named Real if it is playing or paused. The new
texture is then used by the shader of the model named mSphere. The texture that was used in the
previous frame is deleted. Finally, the sphere is rotated by 1 around the y-axis. The result is a
#realMedia video playing on a rotating sphere.
on updateShader
if member("Real").state = 4 then
sphereShader = member("3d").model("mSphere").shader
tex = member("3d").newTexture("texture" & gTextureNumber, \
#fromImageObject, member("Real").image)
sphereShader.texture = tex
if gTextureNumber > 1 then
member("3d").deleteTexture("texture" & (gTextureNumber - 1))
end if
gTextureNumber = gTextureNumber + 1
end if
member("3d").model[1].transform.rotate(0, 1, 0)
end

imageCompression
Syntax

member(whichMember).imageCompression
the imageCompression of member whichMember
Description

This bitmap cast member property indicates the type of compression that Director will apply to
the member when saving the movie in Shockwave format. This property can be tested and set,
and has no effect at runtime. Its value can be any one of these symbols:
Value

Meaning

#movieSetting

Use the compression settings of the movie, as stored in the movieImageCompression

property. This is the default value for image formats not restricted to standard
compression (see below).

#standard

Use the Director standard internal compression format.

#jpeg

Use JPEG compression. See imageQuality.

You normally set this property in the Property inspectors Bitmap tab. However, if you want to set
this property for a large number of images at once, you can set the property with a Lingo routine.
If a member doesnt support JPEG compression because it is 8-bit or lower, or if the image is
linked from an external file, only #standard compression can be used. Image formats that do not
support JPEG compression include GIF and 8-bit or lower images.
Example

This statement displays the imageCompression of member Sunrise in the message window:
put member("Sunrise").imageCompression
-- #movieSetting
See also

imageQuality, movieImageCompression, movieImageQuality

312

imageEnabled
Syntax

sprite(whichVectorOrFlashSprite).imageEnabled
the imageEnabled of sprite whichVectorOrFlashSprite
member(whichVectorOrFlashMember).imageEnabled
the imageEnabled of member whichVectorOrFlashMember
Description

Cast member property and sprite property; controls whether a Flash movie or vector shapes
graphics are visible (TRUE, default) or invisible (FALSE).
This property can be tested and set.
Example

This beginSprite script sets up a linked Flash movie sprite to hide its graphics when it first
appears on the Stage and begins to stream into memory and saves its sprite number in a global
variable called gStreamingSprite for use in a frame script later in the Score:
global gStreamingSprite
on beginSprite me
gStreamingSprite = me.spriteNum
sprite(gStreamingSprite).imageEnabled = FALSE
end

In a later frame of the movie, this frame script checks to see if the Flash movie sprite specified by
the global variable gStreamingSprite has finished streaming into memory. If it has not, the
script keeps the playhead looping in the current frame until 100% of the movie has streamed into
memory. It then sets the imageEnabled property to TRUE so that the graphics appear and lets the
playhead continue to the next frame in the Score.
global gStreamingSprite
on exitFrame me
if sprite(gStreamingSprite).member.percentStreamed < 100 then
go to frame
else
sprite(gStreamingSprite).imageEnabled = TRUE
updatestage
end if
end

imageQuality
Syntax

member(whichMember).imageQuality
the imageQuality of member whichMember
Description

This bitmap cast member property indicates the level of compression to use when the members
imageCompression property is set to #jpeg. The range of acceptable values is 0100. Zero yields
the lowest image quality and highest compression; 100 yields the highest image quality and lowest
compression.

313

This property is settable only during authoring and only affects cast members when saving a
movie in Shockwave format. The compressed image can be previewed via the Optimize in
Fireworks button in the Property inspectors Bitmap tab or the Preview in Browser command in
the File menu.
If an image cast members imageCompression property is set to #MovieSetting, the movie
property movieImageQuality is used instead of imageQuality.
See also

imageCompression, movieImageCompression, movieImageQuality

immovable
Syntax

member(whichCastmember).model(whichModel).collision.immovable
Description

3D #collision modifier property; indicates whether a model can be moved as a result of

collisions during animations. Specifying TRUE makes the model immovable; specifying FALSE
allows the model to be moved. This property is useful as a way of improving performance during
animation, because models that do not move do not need to be checked for collisions by Lingo.
This property has a default value of FALSE.
Example

This statement sets the immovable property of the collision modifier attached to the first
model of the cast member named Scene to TRUE:
member("Scene").model[1].collision.immovable = TRUE
See also

collision (modifier)

importFileInto
Syntax

importFileInto member whichCastMember, fileName

importFileInto member whichCastMember of castLib whichCast, fileName
importFileInto member whichCastMember, URL
Description

Command; replaces the content of the cast member specified by whichCastMember with the file
specified by fileName.
The importFileInto command is useful in four situations:

When finishing developing a movie, use it to embed media that you have kept linked and
external so it can be edited during the project.

When generating Score from Lingo during movie creation, use it to assign content to new cast
members that you created.

314

 When downloading files from the Internet, use it to download the file at a specific URL and
set the filename of linked media. (However, to import a file from a URL, its usually more
efficient and minimizes downloading to use the preloadNetThing command to download the
file to a local disk first and then import the file from the local disk.)

Use it to import both RTF and HTML documents into text cast members with formatting and
links intact.
Use of the importFileInto command in projectors can quickly consume available memory, so
its best to reuse the same members for imported data if possible.
Also, the importFileInto command doesnt work with the Director player for Java. To change
the content of a bitmap or sound cast member in a movie playing back as an applet, make the cast
members linked cast members and change the cast members fileName property.
Note: In Shockwave, you must issue a preloadNetThing and wait for a successful completion of the download
before using importFileInto with the file. In Director and projectors, importFileInto automatically downloads the
file for you.

Example

This handler assigns a URL that contains a GIF file to the variable tempURL and then uses the
importFileInto command to import the file at the URL into a new bitmap cast member:
on exitFrame
tempURL = "http://www.dukeOfUrl.com/crown.gif"
importFileInto new(#bitmap), tempUrl
end

This statement replaces the content of the sound cast member Memory with the sound file Wind:
importFileInto member "Memory", "Wind.wav"

These statements download an external file from a URL to the Director application folder and
then import that file into the sound cast member Norma Desmond Speaks:
downLoadNetThing http://www.cbDeMille.com/Talkies.AIF, the \
applicationPath&"Talkies.AIF" \
importFileInto(member "Norma Desmond Speaks", the
applicationPath&"Talkies.AIF")
See also

downloadNetThing, fileName (cast member property), preloadNetThing()

in
See also

number (characters), number (items), number (lines), number (words)

INF
Description

Lingo return value; indicates that a specified Lingo expression evaluates as an infinite number.
See also

NAN

315

inflate
Syntax

rectangle.Inflate(widthChange, heightChange)
inflate (rectangle, widthChange, heightChange)
Description

Command; changes the dimensions of the rectangle specified by rectangle relative to the center
of the rectangle, either horizontally (widthChange) or vertically (heightChange).
The total change in each direction is twice the number you specify. For example, replacing
with 15 increases the rectangles width by 30 pixels. A value less than 0 for the
horizontal or vertical dimension reduces the rectangles size.
widthChange

Examples

This statement increases the rectangles width by 4 pixels and the height by 2 pixels:
rect(10, 10, 20, 20).inflate(2, 1)
-- rect (8, 9, 22, 21)

This statement decreases the rectangles height and width by 20 pixels:

inflate (rect(0, 0, 100, 100), -10, -10)
-- rect (10, 10, 90, 90)

ink
Syntax

sprite(whichSprite).ink
the ink of sprite whichSprite
Description

Sprite property; determines the ink effect applied to the sprite specified by whichSprite, as
follows:

316

0Copy

32Blend

1Transparent

33Add pin

2Reverse

34Add

3Ghost

35Subtract pin

4Not copy

36Background transparent

5Not transparent

37Lightest

6Not reverse

38Subtract

7Not ghost

39Darkest

8Matte

40Lighten

9Mask

41Darken

For a movie that p