The iOS framework that grows only as fast as its documentation
NIAttributedLabel Class Reference

Overview

The NIAttributedLabel class provides support for displaying rich text with selectable links and embedded images.

Differences between UILabel and NIAttributedLabel:

  • NSLineBreakByTruncatingHead and NSLineBreakByTruncatingMiddle only apply to single lines and will not wrap the label regardless of the numberOfLines property. To wrap lines with any of these line break modes you must explicitly add newline characters to the string.
  • When you assign an NSString to the text property the attributed label will create an attributed string that inherits all of the label's current styles.
  • Text is aligned vertically to the top of the bounds by default rather than centered. You can change this behavior using verticalTextAlignment.
  • CoreText fills the frame with glyphs until they no longer fit. This is an important difference from UILabel because it means that CoreText will not add any glyphs that won't fit in the frame, while UILabel does. This can result in empty NIAttributedLabels if your frame is too small where UILabel would draw clipped text. It is recommended that you use sizeToFit to get the correct dimensions of the attributed label before setting the frame.

NIAttributedLabel implements the UIAccessibilityContainer methods to expose each link as an accessibility item.

Tasks

Accessing the Text Attributes
NSAttributedString * attributedString property
 
Accessing and Detecting Links
NSTextCheckingType dataDetectorTypes property
 
BOOL deferLinkDetection property
 
(void) - addLink:range:
 
Accessing Link Display Styles
UIColor * linkColor property
 
UIColor * highlightedLinkBackgroundColor property
 
BOOL linksHaveUnderlines property
 
Modifying Rich Text Styles for All Text
CGFloat lineHeight property
 
NIVerticalTextAlignment verticalTextAlignment property
 
CTUnderlineStyle underlineStyle property
 
CTUnderlineStyleModifiers underlineStyleModifier property
 
CGFloat shadowBlur property
 
CGFloat strokeWidth property
 
UIColor * strokeColor property
 
CGFloat textKern property
 
Modifying Tail Truncation Properties
NSString * tailTruncationString property
 
Accessing the Delegate
IBOutlet id
< NIAttributedLabelDelegate
delegate property
 
Modifying Rich Text Styles in Ranges
(void) - setFont:range:
 
(void) - setStrokeColor:range:
 
(void) - setStrokeWidth:range:
 
(void) - setTextColor:range:
 
(void) - setTextKern:range:
 
(void) - setUnderlineStyle:modifier:range:
 
Adding Inline Images
(void) - insertImage:atIndex:
 
(void) - insertImage:atIndex:margins:
 
(void) - insertImage:atIndex:margins:verticalTextAlignment:
 
Accessibility
(void) - invalidateAccessibleElements
 

Method Documentation

attributedString

This method is now deprecated and will eventually be removed, please use attributedText instead.

@property (nonatomic, copy) NSAttributedString* attributedString;

autoDetectLinks

A Booelan value indicating whether to automatically detect links in the string.

@property (nonatomic) BOOL autoDetectLinks;
Discussion

By default this is disabled.

Link detection is deferred until the label is displayed for the first time. If the text changes then all of the links will be cleared and re-detected when the label displays again.

Note that link detection is an expensive operation. If you are planning to use attributed labels in table views or similar high-performance situations then you should consider enabling defered link detection by setting deferLinkDetection to YES.

See Also
NIAttributedLabel::dataDetectorTypes
NIAttributedLabel::deferLinkDetection

dataDetectorTypes

The types of data that will be detected when autoDetectLinks is enabled.

@property (nonatomic) NSTextCheckingType dataDetectorTypes;
Discussion

By default this is NSTextCheckingTypeLink. All available data detector types.

deferLinkDetection

A Boolean value indicating whether to defer link detection to a separate thread.

@property (nonatomic) BOOL deferLinkDetection;
Discussion

By default this is disabled.

When defering is enabled, link detection will be performed on a separate thread. This will cause your label to appear without any links briefly before being redrawn with the detected links. This offloads the data detection to a separate thread so that your labels can be displayed faster.

linkColor

The text color of detected links.

@property (nonatomic, strong) UIColor* linkColor;
Discussion

The default color is [UIColor blueColor] on pre-iOS 7 devices or self.tintColor on iOS 7 devices. If linkColor is assigned nil then links will not be given any special color. Use attributesForLinks to specify alternative styling.

NIAttributedLabelLinkAttributes.png
Link attributes

highlightedLinkBackgroundColor

The background color of the link's selection frame when the user is touching the link.

@property (nonatomic, strong) UIColor* highlightedLinkBackgroundColor;
Discussion

The default is [UIColor colorWithWhite:0.5 alpha:0.5].

If you do not want links to be highlighted when touched, set this to nil.

NIAttributedLabelLinkAttributes.png
Link attributes

linksHaveUnderlines

A Boolean value indicating whether links should have underlines.

@property (nonatomic) BOOL linksHaveUnderlines;
Discussion

By default this is disabled.

This affects all links in the label.

attributesForLinks

A dictionary of CoreText attributes to apply to links.

@property (nonatomic, copy) NSDictionary* attributesForLinks;
Discussion

This dictionary must contain CoreText attributes. These attributes are applied after the color and underline styles have been applied to the link.

attributesForHighlightedLink

A dictionary of CoreText attributes to apply to the highlighted link.

@property (nonatomic, copy) NSDictionary* attributesForHighlightedLink;
Discussion

This dictionary must contain CoreText attributes. These attributes are applied after attributesForLinks have been applied to the highlighted link.

lineHeight

Sets the line height for the text.

@property (nonatomic) CGFloat lineHeight;
Discussion

By default this is zero.

