Table of Contents

Key.property
Key.methodName()

Properties

Table 18-8 lists the properties of the Key object.

Table 18-8. Key object keycode properties

Property	Equivalent keycode		Property	Equivalent keycode
BACKSPACE	8		INSERT	45
CAPSLOCK	20		LEFT	37
CONTROL	17		PGDN	34
DELETEKEY	46		PGUP	33
DOWN	40		RIGHT	39
END	35		SHIFT	16
ENTER	13		SPACE	32
ESCAPE	27		TAB	9
HOME	36		UP	38

Methods

addListener( )

Registers an object to receive onKeyUp( ) and onKeyDown( ) events.

getAscii( )

Returns the ASCII value of the last key pressed.

getCode( )

Returns the keycode of the last key pressed.

isDown( )

Checks if a specific key is currently depressed.

isToggled( )

Checks if the Num Lock, Caps Lock, or Scroll Lock keys are activated.

removeListener( )

Cancels event notices for the specified listener.

Listener Events

onKeyDown( )

Occurs when a key is depressed.

onKeyUp( )

Occurs when a key is released.

Description

The Key object is used to determine which keys are currently depressed and which key was last released. We can use it to build interfaces controlled by the keyboard, such as a game with a spaceship moved via the arrow keys.

Because not all keyboards are identical, keyboard-controlled interfaces can sometimes be tricky to create. By choosing our scripting tools correctly, however, we can ensure that all users have the same experience.

There are two general approaches to detecting keyboard commands:

• We can check if a key is currently depressed via the isDown( ) method. This is recommended for cases in which the keyboard state needs constant polling (i.e., checking repeatedly), such as in video games. To poll the keyboard, use isDown( ) to check the keyboard state within a MovieClip.onEnterFrame( ) handler or during an interval created via setInterval( ).

• We can check which key was last released using the getCode( ) and getAscii( ) methods. This is recommended for typical keyboard-driven interfaces in which specific operations are performed in response to individual keys being pressed. We ordinarily use these methods from an onKeyDown( ) or onKeyUp( ) event listener, or a movie clip's onClipEvent(keyDown) or onClipEvent(keyUp) handler. There is no need to constantly check (i.e., poll) for the last key pressed. In fact, doing so leads to erroneously repeating some operation even if a key wasn't pressed repeatedly. That is, you should generally check getCode( ) and getAscii( ) from a listener or clip event only to guarantee the code is executed once and only once for each keystroke.

The isDown( ) method is synchronous, as is the isToggled( ) method. They both report on the current state of the keyboard at the time the method is called. For example, isDown( ) returns false if the key of interest is released before the call to isDown( ) is made. On the other hand, the getAscii( ) and getCode( ) methods are asynchronous. They report on the last key pressed, even if it has been released. Therefore, it is usually a mistake to call getAscii( ) or getCode( ) unless a keyboard event has been detected via, say, an onKeyDown( ) listener. Both getAscii( ) and getCode( ) will continue to report the same value indefinitely (or until another key is pressed), even if no key is currently being pressed.

The so-called Windows virtual keycode (or simply keycode) returned by getCode( ) and required by isDown( ) is a number representing the physical keys on the keyboard, not the symbols on those keys and not their ASCII values. By using the keycode, we can identify keys even when a movie is running on different operating systems or when two keyboards use different languages or have different symbol layouts.

On most keyboards, the keycodes of the keys A to Z are the same as the code points (65-90) for the equivalent uppercase Latin 1 letters (also the same as their ASCII codes). The keycodes of the keys 0 to 9 are, likewise, the same as the Latin 1 and ASCII values for those numbers (48-57). The key codes of other keys do not necessarily match Latin 1 code points, although some, such as the Tab key, match the ASCII values. However, many of the nonletter and nonnumber keycodes are available as properties of Key, as shown in Table 18-8. For example, we don't have to remember that the up arrow uses keycode 38; we simply use the Key.UP property. The following code checks whether the up arrow key is currently depressed:

if (Key.isDown(Key.UP)) {
  trace("The up arrow is being pressed");
}

When working with a keycode that is not a letter or a number and is not available as a property of Key�such as those of the function keys (F1, F2, etc.)�it's safest to create a quick test movie to check the keycode of the desired key, as follows:

var keyTester = new Object();
keyTester.onKeyDown = function () {
  trace(Key.getCode());
}
Key.addListener(keyTester);

When testing keys in Test Movie mode, be sure to disable keyboard shortcuts via Control Disable Keyboard Shortcuts.

The keycodes are listed in Appendix B.

Usage

The onKeyDown( ) and onKeyUp( ) listener events were added to the Key object in Flash 6. They are preferred over MovieClip.onKeyDown( ) and MovieClip.onKeyUp( ) and the Flash 5-style onClipEvent(keyDown) and onClipEvent(keyUp) handlers in most cases.

However, the following caveats apply:

• In Flash 6, the updateAfterEvent( ) function, which refreshes the screen between frames, can be used only with MovieClip mouse and key events and setInterval( ). Hence, to create instant-refresh keyboard applications, use onClipEvent(keyDown) and onClipEvent(keyUp), which are directly analogous to Key.onKeyDown( ) and Key.onKeyUp( ).

• To capture keystrokes while a specific movie clip has input focus only, use the MovieClip.onKeyDown( ) and MovieClip.onKeyUp( ) handlers. See those entries for details.

See Also

MovieClip.onKeyDown( ), MovieClip.onKeyUp( ); Chapter 10, Appendix B

Table of Contents