Lingo 3 Tutorial: Events and Handlers

READING: We are about to get into a little deeper waters now. You have to read carefully Chapter 8 of the D8D and answer all the questions within this tutorial

Director is supposedly(*) based on a few principles that are known as "Object-oriented Programming". What this means for you is that, everything in Director is an "object". A drawing you created is an object. A field you display is an object. Even a frame and a director movie is an object. (*)"supposedly" means "not completely". The addition of the keyword "me" at the end of some event handlers that lingo is adding automatically is the most prominent feature of an object's script that affects the object itself. Ignore it - all of the scripts we will be writing will be of that sort.

Objects have properties (can remember facts) and methods (can do things).
For example, "member(x).text" says that text is a property of a cast member object;
" stop" is a method of the movie object.

During the run of a program, Director is watching for "events". Director's events are similar to JavaScripts events, but they are many more than them. There are at least 27 such events, probably more than you can learn how to use effectively in this course. We will point out the ones that we view as really necessary.

Events related to the Playback head (to be demoed by playbackHeadEvents.dir)

startMovie, stopMovie,
enterFrame, exitFrame
Not for now: prepareFrame, prepareMovie, cuePassed, beginSprite, endSprite

Events related to User Actions (to be demoed by userActionsEventsXX.dir)

mouseDown, mouseUp (rightMouseDown, rightMouseUp)
mouseEnter, mouseLeave
mouseWithin, mouseUpOutside
keyDown, keyUp

Events related to Time (to be demoed by timeEventsXX.dir)


Events related to multiple Window Control

Not for now: activateWindow, deactivateWindow, openWindow, closeWindow
Not for now: moveWindow, resizeWindow, zoomWindow

These events are sent to the appropriate level of the Event Hierarchy:
For example, clicking on a sprite sends a mouseDown event to the following sequence of objects, until it is handled:

Sprite -> Cast -> Frame -> Movie -> Director

For each of the above objects you can write event handlers to respond to the event. Once a handler is executed, the event stops propagating, unless the handler contains the pass command. A pass command will allow the propagation of the event up the hierarchy.


To start this tutorial look at the file "playbackHeadEvents.dir". Make sure the "loop playback" button is off (->|)
Open the message window (cmd-M) and observe the events happening. The typical messages are
-- "The movie starts"
-- "entering frame 1"
-- "Taking a break"
-- "exiting frame 1"
-- "entering frame 2"
-- "Taking a break"
-- "exiting frame 2"
-- "That's all folks!"

Q1: Who sends the messages?

Turn on the "loop playback" button. What do you expect to happen? Test it.


Now run the movie "userActionsEvents00.dir", and click on the red dot. You get the message
-- "mouse up on sprite"
When you click outside the red dot you get
-- "mouse up on frame"

Q3: Why?

Now edit the sprite and frame scripts to Pass the messages after you process them.
The messages now are: when clicking on the red dot:
-- "mouse up on sprite"
-- "mouse up on cast member"
and when clicking outside it:
-- "mouse up on frame"
-- "mouse up on movie"

Q4: Why?

Edit the script of the cast member to pass the message. What is the behavior of the clicks now?
Edit the script of the movie to pass the message. What is the behavior of the clicks now?
On a piece of paper draw the paths that your clicks are taking.


Run the movie "userActionsEvents01.dir", and click on the red dot. Now you capture messages about mouseDown instead of mouseUp.
Edit the scripts of sprite and frame to also report mouseUp's and watch their behavior in the Message window.


Yet again, open the movie "userActionsEvents02.dir", and bring your cursor over the red dot. Notice the reporting of the script for mouseWithin.
Move the cursor quickly in the red dot, click on it and move it outside the red dot quickly. If you are as fast as I am (;-) you would get:
-- "mouse WITHIN the cast member"
-- "mouse WITHIN the cast member"
-- "mouse WITHIN the cast member"
-- "mouse WITHIN the cast member"
-- "mouse DOWN on CAST MEMBER"
-- "mouse up on SPRITE"
-- "mouse up on CAST MEMBER"
-- "mouse up on FRAME"
-- "mouse up on MOVIE"
-- "mouse WITHIN the cast member"
-- "mouse WITHIN the cast member"

Q5: Why there is no reporting mouse DOWN on the sprite?

To review, here is the hierarchy in which the message events are going through:

Sprite -> Cast -> Frame -> Movie -> Director

Sing it 56 times every morning until you memorize it completely!


Open the movie "userActionsEvents03.dir", and bring your cursor over the red dot. Notice the behaviour of the script for mouseWithin now makes you chase the ball. Try to click on the dot and release slowly. Hear the beep. Observe the behavior of the script for mouseUpOutside.

Q6: Why the mouseUpOutside is not activated when you just click outside the dot?
While we are at it, observe how the sprite(1).locH is used to to move the dot to the right.

Q7: What other properties you can you guess exist for a sprite? How can you find out?


Open the movie "userActionsEvents04.dir", and bring your cursor over the red dot. When you move the cursor over the red dot, the text "WOW" to appear on the dot, and when you move the cursor away from the red dot, the text disappears. (Many programs' UIs have such a popup window these days, to explain what will happen if you click a button.)

Q8: How do you do that?Guess and verify your answer by looking at the script.


Open the movie "userActionsEvents05.dir", run it, and try to guess what the scripts look like. Verify that your guess was right or find out why it was not.

Q10: Modify the movie so that the ball bounces up and down, never sinking to the bottom for good. Explain how to do that.


There are also two movies "timeEvents01.dir" and "timeEvents02.dir" that wake up the user after 5 seconds with two different ways: an alert box and going to another frame.

Q11: Describe a situation in which the first way is useful and another in which the second way is useful.

All of the above are CRUCIAL elements of understanding Lingo: Make sure you can answer all of the above mentioned questions. They will come up again and again almost every time you work on your project.


So, you have figured out that you need to write a script, and what type of script it should be (sprite, cast member's frame's or movie's).

But where do you find the actual location that will contain your script? Here is some help:

SCRIPT TYPE Descriptive picture

Control-click (on the Mac)
or right-button click (on the PC)
to bring up the sprite menu.
Select Script... from this menu.

(Longer process, just so you know:) Select the sprite you want to write the script for.
Double-click on the behavior wheel
to bring up the Property inspector,
open at the Behavior tab.

Click on the + to add a new behavior;
name it (here it is named "New Behavior")
Double-click on it
OR click on the scroll above, to edit it.



Select the cast member.
Then click on the scroll-like button above.
That will bring you to the right place.
A template will appear expecting that you likely going to write a mouseUp handler.



Double-click on the script channel of the frame that you want the script to be active
This will bring you to the right place.
A template will appear expecting that you likely going to write a exitFrame handler.



In the scripts window (command-0)
do control-click (on Mac)
or right-button click (on the PC)
to bring up the Add NewMovie Script menu.

Sometimes you have a movie script and you would rather have it behave
as a frame script or as a sprite script (Director calls those behavior scripts).
Highlight it in the cast,
then bring up the property window.
Under Script you have a chance to select its type.



Maintained By: Takis Metaxas
Last Modified: October 17, 2013