Classes
class	NIAttributedLabel
	The NIAttributedLabel class provides support for displaying rich text with selectable links. More...
protocol	<NIAttributedLabelDelegate>
	The methods declared by the NIAttributedLabelDelegate protocol allow the adopting delegate to respond to messages from the NIAttributedLabel class and thus respond to selections. More...

Overview

The Nimbus Attributed Label is a UILabel that uses NSAttributedString to render rich text labels with links using CoreText.

A mashup of possible label styles

Minimum Requirements

Required frameworks:

Foundation.framework
UIKit.framework
CoreText.framework
QuartzCore.framework

Minimum Operating System: iOS 4.0

Source located in src/attributedlabel/src

#import "NimbusAttributedLabel.h"

Basic Use

NIAttributedLabel is a subclass of UILabel. The attributed label maintains an NSAttributedString object internally which is used in conjunction with CoreText to draw rich-text labels. A number of helper methods for modifying the text style are provided. If you need to directly modify the internal NSAttributedString you may do so by accessing the attributedString property on iOS 4 through 5.*.

Attention: iOS 6 Beta note: when building for iOS 6 and higher you must use the attributedText property now provided via UILabel.

NIAttributedLabel* label = [[NIAttributedLabel alloc] initWithFrame:CGRectZero];

// The internal NSAttributedString will inherit all of UILabel's text attributes when we assign
// text.
label.text = @"Nimbus";

Interface Builder

You can use an attributed label within Interface Builder by creating a UILabel and changing its class to NIAttributedLabel. This will allow you to set styles that apply to the entire string. If you want to style specific parts of the string then you will need to do this in code.

Configuring an attributed label in Interface Builder

Feature Overview

Automatic link detection using data detectors
Link attributes
Explicit links
Underlining
Justifying paragraphs
Stroking
Kerning
Setting rich text styles at specific ranges

Automatic Link Detection

Automatic link detection is provided using NSDataDetector. Link detection is off by default and can be enabled by setting autoDetectLinks to YES. You may configure the types of data that are detected by modifying the dataDetectorTypes property. By default only urls will be detected.

Attention: NIAttributedLabel is not designed to detect html anchor tags (i.e. <a>). If you want to attach a URL to a given range of text you must use addLink:range:.

Before enabling autoDetectLinks

// Enable link detection on the label.
myLabel.autoDetectLinks = YES;

After enabling autoDetectLinks

Enabling automatic link detection will automatically enable user interation with the label view so that the user can tap the detected links.

Link Attributes

Detected links will use linkColor and highlightedLinkColor to differentiate themselves from standard text. highlightedLinkColor is the color of the highlighting frame around the text. You can easily add underlines to links by enabling linksHaveUnderlines. You can customize link attributes in more detail by directly modifying the attributesForLinks property.

Link attributes

A note on performance

Automatic link detection is expensive. You can choose to defer automatic link detection by enabling deferLinkDetection. This will move the link detection to a separate background thread. Once the links have been detected the label will be redrawn.

Handling Taps on Links

The NIAttributedLabelDelegate protocol allows you to handle when the user taps on a given link. The protocol methods provide the tap point as well as the data pertaining to the tapped link.

- (void)attributedLabel:(NIAttributedLabel *)attributedLabel didSelectTextCheckingResult:(NSTextCheckingResult *)result atPoint:(CGPoint)point {
  [[UIApplication sharedApplication] openURL:result.URL];
}

Explicit Links

Links can be added explicitly using addLink:range:.

// Add a link to the string 'nimbus' in myLabel.
[myLabel addLink:[NSURL URLWithString:@"nimbus://custom/url"]
           range:[myLabel.text rangeOfString:@"nimbus"]];

Underlining Text

To underline an entire label:

// Underline the whole label with a single line.
myLabel.underlineStyle = kCTUnderlineStyleSingle;

Underline modifiers can also be added:

// Underline the whole label with a dash dot single line.
myLabel.underlineStyle = kCTUnderlineStyleSingle;
myLabel.underlineStyleModifier = kCTUnderlinePatternDashDot;

Underline styles and modifiers can be mixed to create the desired effect, which is shown in the following screenshot:

Underline styles

Remarks: Underline style kCTUnderlineStyleThick only over renders a single line.

Justifying Paragraphs

NIAttributedLabel supports justified text using UITextAlignmentJustify.

 myLabel.textAlignment = UITextAlignmentJustify;

Stroking Text

myLabel.strokeWidth = 3.0;
myLabel.strokeColor = [UIColor blackColor];

A positive stroke width will render only the stroke.

Black stroke of 3.0

A negative number will fill the stroke with textColor:

myLabel.strokeWidth = -3.0;
myLabel.strokeColor = [UIColor blackColor];

Black stroke of -3.0

Kerning Text

Kerning is the space between characters in points. A positive kern will increase the space between letters. Correspondingly a negative number will decrease the space.

myLabel.textKern = -6.0;

Text kern of -6.0

Setting Rich Text styles at specific ranges

All styles that can be added to the whole label (as well as default UILabel styles like font and text color) can be added to just a range of text.

[myLabel setTextColor:[UIColor orangeColor] range:[myLabel.text rangeOfString:@"Nimbus"]];
[myLabel setFont:[UIFont boldSystemFontOfSize:22] range:[myLabel.text rangeOfString:@"iOS"]];

Classes