Implementing Fonts, User Interfaces, and Localization - Marmalade SDK Mobile Game Development Essentials - page 168

Drawing text on screen
When we were looking at how to create a font resource, it was mentioned that a color
could be chosen for the font. It is recommended to choose white so we can change
the color of our text at runtime to any color we want. We change the color of the font
by modulating the font bitmap with our chosen color, so if the font bitmap is not
white this will not produce the desired color change.
We'll be seeing how to change the font color in a moment, but in order for font
coloring to work there is one quirk of IwGxFont that must be mentioned first.
When attempting to recolor a font at runtime, we must ensure
that emissive lighting is enabled using the function call
IwGxLightingEmissive(true) . IwGxFont affects the color
of a font by using the emissive lighting component, which will
not be applied if it is disabled.
With the note about lighting out of the way, the first step in rendering text is to
indicate which font we want to use to draw it. This is done by passing a pointer
to the relevant CIwGxFont instance into the function IwGxFontSetFont .
Next, we can set the color we want to use with IwGxFontSetCol . There are two
versions of this function, one that takes a reference to a const CIwColour instance,
and another that takes the color value as a uint32 value. When using the latter, bear
in mind that the color is specified as ABGR—that is, alpha in the most significant
byte, then blue, green, and red in the least significant byte.
We now need to indicate where on the screen we want the text to appear, which
we do by defining a rectangular area in which the text should appear. This is
specified by using a CIwRect instance that contains x and y values for the top
left of the rectangle, plus a width and height value. The function call we use is
IwGxFontSetRect .
Drawing the text is now possible using the IwGxFontDrawText function. The first
parameter is the string of text to print and is specified as a const CIwChar pointer.
CIwChar is just a typedef type for the standard C char type.
The default encoding for text is UTF-8. For text comprising of characters from the
ASCII set, this means we don't have to do anything to the text data at all.
The function also takes a second parameter, which is the length of the text to be
drawn. This has a default parameter value of -1 , which indicates the entire string
should be drawn. Any other value will draw the specified number of characters.
This is handy if you want to implement a system common in many games where
text appears on screen one character at a time.