UILabel Class Reference

Inherits from
UIView : UIResponder : NSObject
Conforms to
NSCoding
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Text, Web, and Editing Programming Guide for iOS
Declared in
UILabel.h
Related sample code

Overview

The UILabel class implements a read-only text view. You can use this class to draw one or multiple lines of static text, such as those you might use to identify other parts of your user interface. The base UILabel class provides support for both simple and complex styling of the label text. You can also control over aspects of appearance, such as whether the label uses a shadow or draws with a highlight. If needed, you can customize the appearance of your text further by subclassing.

The default content mode of the UILabel class is UIViewContentModeRedraw. This mode causes the view to redraw its contents every time its bounding rectangle changes. You can change this mode by modifying the inherited contentMode property of the class.

New label objects are configured to disregard user events by default. If you want to handle events in a custom subclass of UILabel, you must explicitly change the value of the userInteractionEnabled property to YES after initializing the object.

For information about basic view behaviors, see View Programming Guide for iOS.

Tasks

Accessing the Text Attributes

Sizing the Label’s Text

Managing Highlight Values

Drawing a Shadow

Drawing and Positioning Overrides

Setting and Getting Attributes

Getting the Layout Constraints

Properties

adjustsFontSizeToFitWidth

A Boolean value indicating whether the font size should be reduced in order to fit the title string into the label’s bounding rectangle.

@property(nonatomic) BOOL adjustsFontSizeToFitWidth
Discussion

Normally, the label text is drawn with the font you specify in the font property. If this property is set to YES, however, and the text in the text property exceeds the label’s bounding rectangle, the receiver starts reducing the font size until the string fits or the minimum font size is reached. This property is effective only when the numberOfLines property is set to 1.

The default value for this property is NO. If you change it to YES, you should also set an appropriate minimum font size by modifying the minimumFontSize property.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UILabel.h

adjustsLetterSpacingToFitWidth

A Boolean value indicating whether spacing between letters should be adjusted to fit the string within the label’s bounds rectangle.

@property(nonatomic) BOOL adjustsLetterSpacingToFitWidth
Discussion

When this property is YES, the label may alter the letter spacing of the label text to make that text fit better within the label’s bounds. This property is applied to the string regardless of the current line break mode. The default value of this property is NO.

If the value of this property to YES, the label to ignore values value returned by the tighteningFactorForTruncation method of any NSParagraphStyle objects associated with the label text.

Availability
  • Available in iOS 6.0 and later.
Declared In
UILabel.h

attributedText

The styled text displayed by the label.

@property(nonatomic,copy) NSAttributedString *attributedText
Discussion

This property is nil by default. Assigning a new value to this property also replaces the value of the text property with the same string data, albeit without any formatting information. In addition, assigning a new a value updates the values in the font, textColor, and other style-related properties so that they reflect the style information starting at location 0 in the attributed string.

Availability
  • Available in iOS 6.0 and later.
Declared In
UILabel.h

baselineAdjustment

Controls how text baselines are adjusted when text needs to shrink to fit in the label.

@property(nonatomic) UIBaselineAdjustment baselineAdjustment
Discussion

If the adjustsFontSizeToFitWidth property is set to YES, this property controls the behavior of the text baselines in situations where adjustment of the font size is required. The default value of this property is UIBaselineAdjustmentAlignBaselines. This property is effective only when the numberOfLines property is set to 1.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UILabel.h

enabled

The enabled state to use when drawing the label’s text.

@property(nonatomic, getter=isEnabled) BOOL enabled
Discussion

This property determines only how the label is drawn. Disabled text is dimmed somewhat to indicate it is not active. This property is set to YES by default.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UILabel.h

font

The font of the text.

@property(nonatomic, retain) UIFont *font
Discussion

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the font to be applied to the entirety of the string in the attributedText property. If you want to apply the font to only a portion of the text, create a new attributed string with the desired style information and associate it with the label. If you are not using styled text, this property applies to the entire text string in the text property.

The default value for this property is the system font at a size of 17 points (using the systemFontOfSize: class method of UIFont). The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UILabel.h

highlighted

A Boolean value indicating whether the receiver should be drawn with a highlight.

@property(nonatomic, getter=isHighlighted) BOOL highlighted
Discussion

Setting this property causes the receiver to redraw with the appropriate highlight state. A subclass implementing a text button might set this property to YES when the user presses the button and set it to NO at other times. In order for the highlight to be drawn, the highlightedTextColor property must contain a non-nil value.

The default value of this property is NO.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UILabel.h

highlightedTextColor

The highlight color applied to the label’s text.

@property(nonatomic, retain) UIColor *highlightedTextColor
Discussion

Subclasses that use labels to implement a type of text button can use the value in this property when drawing the pressed state for the button. This color is applied to the label automatically whenever the highlighted property is set to YES.

The default value of this property is nil .

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UILabel.h

lineBreakMode

The technique to use for wrapping and truncating the label’s text.

@property(nonatomic) NSLineBreakMode lineBreakMode
Discussion

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the line break mode to be applied to the entirety of the string in the attributedText property. If you want to apply the line break mode to only a portion of the text, create a new attributed string with the desired style information and associate it with the label. If you are not using styled text, this property applies to the entire text string in the text property.

This property is in effect both during normal drawing and in cases where the font size must be reduced to fit the label’s text in its bounding box. This property is set to NSLineBreakByTruncatingTail by default.

Special Considerations

