Understanding Director Basics

January 12, 1999
by Alex Zavatone

With the release of each new version of Director, our favorite app gets more and more complicated. Where do you start when you understand the basics of the cast, score and stage but want to do a bit more than treating lingo like a wading pool?

So wadda ya got there sport?

It's so much easier to get a grip on Director if you go back to Director 4. There's so much less there to learn. Unfortunately, there are not many of us who have Dir 4 lying around. Though Director's become a great development tool in it's latest releases, the added complexity doesn't make it any easier to learn.

To get started in Lingo, there are a few concepts that help me alot. Those concepts are as follows:
Where does the lingo happen?
What starts the lingo execution?
What are Variables, Events and Handlers?
How do I structure or organize my code?

The best places to start understanding are variables and events. Luckily, I've already cooked up an article on variables. Variables are just your containers for any info you need to store and manipulate. Next to variables, events are very important because they are the "triggers" that start the execution of some lingo. Things like the movie starting, the pressing of a key or clicking of a mouse are in a very real sense an event. This is great because you can take advantage of different types of events to pretty much do whatever you want.

Normally I like to take advantage of the startmovie event to set up my variables and other conditions. This gets things started but once everything is up and going, the movie needs to stay in a section of the score that you want it to. To do this, you have to take advantage of another event and just catch the "event" of the score's playhead leaving the frame that it is in and make it jump back a number of frames or just loop over the same one. Sprites with behavior scripts attached to them allow additional user provided events - clicks n such - to trigger the instructions that they need to.

In Lingo, events are intercepted, caught or "trapped" by handlers. An "Event handler" is a simple handler that specifically handles the event that is generated by some action. Clicking the mouse, for example. This is great because the handlers are made to contain your custom lingo where they can do whatever you design them to do. The goal here is to use the event handlers to call your custom handlers you write to perform specific tasks much like in the example below:


on StartMovie 
  -- A lingo standard event handler
  InitGlobals
  InitObjects
  InitConditions
end
on InitConditions 
  -- custom handler to declare all the global variables
  -- declare your globals here and assign initial values
end
on InitObjects 
  -- custom handler to "instantiate" (aka create) any objects
  -- create any objects here
end
on InitConditions 
  -- custom handler to set up any remaining conditions
  -- set up any start conditions here
end

Now that you've got an example and quick overview of the built-in event handlers, it'd probably be pretty nice to know what they are. Without further adeau here are many of the event handlers you can use in Dir 6...

Events:

Movie play events:

PrepareMovie
This event happens before startmovie.
StartMovie
When the movie starts up, this event is triggered and all code within the StartMovie handler is called.

StopMovie
This one gets executed when the movie stops.

Timeout
There is a movie property that can be set which is called "the timeoutlength". This property is in ticks or 60ths of a second. If you set the timeoutlength to 300, any code within the timeout handler, will get executed every 5 seconds.

Idle
This event gets triggered when no other handlers are executing or "idle time" exists. This event is often used in a movie script AND in frames scripts. More on that later.

Frame Events:

EnterFrame
Every time the playhead enters a frame, an enterframe is triggered. If a score frame script has an enterFrame handler in it, the lingo within it will be executed.
ExitFrame
When the play head leaves a frame, an Exitframe event gets generated and all code within a script's ExitFrame handler gets executed.

PrepareFrame
Happens right before an enterFrame.

BeginSprite
In Director 6, there are these things called sprite spans, basically a continous set of frames that hold the same sprite. BeginSprite happens when a sprite span starts and before a prepareframe.

EndSprite
Guess what? EndSprite happens at the end of a sprite span. If there is an ExitFrame handler in any of the scripts on the current frame, EndSprite happens after that.

Idle
Same as in the movie section but can also be used in frame scripts.

Sprite Events:

MouseDown
When the mouse button is clicked a mouseDown is generated. Usually, this event handler is attached to a sprite.
MouseUp
When the mouse button is released, MouseUp happens. Again this handler is usually attached to a sprite.

MouseUpOutside
MouseUpOutside happens if a mouse click started on sprite and ended (with the release of the mouse) not on that sprite.

RightMouseDown
On PCs with right mouse buttons, clicking the right mouse will generate this event.

RightMouseUp
And to no big surprise, releasing the right mouse button will generate this one.

