iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKLabelNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKLabelNode

An SKLabelNode is a node that draws a string.

Just about every game needs to display text at some point, even if it is just to display “Game Over” to the player. If you had to implement this yourself in OpenGL, it would take a fair amount of work to get it correct. But the SKLabelNode class does all of the work necessary to load fonts and create text for display.

To use a label node, create a new label node by calling the labelNodeWithFontNamed: class method. Then configure the other label properties, especially the text property. The size of a label node is determined implicitly by the label node’s fontName, fontSize, and text properties.

By default, the text label is centered horizontally on the label node’s origin, with the font’s baseline passing through the origin. The verticalAlignmentMode and horizontalAlignmentMode properties can be used to adjust the label’s position relative to the origin.

Adding a text label demonstrates how to create a new text label.

Listing 1Adding a text label
  1. SKLabelNode *winner = [SKLabelNode labelNodeWithFontNamed:@"Chalkduster"];
  2. winner.text = @"You Win!";
  3. winner.fontSize = 65;
  4. winner.fontColor = [SKColor greenColor];
  5. winner.position = CGPointMake(CGRectGetMidX(self.bounds),
  6. CGRectGetMidY(self.bounds));
  7. [self addChild:winner];

Whenever you change the label node’s properties, the label node is automatically updated the next time the scene is rendered.

  • Initializes a new label object.

    Declaration

    Swift

    init(fontNamed fontName: String?)

    Objective-C

    - (instancetype _Nonnull)initWithFontNamed:(NSString * _Nullable)fontName

    Parameters

    fontName

    The name of the font used by the label.

    Return Value

    An initialized label object.

    Availability

    Available in iOS 7.0 and later.

  • Creates a new label object.

    Declaration

    Objective-C

    + (instancetype _Nonnull)labelNodeWithFontNamed:(NSString * _Nullable)fontName

    Parameters

    fontName

    The name of the font used by the label.

    Return Value

    A new initialized label object.

    Availability

    Available in iOS 7.0 and later.

  • Creates a new label object with some initial text.

    Declaration

    Swift

    convenience init(text text: String?)

    Objective-C

    + (instancetype _Nonnull)labelNodeWithText:(NSString * _Nullable)text

    Parameters

    text

    The text to use to initialize the label node.

    Return Value

    A new initialized label object.

    Discussion

    The label node’s font is set to Helvetica Neue Ultralight, 32 point.

    Availability

    Available in iOS 8.0 and later.

  • text text Property

    The string that the label node displays.

    Declaration

    Swift

    var text: String?

    Objective-C

    @property(nonatomic, copy) NSString * _Nullable text

    Availability

    Available in iOS 7.0 and later.

  • The color of the label.

    Declaration

    Swift

    var fontColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor * _Nullable fontColor

    Discussion

    The default color is white.

    Availability

    Available in iOS 7.0 and later.

  • The font used for the text in the label.

    Declaration

    Swift

    var fontName: String?

    Objective-C

    @property(nonatomic, copy) NSString * _Nullable fontName

    Availability

    Available in iOS 7.0 and later.

  • The size of the font used in the label.

    Declaration

    Swift

    var fontSize: CGFloat

    Objective-C

    @property(nonatomic) CGFloat fontSize

    Discussion

    The default font size is 32 points.

    Availability

    Available in iOS 7.0 and later.

  • The label’s blend color.

    Declaration

    Swift

    var color: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor * _Nullable color

    Availability

    Available in iOS 7.0 and later.

    See Also

    colorBlendFactor

  • A floating-point value that describes how the color is blended with the font color.

    Declaration

    Swift

    var colorBlendFactor: CGFloat

    Objective-C

    @property(nonatomic) CGFloat colorBlendFactor

    Discussion

    The value must be a number between 0.0 and 1.0, inclusive. The default value (0.0) indicates that the color property is ignored and that the label’s font color should be used unmodified. For values greater than 0.0, the font color is blended first with the blend color.

    Availability

    Available in iOS 7.0 and later.

    See Also

    color

  • Options for aligning text vertically.

    Declaration

    Swift

    enum SKLabelVerticalAlignmentMode : Int { case Baseline case Center case Top case Bottom }

    Objective-C

    typedef SKLabelVerticalAlignmentMode : NSInteger { SKLabelVerticalAlignmentModeBaseline, SKLabelVerticalAlignmentModeCenter, SKLabelVerticalAlignmentModeTop, SKLabelVerticalAlignmentModeBottom, } SKLabelVerticalAlignmentMode;

    Constants

    • Baseline

      SKLabelVerticalAlignmentModeBaseline

      Positions the text so that the font’s baseline lies on the node’s origin.

      Available in iOS 7.0 and later.

    • Center

      SKLabelVerticalAlignmentModeCenter

      Centers the text vertically on the node’s origin.

      Available in iOS 7.0 and later.

    • Top

      SKLabelVerticalAlignmentModeTop

      Positions the text so that the top of the text is on the node’s origin.

      Available in iOS 7.0 and later.

    • Bottom

      SKLabelVerticalAlignmentModeBottom

      Positions the text so that the bottom of the text is on the node’s origin.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Options for aligning text horizontally.

    Declaration

    Swift

    enum SKLabelHorizontalAlignmentMode : Int { case Center case Left case Right }

    Objective-C

    typedef SKLabelHorizontalAlignmentMode : NSInteger { SKLabelHorizontalAlignmentModeCenter, SKLabelHorizontalAlignmentModeLeft, SKLabelHorizontalAlignmentModeRight, } SKLabelHorizontalAlignmentMode;

    Constants

    • Center

      SKLabelHorizontalAlignmentModeCenter

      Centers the text horizontally on the node’s origin.

      Available in iOS 7.0 and later.

    • Left

      SKLabelHorizontalAlignmentModeLeft

      Positions the text so that the left side of the text is on the node’s origin.

      Available in iOS 7.0 and later.

    • Right

      SKLabelHorizontalAlignmentModeRight

      Positions the text so that the right side of the text is on the node’s origin.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.