In iOS 5 and earlier, the type of this property was UILineBreakMode.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UILabel.h

minimumScaleFactor

The minimum scale factor supported for the label’s text.

@property(nonatomic) CGFloat minimumScaleFactor
Discussion

Use this property to specify the smallest multiplier for the current font size that yields an acceptable font size to use when displaying the label’s text. If you specify a value of 0 for this property, the current font size is used as the smallest font size.

The default value of this property is 0.

Availability
  • Available in iOS 6.0 and later.
Declared In
UILabel.h

numberOfLines

The maximum number of lines to use for rendering text.

@property(nonatomic) NSInteger numberOfLines
Discussion

This property controls the maximum number of lines to use in order to fit the label’s text into its bounding rectangle. The default value for this property is 1. To remove any maximum limit, and use as many lines as needed, set the value of this property to 0.

If you constrain your text using this property, any text that does not fit within the maximum number of lines and inside the bounding rectangle of the label is truncated using the appropriate line break mode.

When the receiver is resized using the sizeToFit method, resizing takes into account the value stored in this property. For example, if this property is set to 3, the sizeToFit method resizes the receiver so that it is big enough to display three lines of text.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UILabel.h

preferredMaxLayoutWidth

The preferred maximum width (in points) for a multiline label.

@property(nonatomic) CGFloat preferredMaxLayoutWidth
Discussion

This property affects the size of the label when layout constraints are applied to it. During layout, if the text extends beyond the width specified by this property, the additional text is flowed to one or more new lines, thereby increasing the height of the label.

Availability
  • Available in iOS 6.0 and later.
Declared In
UILabel.h

shadowColor

The shadow color of the text.

@property(nonatomic, retain) UIColor *shadowColor
Discussion

The default value for this property is nil, which indicates that no shadow is drawn. In addition to this property, you may also want to change the default shadow offset by modifying the shadowOffset property. Text shadows are drawn with the specified offset and color and no blurring.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UILabel.h

shadowOffset

The shadow offset (measured in points) for the text.

@property(nonatomic) CGSize shadowOffset
Discussion

The shadow color must be non-nil for this property to have any effect. The default offset size is (0, -1), which indicates a shadow one point above the text. Text shadows are drawn with the specified offset and color and no blurring.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UILabel.h

text

The text displayed by the label.

@property(nonatomic, copy) NSString *text
Discussion

This string is nil by default.

In iOS 6 and later, assigning a new value to this property also replaces the value of the attributedText property with the same text, albeit without any inherent style attributes. Instead the label styles the new string using the shadowColor, textAlignment, and other style-related properties of the class.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UILabel.h

textAlignment

The technique to use for aligning the text.

@property(nonatomic) NSTextAlignment textAlignment
Discussion

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the text alignment to be applied to the entirety of the string in the attributedText property. If you want to apply the alignment to only a portion of the text, create a new attributed string with the desired style information and associate it with the label. If you are not using styled text, this property applies to the entire text string in the text property.

The default value of this property is NSTextAlignmentLeft.

Special Considerations

In iOS 5 and earlier, the type of this property was UITextAlignment.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UILabel.h

textColor

The color of the text.

@property(nonatomic, retain) UIColor *textColor
Discussion

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the color to be applied to the entirety of the string in the attributedText property. If you want to apply the color to only a portion of the text, create a new attributed string with the desired style information and associate it with the label. If you are not using styled text, this property applies to the entire text string in the text property.

The default value for this property is a black color (set through the blackColor class method of UIColor). The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UILabel.h

userInteractionEnabled

A Boolean value that determines whether user events are ignored and removed from the event queue.

@property(nonatomic, getter=isUserInteractionEnabled) BOOL userInteractionEnabled
Discussion

This property is inherited from the UIView parent class. This class changes the default value of this property to NO.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UILabel.h

Instance Methods

drawTextInRect:

Draws the receiver’s text (or its shadow) in the specified rectangle.

- (void)drawTextInRect:(CGRect)rect
Parameters
rect

The rectangle in which to draw the text.

Discussion

You should not call this method directly. This method should only be overridden by subclasses that want to modify the default drawing behavior for the label’s text.

By the time this method is called, the current graphics context is already configured with the default environment and text color for drawing. In your overridden method, you can configure the current context further and then invoke super to do the actual drawing or you can do the drawing yourself. If you do render the text yourself, you should not invoke super.

Availability
  • Available in iOS 2.0 and later.
Declared In
UILabel.h

textRectForBounds:limitedToNumberOfLines:

Returns the drawing rectangle for the label’s text.

- (CGRect)textRectForBounds:(CGRect)bounds limitedToNumberOfLines:(NSInteger)numberOfLines
Parameters
bounds

The bounding rectangle of the receiver.

numberOfLines

The maximum number of lines to use for the label. The value 0 indicates there is no maximum number of lines and that the rectangle should encompass all of the text.

Return Value

The computed drawing rectangle for the label’s text.

Discussion

You should not call this method directly. This method should only be overridden by subclasses that want to change the receiver’s bounding rectangle before performing any other computations. Use the value in the numberOfLines parameter to limit the height of the returned rectangle to the specified number of lines of text. For this method to be called, there must be a prior call to the sizeToFit or sizeThatFits: method. Note that labels in UITableViewCell objects are sized based on the cell dimensions, and not a requested size.

The default implementation of this method returns the original bounds rectangle.

Availability
  • Available in iOS 2.0 and later.
Declared In
UILabel.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...