CCLabelBMFont Class Reference

Inherits from CCNode : CCResponder : NSObject
Conforms to CCLabelProtocol
CCTextureProtocol
Declared in CCLabelBMFont.h

Overview

CCLabelBMFont is a label whose characters are drawn from a bitmap image.

The label is loaded from a fnt file created with an external editor with support for Cocos2D. For example Glyph Designer or bmGlyph.

Each character is internally represented by a CCSprite instance. You can access and modify the label’s sprites via the [CCNode children] property.

Drawbacks/Advantages

Advantages:

  • No penalty when label text changes.
  • Individual characters are sprites, can be modified individually (ie individual character animations).
  • Even using few labels may provide a memory usage advantage over CCLabelTTF, depending on size of bitmap font texture atlas and how many different fonts are used.

Drawbacks:

  • Visual quality suffers when scaling (aliasing, blurring).
  • Limited to characters in bitmap font atlas. Foreign language support means potentially having lots of additional Unicode characters, thus increasing the font texture size.

See the Developer Guide (Concepts: Nodes) for more details.

Usage Notes

The character sprites' anchorPoint is (0.5, 0.5) and should not be changed. It might affect the rendering.

Creating a Bitmap Font Label

+ labelWithString:fntFile:

Creates and returns a label object using the specified text and font file values.

+ (instancetype)labelWithString:(NSString *)string fntFile:(NSString *)fntFile

Parameters

string

Label text.
fntFile

Label font file.

Return Value

The CCLabelBMFont Object.

Declared In

CCLabelBMFont.h

+ labelWithString:fntFile:width:alignment:

Creates and returns a label object using the specified text, font file and alignment values.

+ (instancetype)labelWithString:(NSString *)string fntFile:(NSString *)fntFile width:(float)width alignment:(CCTextAlignment)alignment

Parameters

string

Label text.
fntFile

Label font file.
width

Label maximum width.
alignment

Horizontal text alignment.

Return Value

The CCLabelBMFont Object.

See Also

Declared In

CCLabelBMFont.h

+ labelWithString:fntFile:width:alignment:imageOffset:

Creates and returns a label object using the specified text, font file, alignment and image offset values.

+ (instancetype)labelWithString:(NSString *)string fntFile:(NSString *)fntFile width:(float)width alignment:(CCTextAlignment)alignment imageOffset:(CGPoint)offset

Parameters

string

Label text.
fntFile

Label font file.
width

Label maximum width.
alignment

Horizontal text alignment.
offset

Glyph offset on the font texture

Return Value

The CCLabelBMFont Object.

See Also

Declared In

CCLabelBMFont.h

– initWithString:fntFile:

Initializes and returns a label object using the specified text and font file values.

- (id)initWithString:(NSString *)string fntFile:(NSString *)fntFile

Parameters

string

Label text.
fntFile

Label font file.

Return Value

An initialized CCLabelBMFont Object.

Declared In

CCLabelBMFont.h

– initWithString:fntFile:width:alignment:

Initializes and returns a label object using the specified text, font file and alignment values.

- (id)initWithString:(NSString *)string fntFile:(NSString *)fntFile width:(float)width alignment:(CCTextAlignment)alignment

Parameters

string

Label text.
fntFile

Label font file.
width

Label maximum width.
alignment

Horizontal text alignment.

Return Value

An initialized CCLabelBMFont Object.

See Also

Declared In

CCLabelBMFont.h

– initWithString:fntFile:width:alignment:imageOffset:

Initializes and returns a label object using the specified text, font file, alignment and image offset values.

- (id)initWithString:(NSString *)string fntFile:(NSString *)fntFile width:(float)width alignment:(CCTextAlignment)alignment imageOffset:(CGPoint)offset

Parameters

string

Label text.
fntFile

Label font file.
width

Label maximum width.
alignment

Horizontal text alignment.
offset

Glyph offset on the font texture.

Return Value

An initialized CCLabelBMFont Object.

See Also

Declared In

CCLabelBMFont.h

Accessing Text Attributes

  alignment

The technique to use for horizontal aligning of the text.

@property (nonatomic, assign, readonly) CCTextAlignment alignment

See Also

Declared In

CCLabelBMFont.h

Size and Alignment

– setWidth:

Set the maximum width allowed before a line break will be inserted.

- (void)setWidth:(float)width

Parameters

width

The maximum width of a line.

Declared In

CCLabelBMFont.h

– setAlignment:

Set the horizontal alignment of the text.

- (void)setAlignment:(CCTextAlignment)alignment

Parameters

alignment

Horizontal alignment.

Declared In

CCLabelBMFont.h

Memory Management

+ purgeCachedData

Uncaches bitmap font configuration data and the atlas dictionary.

+ (void)purgeCachedData

Discussion

Note: The bulk of the cached memory will not be released instantly but rather after the last instance of CCLabelBMFont using a specific set of cached data has been deallocated.

Declared In

CCLabelBMFont.h