Messages and Events

To run the appropriate set of Lingo statements at the right time, Director must determine what is occurring in the movie and which Lingo to run in response to specific events.

Director sends messages to indicate when specific events occur in a movie, such as when sprites are clicked, keyboard keys are pressed, a movie starts, the playback head enters or exits a frame, or a script returns a certain result.

Handlers contain instructions that run when a specific message is received. The handler's name begins with the word on followed by the message name. When an object receives a message that corresponds to a handler attached to the object, Director runs the Lingo statements within the handler. For example, a handler named on enterFrame that is attached to a frame runs when the playback head enters the frame.

Most common events that occur in a movie have built-in message names. See the following categories in the Lingo Dictionary for the built-in messages that describe events:

• Keyboard and mouse events.
• Frame events.
• Browser and Internet events.
• Sprite events.
• Movie in a window events.
• Movie events.
• Synchronizing media events.
• Idle events.
• Timeout events.
• Authoring behavior events.

You can also define your own messages and corresponding handler names. A custom message can call another script, another handler, or the statement's own handler. When the called handler stops executing, the handler that called it resumes. Director can send a custom message from any location. The message is first available to handlers in the script from which the message was sent. If no handler is found, the message is available to movie scripts. If more than one movie script contains a handler for the message, the handler in the movie script that has the lowest cast member number is executed. A custom handler name must:

• Start with a letter
• Include alphanumeric characters only (no special characters or punctuation)
• Consist of one word or multiple words connected by an underscore-no spaces are allowed
• Not be the same as the name of a predefined Lingo element

Using Lingo keywords for handler names can create confusion. Although it is possible to explicitly replace or extend the functionality of a Lingo element by using it as a handler name, this should be done only in certain advanced situations. When you have multiple handlers with similar functions, it is useful to give them names that have similar beginnings so they appear together in an alphabetical listing, such as the listing displayed by the Find Handler option in the Edit menu.

Director follows a definite order when sending messages about events that occur during the course of a movie. When the movie first starts, events occur in the following order:

• prepareMovie.
• beginSprite. This event occurs when the playback head enters a sprite span.
• 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. An on prepareFrame handler is a good location for Lingo that you want to run before the frame draws.
• startMovie. This event occurs in the first frame that plays.

When Director plays a frame, events occur in this order:

• beginSprite. This event occurs only if new sprites begin in the frame.
• stepFrame.
• 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.
• enterFrame. After enterFrame and before exitFrame, Director handles any time delays required by the tempo setting, idle events, and keyboard and mouse events.
• exitFrame.
• endSprite. This event occurs only if the playback head exits a sprites in the frame.

When a movie stops, events occur in this order:

• endSprite. This event occurs only if sprites currently exist in the movie.
• stopMovie.

A movie can contain more than one handler for the same message. Director manages this situation by sending the message to objects in a definite order.

The general order in which messages are sent to objects is as follows:

• Messages are sent first to behaviors attached to a sprite involved in the event. If a sprite has more than one behavior attached to it, behaviors respond to the message in the order in which they were attached to the sprite.
• Messages are sent next to a script attached to the cast member assigned to the sprite.
• Messages are then sent to behaviors attached to the current frame.
• Messages are sent last to movie scripts.

When a message reaches a script that contains a handler corresponding to the message, Director executes the handler's instructions.

After a handler intercepts a message, the message doesn't automatically pass on to the remaining locations. (You can use the pass command to override this default rule and pass the message to other objects.) If no matching handler is found after the message passes to all possible locations, Director ignores the message.

The exact order of objects to which Director sends a message depends on the message. See the message's Lingo Dictionary entry for details about the sequence of objects to which Director sends specific messages.

You can place handlers in any type of script. However, the following are some useful guidelines for many common situations:

• To set up a handler that affects a specific sprite or runs in response to an action on a specific sprite:

  Put the handler in a behavior attached to the sprite.

• To set up a handler that should be available any time that the movie is in that frame:

  Put the handler in a frame script attached to the frame.

  For example, to have a handler respond to a mouse click while the playback head is in a frame, regardless of where the click occurs, place an on mouseDown or on mouseUp handler in the frame script rather than a sprite script.

• To set up a handler that runs in response to an event that affects a cast member, regardless of which sprites use the cast member:

  Put the handler in a cast member script.

• To set up a handler that runs in response to messages about events anywhere in the movie:

  Put the handler in a movie script.

  A script can contain multiple handlers. It's a good idea to group related handlers in a single place, though, for easier maintenance.