Recipe 9.15. Detecting Keystrokes

Problem

You want to detect when the user presses a key on the keyboard.

Solution

Add a listener object to the Key class.

Discussion

If you want to detect key presses with Flash, you've got to write a small amount of ActionScript code. In order to handle keyboard interactivity, Flash uses a specific ActionScript class called Key. The Key class detects when keys are pressed and released, and it reports which keys have been pressed. When the Key class detects that some keyboard event has occurred, it sends out a notification to any object that has been registered with it as a listener. A listener object is an ActionScript construct that you can register with the Key class once, and each time the Key class dispatches notifications, the listener object can respond appropriately. All you need to do is tell the listener object what ActionScript code it should run when it gets a notification.

Key class listener objects can receive notifications for two types of keyboard events: keys being pressed and released. In order to handle those events, define event handler methods on the listener object with the names onKeyDown( ) and onKeyUp( ).

The onKeyDown( ) method, as the name (exp 3pod.com) would suggest, gets called when a key is pressed. And similarly, the onKeyUp( ) method is called when a key is released.

If defining listener objects and custom event handler methods is new to you, don't worry. It requires only a few lines of code. The following code defines a listener object as well as an onKeyDown( ) and onKeyUp( ) method for the object:

	var oKeyListener:Object = new Object();
	oKeyListener.onKeyDown = function():Void {
	  // Code you want to run when the key is pressed. For example:
	  trace("Key pressed");
	};

	oKeyListener.onKeyUp = function():Void {
	  // Code you want to run when the key is released. For example:
	  trace("Key released");
	};

When you've defined the listener object and its event handler methods, the next thing you need to do is register it with the Key class. That step is important, because otherwise the Key class won't know to send the notifications to that listener. To register a listener object with the Key class requires only a single line of code. The addListener( ) method requires a single parameter referencing the listener object you want to register. The following example registers a listener object named oKeyListener with the Key class:

	Key.addListener(oKeyListener);

Frequently, you'll want to know more than simply that some key has been pressed. Rather, you'll want to know which key has been pressed. The Key class has built-in functionality that can report that information using the getCode( ) method. The getCode( ) method returns the numeric code that corresponds to the key that was pressed, and the getAscii( ) method returns the ASCII code that corresponds to the key that was pressed. For uppercase alphabetic character and numeric keys, the getCode( ) and getAscii( ) methods return the same values. The character codes for upper-and lowercase alphabetic characters are the same, so if you want to differentiate between upper-and lowercase, you should use getAscii( ). However, for non-alphanumeric keys such as Shift, Enter, arrowkeys, and so on, you should use the getCode( ) method, because the Key class also has some built-in constants that you can use to compare with character codes.

You can use the String class's charCodeAt( ) method to get the ASCII code for a particular character in order to compare it with the character code of a pressed key. Even though the name (exp 3pod.com) of the method would suggest that it returns a character code, it returns the ASCII code, so you can compare the value with the value returned by Key.getAscii( ). The following code creates a listener object that tests to see if the user has pressed a lowercase r key:

	var oKeyListener:Object = new Object();
	oKeyListener.onKeyDown = function():Void {
	  // Create a string with the value of the character you want to use in the
	comparison.
	  var sCharacter:String = "r";

	  // Retreive the character code for the character.
	  var nCode:Number = sCharacter.charCodeAt(0);

	  // Check to see if the code of the key that was pressed matches the character code
	of
	  // the character for which you are wanting to check.
	  if(Key.getAscii() == nCode) {
	    trace("You have pressed the r key.");
	  }
	};

	Key.addListener(oKeyListener);

The getCode( ) method returns codes for lots of non-alphanumeric keys, making it a good choice for determining whether and when keys like the arrow keys have been pressed. To make your job even simpler, the Key class has some built-in constants that return the character codes for some common keys such as the up, down, right, left, shift, backspace, and enter keys. You can find a complete list in the Help panel by searching for Key class. The following code creates a listener object that detects when the right arrow is pressed:

	var oKeyListener:Object = new Object();
	oKeyListener.onKeyDown = function():Void {
	
	  if(Key.getCode() == Key.RIGHT) {
	    trace("You have pressed the right arrow key.");
	  }
	};

	Key.addListener(oKeyListener);