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

Detecting character code input using polling
To find out if a key that generates a character code has been pressed, all we have to
do is call the following function:
s3eWChar lCharCode = s3eKeyboardGetChar();
The s3eWChar type is just an alternate type definition for the standard C++ type
wchar_t , a wide character. While this type can vary in size, it is assumed to be a
16-bit value in Marmalade. When a key is pressed, its character code will be added
to the back of a queue. Calling this function will return the character to the front of
the queue, or S3E_WEOF if the queue is empty. We often call this function in a loop
in order to try and keep the queue empty and not risk losing key presses.
The character codes returned will depend on the device you are running on, but in
most cases the standard alphabet A through Z, numbers, and punctuation characters
will be ASCII codes, just stored in a 16-bit value.
Detecting character code input using callbacks
Using the callback method of receiving character codes takes the same approach as
the callback method for receiving key state changes.
We again use s3eKeyboardRegister and s3eKeyboardUnRegister to start and
stop notifications from occurring, but we use the enumeration value S3E_KEYBOARD_
CHAR_EVENT to indicate that it is a character code event we want to receive.
The callback function we provide will now be sent a pointer to an
s3eKeyboardCharEvent structure that contains a single member of type s3eWChar
named m_Char . This member will contain the character code that was generated by
the user.
Character code input is really only recommended if you are running
on a device with a physical keyboard, as using virtual keyboards on
touch screen devices can be unreliable with many key presses going
unnoticed, particularly when characters outside the normal ASCII
character set are entered (for example, Chinese or Japanese text entry).
Inputting strings
We've already seen how we can use the s3eKeyboard functionality to read character
codes, but if we want to allow the user to enter a string and we don't mind our
program forsaking its own user interface in favor of a standard modal string entry
dialog, then we have a shortcut available to us.