User Interaction

Finally, we come to user interaction, one of the key points of what you are doing here. After all, if it werent for interaction or some sort of dynamic input going into the movie, you might as well just use tweens.

Actually, there is not a whole lot left to discuss here that I havent already touched on earlier in the chapter. User interaction is based on user events, and these generally come down to mouse events and keyboard events. Lets quickly go through the various user events and their handlers.

Mouse events

A movie clip or button is automatically a listener for any of these events. You just need to create an event handler function for that event. The name of that event is always on plus the capitalized name of the event. For example, if you had a clip named square , you could handle the press event as follows :

 square.onPress = function():Void {    // actions }

The following are the mouse events:

dragOut : Occurs when the user presses a mouse button while over graphical content and, while still pressing the mouse button, moves the mouse off of that content.
dragOver : Occurs after dragOut if the user, still holding down that mouse button, drags back over the graphical content. Im not sure I could come up with a useful example of this one if I tried, but if you ever find yourself needing such a thing, its available.
mouseDown : Occurs whenever a mouse button is pressed, regardless of mouse location, visibility, or any other factors. This is often a source of confusion for programmers who think of mouseDown as press . In fact, when a mouse button is pressed, every single movie clip in the movie will receive a mouseDown event.
mouseMove : Occurs whenever the mouse is moved. You should be careful about using this event, as it can generate hundreds of calls per second and really slow down a movie. Use it only when necessary, turn it off when you are done with it, and keep the code it executes to a minimum.
mouseUp : Occurs whenever a mouse button is released. All the same rules for mouseDown apply.
mouseWheel : Occurs when the user scrolls the mouse wheel, if it exists. Note that even though a movie clip is a listener for mouse events by default, for some reason, it will not automatically listen for the mouseWheel event. If you want a movie clip to handle this event, you must explicitly call Mouse.addListener( yourMovieClip ) to add it as a mouse listener.
press: Occurs when the user presses a mouse button while the cursor is over any visible graphical elements in the movie clip. If the movie clips _visible property is set to false , it will not receive press events. Any portion of graphical content that is invisible due to masking will not generate press events if clicked on. However, setting the _alpha property to zero will effectively make the content invisible while still allowing it to receive press events.
release : Occurs after press when the user releases the mouse button while still over any visible graphical content in a movie clip. All the same rules for press apply. The release event occurs only after a press event, and press events are always followed by either release or releaseOutside .
releaseOutside : Occurs after press when the user has moved the mouse off the graphical content and then releases the mouse button. User interface buttons almost always listen for release and ignore releaseOutside . This allows the user to cancel the button press by moving off the button before releasing.
rollout : Occurs when the mouse is over visible graphical content and moves off, while no mouse buttons are being pushed .
rollover : Occurs when the user moves the mouse pointer over the graphical content in a movie. As with press , the content must be visible and not hidden by a mask, though the _alpha property can be set to zero.

As you can see, most of these events deal with the graphical content in a movie clip. As such, they really apply only to movie clips or buttons, which can also contain graphics. You cannot listen for, say, a press event on a generic object or a custom class that does not subclass MovieClip , as these would have no visible graphical content. The only mouse events such an object can listen for are mouseDown , mouseUp , mouseMove , and mouseWheel .

Keyboard events

Movie clips are technically listeners for keyboard events. But theres a catcha serious one. The movie clip must have keyboard focus , which is usually acquired only by using the TAB key to tab between objects. This means that you need to set focusEnabled = true and tabEnabled = true , and then tab to the movie clip. Then the movie clip can receive keyboard events. Oh, but if you move the mouse at alleven 1 pixelyour movie clip will lose focus and wont respond to keyboard events.

Given the fleeting nature of the automatic keyboard listening, it is usually best to just force the issue by saying Key.addListener( yourMovieClip ) . This allows the movie clip to receive all key events, regardless of focus.

The following are the keyboard events:

keyDown : Supposedly occurs whenever a key is pressed. This is a bit misleading though, because in most cases, you will get a continuous series of keyDown events as long as the key is being held down.
keyUp : Occurs whenever a key that has been pressed is released. If you want to ensure that you get only one event per key press, this is the one to use.

Mouse position

In addition to mouse events, two very important properties are always available to determine the current location of the mouse pointer: _xmouse and _ymouse . Note that these are properties of a movie clip, and the values returned are the mouses position in relation to the registration point of that clip. For example, if you had a movie clip instance named clip sitting at 100, 100 on the stage, and the mouse pointer were at 150, 250, you would get the following results:

_root._xmouse would be 150.
_root._ymouse would be 250.
clip._xmouse would be 50.
clip._ymouse would be 150.

Notice how the movie clip is taking the mouse position in relation to its own position.

Key codes

Often, you want to know not just that a key has been pressed, but which key has been pressed, or if a particular key is currently being pressed. ActionScript provides a couple of functions to handle such things.

First is Key.getCode . This returns a number responding to the code of the key that was last pressed. Now, if you know all the key codes by heart, youre all set. But more likely, youll want to use the key enumerations, which allow you to use a human-readable word describing the keysuch as Key.SPACE , Key.UP , or Key.DOWN rather than numbers . You just compare the result from Key.getCode() to the key you want to handle, as follows:

 if(Key.getCode() == Key.UP){    // move object up }

 if(Key.getCode() == Key.SPACE){    // pause game }

You can find a full list of the key enumerations in the Flash help files.

If you want to find out if a specific key is currently being pressed, use the Key.isDown function, passing it the code of the key you want to check:

 if(Key.isDown(Key.UP)){    // move object up }

Whereas Key.getCode() will always return the code of the last key pressed, even if that key was pressed six hours ago, Key.isDown() returns true only if the specified key is down at the time you check it.

One thing you should know about key handling is that when you are testing a movie in the Flash authoring environment, the IDE intercepts some keys to control the IDE itself. TAB , all function keys, and any keys assigned as shortcuts to menu items will not be received by your movie while testing. You can disable this by choosing Control Disable Keyboard Shortcuts from the menu while the movie is running. This allows you to test your movie as it will actually work in a browser.