====== Displaying Text ======

{{:manual:textfields.png?150 }}

Displaying text is easy. The class SPTextField should be quite self explanatory. By default, it uses the system fonts of the iPhone.

<code objc>
SPTextField *textField = [SPTextField textFieldWithWidth:145 height:80 
    text:@"Text" fontName:@"Helvetica" fontSize:12.0f color:0xff0000];
textField.hAlign = SPHAlignRight;  // horizontal alignment
textField.vAlign = SPVAlignBottom; // vertical alignment
textField.border = YES;
</code>

===== System Fonts =====

Here is a list of fonts that are installed per default on any iOS version:

{{ :tutorials:iphone_fonts.png?640 |The default iOS fonts}}

<note tip>
You can include custom fonts with your project by including the UIAppFonts key (an array of strings with the FULL filename including the extension) in your Info.plist as noted [[https://developer.apple.com/library/ios/#releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html|here]].
</note>

Using system fonts like this is adequate for text that does not change very often. However, if your textfield constantly changes its contents, or if you want to display a fancy font that's not available on the iPhone, you should use a bitmap font instead. 

===== Bitmap Fonts =====

A bitmap font is a texture containing all the characters you want to display. The positions of the characters are defined in an XML document. This is all Sparrow needs to render a text. To create the necessary files, there are several options:

  * [[http://kvazars.com/littera/|Littera]] a full-featured free online bitmap font generator.
  * The AngelCode [[http://www.angelcode.com/products/bmfont/|Bitmap Font Generator]] for Windows contains all the basic functionality you need.
  * On OS X, we recommend [[http://glyphdesigner.71squared.com|Glyph Designer]] -- an excellent tool that allows you to add special effects to your fonts, as well.
  * Also exclusive for OS X: [[http://www.bmglyph.com|bmGlyph]], available on the Mac App Store.

Whatever tool you choose: after loading a font in that tool, export the font data as an XML file, and the texture in PNG format with white characters on a transparent background (32 bit). The result is a ".fnt" file and an associated image containing the characters.

{{ :manual:desyrel.png?nolink |}}

To use the bitmap font, just register it at SPTextField:

<code objc>
[SPTextField registerBitmapFontFromFile:@"bmp_font.fnt"];
</code>

After registering the font, it can be used just like any system font. Just assign the right "fontName" to your text field (look it up in the "face" attribute of the font XML). 

<code objc>
textField.fontName = "bitmap-font-name";
</code>

That's all you need to do! 

By the way: you can add the font PNG to your texture atlas, as well. Just use the following method for registering the font:

<code objc>
NSString *bmpFontName = [SPTextField registerBitmapFontFromFile:@"bmp_font.fnt"
    texture:[myAtlas textureByName:@"bmp_font"]];
</code>

That way, you save texture space and speed up the rendering.

-----

//Next section: [[Pivot Points]]//