MouseEnter
This event does what you think it does but is also dependant upon the ink used to display the sprite. If copy ink is used, this event is generated when the mouse rolls into the rectangle surrounding the sprite. Often this is not what people want so the inks of background transparent or matte are used.

MouseWithin
The code that is in this handler gets executed repeatedly when your cursor is within a sprite. Each time the play head crosses the frame and if the cursor is over the sprite, a MouseWithin is generated.

MouseLeave
If there was ever a handler that should be renamed to MouseExit, this is it. Guess what, it gets called/triggered when the cursor leaves the sprite it is attached to.

KeyDown
Key events are very important and tricky events. For a key event to be generated, the stage must be active. You've got to click on it when authoring or the the event will not get triggered. Happens when a key is pressed. Can be checked for at "whole movie" level or per sprite or even per frame.

KeyUp
The releasing of a key registers a KeyUp event.

New
New is usually the event name of choice when creating an object. In this case, it is not an event but merely a handler that you have called to create the script. In a behavior however, new can be used to set up any properties when the behavior comes into existance and is a Director event.

Sound Events:

CuePassed
Sound files can have "cue points" much like the score has markers. The on CuePassed handler can detect when a playing sound file has passed a cue point and execute lingo based upon which point it has passed.

Other:

Stepframe
A legacy event from Versions of Director Gone By, this is pretty close to enterFrame and is only received by lingo objects within the structure known as the actorlist.
StreamStatus
To the best of my knowledge, streamstatus is repeatedly sent when internet actions are present. A rather difficult handler to work with, it can be used to return how much of the specified internet operation is complete.

Movie In a Window Events:
These events are beyond the scope of this "intro" document. Look for an article on Movies in a Window in the future.

Even though there are a large number of events, you don't need to use them all. Honestly, the ones I use the most are :
StartMovie
EnterFrame
ExitFrame
MouseUp
MouseDown
KeyDown
Idle
New

Sometimes, there is a parameter called "me" that follows handlers. That me is VERY cool. Imagine if you will, that you can stuff all the handlers, their code and all variables into one little variable and pass it around from handler to handler. That's what "me" is. We could call it Fozzie for all we care, but that "me" implies that the handler has a parameter that is the script that the handler belongs to and that's pretty much what it is. Picture the concept of a cup holding pencils and a pencil sharpener. The cup is your script. The pencils are property variables because they can be anywhere in the cup (even in the sharpener) and the sharpener is a handler. Now if you've got that, the me is a copy of all that stuffed into one neat n tidy variable. That type of organization is what allows behaviors and objects to work the way they do.

Now that you've got more handlers than hangovers on New Year's Day, the other important concept is where in the movie they exist. See, we've got movie scripts, sprite behaviors, objects and frame scripts in Director. You can check for a mouseDown in any one of these but you probably want it in a behavior that is tied to a specific sprite. You don't have to do it that way, a mousedown in a frame script could check to see what the currentSpriteNum or the clickOn is and execute a script based on which sprite was clicked on.

The question is "what is the best approach for what you are trying to produce?" In fact, these different areas where events can happen -- and your decisions about where to do what -- provide organizational structure to your lingo. An ExitFrame handler in a movie script will execute on every ExitFrame. One in a frame script or even in a sprite will only execute when the score frames that the script is in get exited from. In particular many events or handlers that are in behaviors will only happen if the sprite that they are attached to get that event or if you deliberately call it. You can look at this type of organization when building your next project since it is very important "where" in your scripts the events get intercepted.

Think about it this way: Events that your movie needs to respond to, needs to be looked at to determine where you should put them in your movie.

Now that you've got a pretty good description of events, play with the sample movies and create a few of your own. By fully understanding events in Director, you can do even more cool stuff than you could before. Enjoy.

A series of Director movies demonstrating each class of events is available for downlaod in ZIP format.

A Director user since 1987, Alex (Zav) Zavatone has worked on the engineering teams for both Director and Shockwave, 4, 5, 6 and 7. Recent investigations find him developing foundation classes for Director with asynchronous process management and other life threatening activities. In its early days, he had something to do with this Internet thing known as "DOUG". A noted ne'erdowell, slacker and laggard, Mr. Zavatone is nonetheless is trusted by children, small animals and the elderly. In his spare time, Mr. Zavatone rehabilitates lame desert trout.