User Input - Marmalade SDK Mobile Game Development Essentials - page 65

In order for our program to keep receiving updates on key presses, we must call the
function s3eKeyboardUpdate in our code, once per game frame. The s3eKeyboard
API keeps its own internal cache of the current key press states, which is updated
when calling this function; so if we don't call s3eKeyboardUpdate frequently, we
risk missing key press events.

Detecting key state
The most useful method of key detection for most arcade style games is to be able
to discover the up or down state of any key on the device. The s3eKeyboard API
provides two ways in which we can do this, these being polling the current key
state and by registering a callback function.

Detecting key state changes using polling
We'll start with the simplest approach of polling for the current state of a key. It may
be the simplest approach, but in most cases it is also the best approach as far as game
coding is concerned, since often all we want to know is whether a key is currently
pressed or released so that we can update our game state accordingly.

To detect the current state of any key on our device we make a call to
s3eKeyboardGetState , which takes a value from the s3eKey enumeration (take a
look at the s3eKeyboard.h file for a full list, but you can normally guess the name of
the enumeration fairly easily—for example, s3eKeyUp is the up arrow key, s3eKey4
is the number 4 key, and so on) to identify the key we are interested in. The function
returns an integer value that is a bit mask representing the current state of that key.
The following key states can be detected by performing a bitwise AND operation on
the return value:

Bit mask name Description

S3E_KEY_STATE_DOWN The key is currently being held down.

S3E_KEY_STATE_PRESSED The key went from being up to down in the last

call to s3eKeyboardUpdate .

S3E_KEY_STATE_RELEASED The key went from being down to up in the last

call to s3eKeyboardUpdate .

If the value returned from the function is zero, then the key can be assumed to
currently be in the up position (that is, not being held) and has not just been
released either.