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

When using these functions in an application, it is possible that the user may enter
characters that we are then unable to process or display; this should be kept in
mind, as generic string input may not always be a good choice (for example, you
may be unable to display every possible character that can be entered using your
game's font!).
Using this API will also likely break the look and feel of the game as its super whizzy
UI is suddenly overlaid or replaced by a drab and boring system dialog.
These reasons, combined with the fact that it is not supported by all platforms, may
mean that it is a better decision to implement our own in-game string entry routines.
That being said, it is still a useful API to know about, if only for debugging purposes.
Detecting touch screen and pointer input
There aren't many devices released these days that don't feature a touch screen.
Most new devices have adopted this as the primary input method and have dropped
physical buttons almost entirely.
In Marmalade we detect touch screen events using the s3ePointer API, which I
have to admit is perhaps not the most obvious name for an API that handles touch
screen input. To use this API in our own program we just need to include the
s3ePointer.h file.
The reason for this slightly bizarre naming is that when this API was first
developed, touch screens were not commonplace. Instead, some devices had little
joystick-style nubs that were able to move a pointer around the screen, much like
a mouse on a computer.
Due to the fact that touch screen input is primarily concerned with a screen
coordinate and that it was unlikely that a device would arrive that had both
touch screen and pointer inputs, the Marmalade SDK simply adapted the existing
s3ePointer API to accommodate touch screens as well, since your finger or stylus is
effectively a pointer anyway.
For the purpose of this chapter, whenever we talk about a position being "pointed
at", we mean either an on-screen cursor has been moved to that position or a touch
screen has had a contact made at that position. Positions are always returned as
pixel positions relative to the top-left corner of the screen, as shown in the following
diagram that shows what to expect on a device with a portrait HVGA screen size,
such as a non-retina display iPhone: