User Guide

Events, messages, and handlers 33
Events, messages, and handlers
A key component to creating powerful, useful scripts is an understanding of the concepts and
functionality of events, messages, and handlers. Understanding the order in which events and
messages are sent and received will help you determine exactly when specific scripts or parts of
scripts should run. It will also help you debug scripts when specific actions are not occurring
when you expect them to occur.
When a movie plays, the following occurs:
1 Events occur in response to either a system or user-defined action
2 Messages that correspond to these events are sent to the scripts in a movie
3 Handlers within scripts contain the instructions that run when a specific message is received
The name of an event corresponds to the name of the message it generates, and the handler that
handles the event corresponds to both the event and the message. For example, when the event
named
mouseDown occurs, Director generates and sends to scripts a message named mouseDown,
which would in turn be handled by a handler named
mouseDown.
Events
There are two categories of events that occur when a movie plays:
• System events occur without a user interacting with the movie, and are predefined and
named in Director. For example, when the playhead enters a frame, when a sprite is clicked,
and so on.
• User-defined events occur in response to actions that you define. For example, you could
create an event that occurs when the background color of a sprite changes from red to blue,
when a sound has played five times, and so on.
Many system events, such as
prepareFrame, beginSprite, and so on, occur automatically and
in a predefined order while a movie is playing. Other system events, particularly mouse events
such as
mouseDown, mouseUp, and so on, do not necessarily occur automatically while a movie is
playing, but rather when a user triggers them.
For example, when a movie first starts, the
prepareMovie event always occurs first, the
prepareFrame event always occurs second, and so on. However, the mouseDown and mouseUp
events may never occur in a movie unless a user triggers them by clicking the movie.
The following lists illustrate the system events that always occur during a movie, and the order in
which they occur.
When the movie first starts, events occur in the following order:
1 prepareMovie
2 prepareFrame Immediately after the prepareFrame event, Director plays sounds, draws
sprites, and performs any transitions or palette effects. This event occurs before the
enterFrame
event. A
prepareFrame handler is a good location for script that you want to run before the
frame draws.
3 beginSprite This event occurs when the playhead enters a sprite span.
4 startMovie This event occurs in the first frame that plays.