In this tutorial, we'll explain how to use the keyboard to control user's interactions with the game.

To enable it, we must use the Keyboard class of JPlay's package.

It is not necessary to create an instance of Keyboard class because when an object of Window's class is created, an instance of Keyboard is created as well. Doing this, all the game objects will use the same keyboard.

To have access to the Keyboard, offered by Windows class, we use the following method:

Keyboard getKeyboard();

1 - Default Keys

A classe Keyboard disponibiliza um conjunto de teclas padrão para ser usado na movimentação dos elementos do jogo, por exemplo. Para acessar os códigos destas teclas digite Keyboard seguido de um ponto final. Esta ação irá; resultar no aparecimento de vá;rias opçõ;es de teclas.

The class Keyboard offers a set of default keys to be used to move elements of the game. To access the codes of these keys just type Keyboard followed by a period. This action will show many options of keys.

The default keys of JPlays's keyboard are:

DOWN_KEY, ENTER_KEY, ESCAPE_KEY, LEFT_KEY, RIGHT_KEY, SPACE_KEY,UP_KEY.

2 - Pressed keys and keys behaviour

To determinate if a key is pressed we use the method:

								//Returns 'true' if the key mapped on the keyCode is pressed, returns 'false' otherwise.
								public boolean keyDown(int keyCode);
							

On the following example, the method keyDown will determinate if the escape key (Keyboard.ESCAPE_KEY) is pressed or not. If it is, the game will be terminated.

Example: When escape key is pressed, terminate the game.

								package teclado001;

								import JPlay.GameImage;
								import JPlay.Keyboard;
								import JPlay.Window;

								/**
								 * @author Gefersom Cardoso Lima
								 * Universidade Federal Fluminense - UFF - Brasil - 2010
								 * Ciência da Computação
								 */

								public class teclado001
								{
									//When escape key is pressed, terminate the game.
									public static void main(String[] args)
									{
										Window janela = new Window(800,600);
										Keyboard keyboard = janela.getKeyboard();
										GameImage backGround = new GameImage("fundo.png");

										boolean executando = true;
										while(executando)
										{
												backGround.draw();
												janela.display();

												//Return false otherwise
												if (keyboard.keyDown(Keyboard.ESCAPE_KEY) )
													executando = false;
										}

										//Close the window, and finish the game
										janela.exit();
									}
								}
							
							

Agora que o método keyDown foi explicado, podemos detalhar os dois comportamentos que as teclas podem assumir:

Now that keyDown method has been explained, we shall detail two behaviors that keys may assume:

DETECT_EVERY_PRESS - in each iteration of the loop the keyDown() method of the keyboard will return true if the key is pressed, in other words, returns true while the key is pressed.

DETECT_INITIAL_PRESS_ONLY – if the key is has this behavior, the method keyDown() will just return true once, when the key is pressed, differently from DETECT_EVERY_PRESS, that will return true while the key is being pressed. This means that keyDown() method's behavior will return true again if the key is released and pressed again.

The behavior of DETECT_EVERY_PRESS can be used to determinate a movement of a character, since that to make him move it is necessary to maintain a certain key pressed. The DETECT_INITAL_PRESS_ONLY could be used to make a character or a ship shoot just once, forcing the player to release the key and press it again to shoot.

3 - Adding keys

To add a key, different from the ones provided by the Keyboard class, it is necessary to know its code. To do it, you should use KeyEvent class, that is present in Java. It has the codes for all the keys.

To access the key's codes type ' KeyEvent.VK_ '.

To add a key, use the following methods of the Keyboard class:

 
								void addKey(int  keyCode);
								//or
								void addKey(int keyCode, int behavior);
							

In void addKey(int keyCode, int behavior) the parameters are the key's code that you want to add and the behavior of the key.

Example: add the control key to the JPlay's keyboard.

 teclado.addKey( KeyEvent. VK_CONTROL); 

Using the method addKey(int keyCode) we add a key and its behavior will be DETECT_INITIAL_PRESS_ONLY.

If you want the DETECT_EVERY_PRESS behavior, use the method addKey(int keyCode, int behavior) like this:

 teclado.addKey(KeyEvent.VK_CONTROL, Keyboard.DETECT_EVERY_PRESS). 

Ps.: If you've done an attempt to add an existing key, it will be replaced by the one that had been added, so, there's a possibility that the new key has a different behavior comparing to the one before that.

4 - Behavior of the default keys

The keys UP_KEY, LEFT_KEY, RIGHT_KEY e DOWN_KEY has a DETECT_EVERY_PRESS. behaviour.

The keys ESCAPE_KEY, SPACE_KEY e ENTER_KEY has a DETECT_INITAL_PRESS_ONLY. behavior.

5 - Changing a key's behavior

To change a key's behavior use the method below of JPlay's Keyboard class:

void setBehavior(int key, int behavior);

Example: Changing UP_KEY's behavior:

teclado.setBehavior(Keyboard.UP_KEY, Keyboard.DETECT_INITIAL_PRESS_ONLY); 

The parameters are: the key's code and the new behavior.

 

6 - Removing a key

To remove a key of JPlay's keyboard you should use the method:

void removeKey(int keyCode);

Evample: Add a G key that will be used to terminate the game, and removes the escape key.

								package teclado002;

								import JPlay.GameImage;
								import JPlay.Keyboard;
								import JPlay.Window;
								import java.awt.event.KeyEvent;

								/**
								 * @author Gefersom Cardoso Lima
								 * Universidade Federal Fluminense - UFF - Brasil - 2010
								 * Ciência da Computação
								 */

								public class teclado002
								{
									//Adds a key to the keyboard with the DETECT_INITIAL_PRESS_ONLY behavior
									public static void main(String[] args)
									{
										Window janela = new Window(800,600);
										Keyboard keyboard = janela.getKeyboard();
										GameImage backGround = new GameImage("fundo.png");

										//Adds a G key with DETECT_INITIAL_PRESS_ONLY behavior
										keyboard.addKey(KeyEvent.VK_G);

										//Adds an escape key to the keyboard
										keyboard.removeKey(KeyEvent.VK_ESCAPE);

										boolean executando = true;
										while(executando)
										{
												backGround.draw();
												janela.display();
												if ( keyboard.keyDown(KeyEvent.VK_G) )
													executando = false;
										}
										janela.exit();
									}
								}
							

Ps:

The following keys are the same, in other words, a key's code that represents:

Keyboard.UP_KEY = KeyEvent.VK_UP
Keyboard.DOWN_KEY = KeyEvent.VK_DOWN

Keyboard.LEFT_KEY = KeyEvent.VK_LEFT

Keyboard.RIGHT_KEY = KeyEvent.VK_RIGHT

Keyboard.ESCAPE_KEY = KeyEvent.VK_ESCAPE

Keyboard.SPACE_KEY = KeyEvent.VK_SPACE

Keyboard.ENTER_KEY = KeyEvent.VK_ENTER