Inherits from SPDisplayObjectContainer : SPDisplayObject : SPEventDispatcher : NSObject
Declared in SPTextField.h

Overview

An SPTextField displays text, either using standard iOS fonts or a custom bitmap font.

You can set all properties you are used to, like the font name and size, a color, the horizontal and vertical alignment, etc. The border property is helpful during development, because it lets you see the bounds of the textfield.

There are two types of fonts that can be displayed:

  • Standard iOS fonts. This renders the text with standard iOS fonts like Verdana or Arial. Use this method if you want to keep it simple, and if the text changes not too often. Simply pass the font name to the corresponding property.
  • Bitmap fonts. If you need speed or fancy font effects, use a bitmap font instead. That is a font that has its glyphs rendered to a texture atlas. To use it, first register the font with the method registerBitmapFont:, and then pass the font name to the corresponding property of the text field.

For the latter, we recommend one of the following tools; both support Sparrow natively.

Alternatively, you can use the Bitmap Font Generator from Angel Code, which is a free tool for Windows. Export the font data as an XML file and the texture as a png with white characters on a transparent background (32 bit).

Here is a sample with a standard font:

SPTextField *textField = [SPTextField textFieldWithWidth:300 height:100 text:@"Hello world!"];
textField.hAlign = SPHAlignCenter;
textField.vAlign = SPVAlignCenter;
textField.fontSize = 18;
textField.fontName = @"Georgia-Bold";

And now we use a bitmap font:

// Register the font; the returned font name is the one that is defined in the font XML.
NSString *fontName = [SPTextField registerBitmapFontFromFile:@"bitmap_font.fnt"]; 

SPTextField *textField = [SPTextField textFieldWithWidth:300 height:100 text:@"Hello world!"];
textField.fontName = fontName;

Tip: Sparrow comes with a small bitmap font that is great for debug output. Just assign the font name SPBitmapFontMiniName to a text field to use it.

Tasks

Initialization

Methods

Properties

  •   text

    The displayed text.

         property
  •   fontName

    The name of the font.

         property
  •   fontSize

    The size of the font. For bitmap fonts, use SPNativeFontSize for the original size.

         property
  •   hAlign

    The horizontal alignment of the text.

         property
  •   vAlign

    The vertical alignment of the text.

         property
  •   border

    Allows displaying a border around the edges of the text field. Useful for visual debugging.

         property
  •   color

    The color of the text.

         property
  •   textBounds

    The bounds of the actual characters inside the text field.

         property
  •   kerning

    Allows using kerning information with a bitmap font (where available). Default is YES.

         property
  •   autoScale

    Indicates whether the font size is scaled down so that the complete text fits into the text field. Default is NO.

         property

Properties

autoScale

Indicates whether the font size is scaled down so that the complete text fits into the text field. Default is NO.

@property (nonatomic, assign) BOOL autoScale

Discussion

Indicates whether the font size is scaled down so that the complete text fits into the text field. Default is NO.

Declared In

SPTextField.h

border

Allows displaying a border around the edges of the text field. Useful for visual debugging.

@property (nonatomic, assign) BOOL border

Discussion

Allows displaying a border around the edges of the text field. Useful for visual debugging.

Declared In

SPTextField.h

color

The color of the text.

@property (nonatomic, assign) uint color

Discussion

The color of the text.

Declared In

SPTextField.h

fontName

The name of the font.

@property (nonatomic, copy) NSString *fontName

Discussion

The name of the font.

Declared In

SPTextField.h

fontSize

The size of the font. For bitmap fonts, use SPNativeFontSize for the original size.

@property (nonatomic, assign) float fontSize

Discussion

The size of the font. For bitmap fonts, use SPNativeFontSize for the original size.

Declared In

SPTextField.h

hAlign

The horizontal alignment of the text.

@property (nonatomic, assign) SPHAlign hAlign

Discussion

The horizontal alignment of the text.

Declared In

SPTextField.h

kerning

Allows using kerning information with a bitmap font (where available). Default is YES.

@property (nonatomic, assign) BOOL kerning

Discussion

Allows using kerning information with a bitmap font (where available). Default is YES.

Declared In

SPTextField.h

text

The displayed text.

@property (nonatomic, copy) NSString *text

Discussion

The displayed text.

Declared In

SPTextField.h

textBounds

The bounds of the actual characters inside the text field.

@property (weak, nonatomic, readonly) SPRectangle *textBounds

Discussion