Setting this value to zero will make the label use the default line height for the text's font.

verticalTextAlignment

The vertical alignment of the text within the label's bounds.

@property (nonatomic) NIVerticalTextAlignment verticalTextAlignment;
Discussion

The default is NIVerticalTextAlignmentTop. This is for performance reasons because the other modes require more computation. Aligning to the top is generally what you want anyway.

NIVerticalTextAlignmentBottom will align the text to the bottom of the bounds, while NIVerticalTextAlignmentMiddle will center the text vertically.

underlineStyle

The underline style for the entire label.

@property (nonatomic) CTUnderlineStyle underlineStyle;
Discussion

By default this is kCTUnderlineStyleNone.

View all available styles.

underlineStyleModifier

The underline style modifier for the entire label.

@property (nonatomic) CTUnderlineStyleModifiers underlineStyleModifier;
Discussion

By default this is kCTUnderlinePatternSolid.

View all available style modifiers.

shadowBlur

A non-negative number specifying the amount of blur to apply to the label's text shadow.

@property (nonatomic) CGFloat shadowBlur;
Discussion

By default this is zero.

strokeWidth

Sets the stroke width for the text.

@property (nonatomic) CGFloat strokeWidth;
Discussion

By default this is zero.

Positive numbers will draw the stroke. Negative numbers will draw the stroke and fill.

strokeColor

Sets the stroke color for the text.

@property (nonatomic, strong) UIColor* strokeColor;
Discussion

By default this is nil.

textKern

Sets the kern for the text.

@property (nonatomic) CGFloat textKern;
Discussion

By default this is zero.

The text kern indicates how many points each character should be shifted from its default offset. A positive kern indicates a shift farther away. A negative kern indicates a shift closer.

tailTruncationString

The string to display for tail truncation.

@property (nonatomic, copy) NSString* tailTruncationString;
Discussion

By default this is nil and the default ellipses character, , is used.

delegate

The delegate of the attributed-label object.

@property (nonatomic, weak) IBOutlet id<NIAttributedLabelDelegate> delegate;
Discussion

The delegate must adopt the NIAttributedLabelDelegate protocol. The NIAttributedLabel class, which does not strong the delegate, invokes each protocol method the delegate implements.

addLink:range:

Adds a link to a URL at a given range.

- (void)addLink:(NSURL *)urlLink range:(NSRange)range;
Discussion

Adding any links will immediately enable user interaction on this label. Explicitly added links are removed whenever the text changes.

removeAllExplicitLinks

Removes all explicit links from the label.

- (void)removeAllExplicitLinks;
Discussion

If you wish to remove automatically-detected links, set autoDetectLinks to NO.

setFont:range:

Sets the font for text in a given range.

- (void)setFont:(UIFont *)font range:(NSRange)range;

setStrokeColor:range:

Sets the stroke color for text in a given range.

- (void)setStrokeColor:(UIColor *)color range:(NSRange)range;

setStrokeWidth:range:

Sets the stroke width for text in a given range.

- (void)setStrokeWidth:(CGFloat)width range:(NSRange)range;
Discussion

Positive numbers will draw the stroke. Negative numbers will draw the stroke and fill.

setTextColor:range:

Sets the text color for text in a given range.

- (void)setTextColor:(UIColor *)textColor range:(NSRange)range;

setTextKern:range:

Sets the kern for text in a given range.

- (void)setTextKern:(CGFloat)kern range:(NSRange)range;
Discussion

The text kern indicates how many points each character should be shifted from its default offset. A positive kern indicates a shift farther away. A negative kern indicates a shift closer.

setUnderlineStyle:modifier:range:

Sets the underline style and modifier for text in a given range.

- (void)setUnderlineStyle:(CTUnderlineStyle)style modifier:(CTUnderlineStyleModifiers)modifier range:(NSRange)range;
Discussion

View all available styles.

View all available style modifiers.

insertImage:atIndex:

Inserts the given image inline at the given index in the receiver's text.

- (void)insertImage:(UIImage *)image atIndex:(NSInteger)index;
Discussion

The image will have no margins. The image's vertical text alignment will be NIVerticalTextAlignmentBottom.

Parameters
imageThe image to add to the receiver.
indexThe index into the receiver's text at which to insert the image.

insertImage:atIndex:margins:

Inserts the given image inline at the given index in the receiver's text.

- (void)insertImage:(UIImage *)image atIndex:(NSInteger)index margins:(UIEdgeInsets)margins;
Discussion

The image's vertical text alignment will be NIVerticalTextAlignmentBottom.

Parameters
imageThe image to add to the receiver.
indexThe index into the receiver's text at which to insert the image.
marginsThe space around the image on all sides in points.

insertImage:atIndex:margins:verticalTextAlignment:

Inserts the given image inline at the given index in the receiver's text.

- (void)insertImage:(UIImage *)image atIndex:(NSInteger)index margins:(UIEdgeInsets)margins verticalTextAlignment:(NIVerticalTextAlignment)verticalTextAlignment;
Discussion
Attention
Images do not currently support NIVerticalTextAlignmentTop and the receiver will fire multiple debug assertions if you attempt to use it.
Parameters
imageThe image to add to the receiver.
indexThe index into the receiver's text at which to insert the image.
marginsThe space around the image on all sides in points.
verticalTextAlignmentThe position of the text relative to the image.

invalidateAccessibleElements

Invalidates this label's accessible elements.

- (void)invalidateAccessibleElements;
Discussion

When a label is contained within another view and that parent view moves, the label will not be informed of this change and any existing accessibility elements will still point to the old screen location. If this happens you must call -invalidateAccessibleElements in order to force the label to refresh its accessibile elements.