Understanding Events and Handlers

A Director movie may be thought of as a series of events ”things that happen on the Stage or in the Score. Some events are automatic, such as the playhead entering a new frame. Other events are user -initiated ”for example, a click of the mouse button or the pressing of a key on the keyboard.

Whenever an event occurs, Director generates a one-word message acknowledging the event. (For example, when the mouse button is released, Director generates the message " mouseUp .") The user doesn't see these messages; they're solely for internal communication within Director. Table 15.1 shows a list of common events that can occur while a movie is playing and the messages those events generate.

Table 15.1. Movie events and Lingo messages

E VENT	M ESSAGE AND H ANDLER N AME
A window is activated	activateWindow
A window is closed	closeWindow
A window is deactivated	deactivateWindow
Playhead enters frame with a new sprite	beginSprite
Playhead leaves a sprite	endSprite
Playhead enters current frame	enterFrame
Playhead exits current frame	exitFrame
Playhead enters a frame but hasn't displayed it yet	prepareFrame
No event occurred	idle
A key is pressed	keyDown
A key is released	keyUp
Mouse button pressed	mouseDown
Mouse button released	mouseUp
Mouse pointer enters a sprite	mouseEnter
Mouse pointer leaves a sprite	mouseLeave
Mouse pointer stays within a sprite	mouseWithin
Movie starts playing	startMovie
Movie stops playing	stopMovie
Movie is about to start playing	prepareMovie

You can give Director specific instructions about how you want it to handle (respond to) a particular message. That set of instructions is called a handler . Handlers are the building blocks of Lingo scripts.

Every handler has three parts ( Figure 15.3 ):

Figure 15.3. Every handler has three parts: The first line specifies the event that triggers the handler, the body lists commands that should be executed, and the last line concludes the handler.

• The first line always begins with the word on , followed by the message to which the handler should respond. (Handlers are referred to by the name of the message that triggers them. For example, the handler in Figure 15.3 is called a mouseUp handler, because it responds to the message generated when a user releases the mouse button.)

• The body of the handler (the indented part) contains the commands that are executed when the handler is triggered. The commands are executed in the order in which they appear in the handler.

• The last line always consists of the word end . (This is so Director can know where one handler ends and the next one begins.)

(Note: For convenience, handlers are often described as responding to ”or being triggered by ”events in a movie. There's nothing wrong with using this informal shorthand, as long as you realize that handlers technically respond to the messages generated by events, not to the events themselves .)