The bounds of the actual characters inside the text field.

Declared In

SPTextField.h

vAlign

The vertical alignment of the text.

@property (nonatomic, assign) SPVAlign vAlign

Discussion

The vertical alignment of the text.

Declared In

SPTextField.h

Class Methods

registerBitmapFont:

Makes a bitmap font available at any text field, using texture and name as defined in the file.

+ (NSString *)registerBitmapFont:(SPBitmapFont *)font

Return Value

The name of the font as defined in the font XML.

Discussion

Makes a bitmap font available at any text field, using texture and name as defined in the file.

Declared In

SPTextField.h

registerBitmapFont:name:

Makes a bitmap font available at any text field, using the texture defined in the file and manually providing the font name.

+ (NSString *)registerBitmapFont:(SPBitmapFont *)font name:(NSString *)fontName

Return Value

The name of the font that was passed to the method.

Discussion

Makes a bitmap font available at any text field, using the texture defined in the file and manually providing the font name.

Declared In

SPTextField.h

registerBitmapFontFromFile:

Makes a bitmap font available at any text field, using texture and name as defined in the file.

+ (NSString *)registerBitmapFontFromFile:(NSString *)path

Return Value

The name of the font as defined in the font XML.

Discussion

Makes a bitmap font available at any text field, using texture and name as defined in the file.

Declared In

SPTextField.h

registerBitmapFontFromFile:texture:

Makes a bitmap font available at any text field, using a custom texture.

+ (NSString *)registerBitmapFontFromFile:(NSString *)path texture:(SPTexture *)texture

Return Value

The name of the font as defined in the font XML.

Discussion

Makes a bitmap font available at any text field, using a custom texture.

Declared In

SPTextField.h

registerBitmapFontFromFile:texture:name:

Makes a bitmap font available at any text field, using a custom texture and font name.

+ (NSString *)registerBitmapFontFromFile:(NSString *)path texture:(SPTexture *)texture name:(NSString *)fontName

Discussion

Makes a bitmap font available at any text field, using a custom texture and font name.

@retrurn The name of the font that was passed to the method.

Declared In

SPTextField.h

registeredBitmapFont:

Get the bitmap font that was registered under a certain name.

+ (SPBitmapFont *)registeredBitmapFont:(NSString *)name

Discussion

Get the bitmap font that was registered under a certain name.

Declared In

SPTextField.h

textFieldWithText:

Factory method.

+ (instancetype)textFieldWithText:(NSString *)text

Discussion

Factory method.

Declared In

SPTextField.h

textFieldWithWidth:height:text:

Factory method.

+ (instancetype)textFieldWithWidth:(float)width height:(float)height text:(NSString *)text

Discussion

Factory method.

Declared In

SPTextField.h

textFieldWithWidth:height:text:fontName:fontSize:color:

Factory method.

+ (instancetype)textFieldWithWidth:(float)width height:(float)height text:(NSString *)text fontName:(NSString *)name fontSize:(float)size color:(uint)color

Discussion

Factory method.

Declared In

SPTextField.h

unregisterBitmapFont:

Unregisters the bitmap font of this name.

+ (void)unregisterBitmapFont:(NSString *)name

Discussion

Unregisters the bitmap font of this name.

Declared In

SPTextField.h

Instance Methods

initWithText:

Initialize a 128x128 textField (Helvetica, 14pt, black).

- (instancetype)initWithText:(NSString *)text

Discussion

Initialize a 128x128 textField (Helvetica, 14pt, black).

Declared In

SPTextField.h

initWithWidth:height:

Initialize a text field with default settings (Helvetica, 14pt, black) and an empty string.

- (instancetype)initWithWidth:(float)width height:(float)height

Discussion

Initialize a text field with default settings (Helvetica, 14pt, black) and an empty string.

Declared In

SPTextField.h

initWithWidth:height:text:

Initialize a text field with default settings (Helvetica, 14pt, black).

- (instancetype)initWithWidth:(float)width height:(float)height text:(NSString *)text

Discussion

Initialize a text field with default settings (Helvetica, 14pt, black).

Declared In

SPTextField.h

initWithWidth:height:text:fontName:fontSize:color:

Initialize a text field with all important font properties. Designated Initializer.

- (instancetype)initWithWidth:(float)width height:(float)height text:(NSString *)text fontName:(NSString *)name fontSize:(float)size color:(uint)color

Discussion

Initialize a text field with all important font properties. Designated Initializer.

Declared In

SPTextField.h