Keyboard Events in Quorum

Handling Input with Events

In this tutorial, we will learn about using player input and the game engine's event system. With these tools, our games will be able to react to keyboard input.

The second method for getting player input is known as event handling. Event handling is a technique in which we designate code blocks that run whenever a specific event occurs, such as the mouse being clicked or a key being pressed. When we use event handling, we rely on the game engine to notify us when an event occurs by automatically calling certain predefined actions.

The Difference Between Polling and Event Handling

Most games, especially large games, use event handling instead of polling to detect input. To understand why, it’s helpful to think of an analogy for how the two approaches work.

Consider the situation where you want to get a book from the library, but it is currently checked out. One approach (polling) is to call the library once every hour and ask the librarian if the book has been returned yet. The other approach (event handling) is to register your request with the librarian and respond when you are notified that the book is available.

From this example, you can see that event handling is much more efficient than input polling, because it doesn’t waste time repeatedly checking. There are cases where it isn't noticeable which approach you use and others where it is necessary to poll, but the event handling approach should generally be preferred.

Using KeyboardEvents

To see how events can be used for keyboard input, we will use another sample program. This program will play a sound when the space bar is pressed, and a different sound when it is released. We will use the same audio files in the previous sample, or you can use your own.

Our code for this sample uses two classes, which are each in a separate file. Let's start by looking at the Soundboard class.

use Libraries.Interface.Events.KeyboardListener
use Libraries.Interface.Events.KeyboardEvent
use Libraries.Sound.Audio

class Soundboard is KeyboardListener
   Audio pressedSound
   Audio releasedSound

   on create
       // We load our sounds when this object is created.
       pressedSound:Load("AudioFiles/lightSound.wav")
       releasedSound:Load("AudioFiles/heavySound.wav")
   end

   // This action will be called when any keyboard key is pressed.
   action PressedKey(KeyboardEvent event)
   if event:keyCode = event:SPACE
       pressedSound:Play()
   end
end
   // This action will be called when any keyboard key is released.
   action ReleasedKey(KeyboardEvent event)
       if event:keyCode = event:SPACE
           releasedSound:Play()
       end
   end

end

An important thing to note about this code is in the first line (the class definition) where we specify that the class is a KeyboardListener ( class Soundboard is KeyboardListener ). By inheriting from the KeyboardListener class, our class gets special actions that can "listen" for KeyboardEvents. This gives us certain action definitions that the engine will automatically call when a keyboard event occurs. If we choose to listen and respond to an event we simply put our actions inside these actions.

In any class that inherits from KeyboardListener, the PressedKey action will be called automatically by the engine when the user presses a key on the keyboard. The PressedKey action must take a KeyboardEvent as a parameter which is passed by the engine. This KeyboardEvent contains a field keyCode that represents what key was pressed. A KeyboardEvent also contains values representing all possible supported keys on a keyboard, which we use in our example to make sure that the key that was pressed is the space bar. We can choose to listen to whichever events we want to and respond to whichever keys we specify. If a key is pressed that we don't respond to, the event is ignored by our code.

action PressedKey(KeyboardEvent event)
   if event:keyCode = event:SPACE
      pressedSound:Play()
   end
end

In any class that inherits from KeyboardListener, the ReleasedKey action will be called automatically by the engine when the user releases a key on the keyboard. Let’s start by looking at the Soundboard class.Like the PressedKey action, this action must take a KeyboardEvent as a parameter which will provide the information on which key was released.

action ReleasedKey(KeyboardEvent event)
   if event:keyCode = event:SPACE
      releasedSound:Play()
   end
end

With this class ready to receive KeyboardEvents, we can set up our Main class as follows:

use Libraries.Game.Game

class Main is Game
   // We create a object using our Soundboard listener class.
   Soundboard board

   action Main
       StartGame()
   end

   action CreateGame
       // We add the listener to our game.  This has the effect of letting the engine know 
       //that the Soundboard object should be notified of keyboard events.
       AddKeyboardListener(board)
   end

   action Update(number seconds)
   end
end

The most important addition to the Main class is AddKeyboardListener(board) . This action tells the game engine that our Soundboard object is ready to start receiving KeyboardEvents. Now our program will "get"events from the keyboard (meaning that the engine will call the actions we specified in the Soundboard class when events occur).

Next Tutorial

In the next tutorial, we will discuss Mouse Events in Quorum, which describes How to use mouse events events in our games..