Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
233 lines (178 sloc) 9.73 KB
// TTTAttributedLabel.h
//
// Copyright (c) 2011 Mattt Thompson (http://mattt.me)
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
#import <UIKit/UIKit.h>
#import <CoreText/CoreText.h>
typedef enum {
TTTAttributedLabelVerticalAlignmentCenter = 0,
TTTAttributedLabelVerticalAlignmentTop = 1,
TTTAttributedLabelVerticalAlignmentBottom = 2,
} TTTAttributedLabelVerticalAlignment;
@protocol TTTAttributedLabelDelegate;
// Override UILabel @property to accept both NSString and NSAttributedString
@protocol TTTAttributedLabel <NSObject>
@property (nonatomic, copy) id text;
@end
/**
`TTTAttributedLabel` is a drop-in replacement for `UILabel` that supports `NSAttributedString`, as well as automatically-detected and manually-added links to URLs, addresses, phone numbers, and dates.
*/
@interface TTTAttributedLabel : UILabel <TTTAttributedLabel> {
@private
NSAttributedString *_attributedText;
CTFramesetterRef _framesetter;
BOOL _needsFramesetter;
id _delegate;
UIDataDetectorTypes _dataDetectorTypes;
NSArray *_links;
NSDictionary *_linkAttributes;
TTTAttributedLabelVerticalAlignment _verticalAlignment;
BOOL _userInteractionDisabled;
}
///-----------------------------
/// @name Accessing the Delegate
///-----------------------------
/**
The receiver's delegate.
@discussion A `TTTAttributedLabel` delegate responds to messages sent by tapping on links in the label. You can use the delegate to respond to links referencing a URL, address, phone number, date, or date with a specified time zone and duration.
*/
@property (nonatomic, assign) id <TTTAttributedLabelDelegate> delegate;
///------------------------------------
/// @name Detecting and Accessing Links
///------------------------------------
/**
A bitmask of `UIDataDetectorTypes` which are used to automatically detect links in the label text.
@discussion This bitmask is `UIDataDetectorTypeNone` by default.
@warning You must specify `dataDetectorTypes` before setting the `text`, with either `setText:` or `setText:afterInheritingLabelAttributesAndConfiguringWithBlock:`.
*/
@property (nonatomic, assign) UIDataDetectorTypes dataDetectorTypes;
/**
An array of `NSTextCheckingResult` objects for links detected or manually added to the label text.
*/
@property (readonly, nonatomic, retain) NSArray *links;
///---------------------------------------
/// @name Acccessing Text Style Attributes
///---------------------------------------
/**
A dictionary containing the `NSAttributedString` attributes to be applied to links detected or manually added to the label text.
@discussion The default link style is blue and underlined.
@warning You must specify `linkAttributes` before setting autodecting or manually-adding links for these attributes to be applied.
*/
@property (nonatomic, retain) NSDictionary *linkAttributes;
/**
The vertical text alignment for the label, for when the frame size is greater than the text rect size.
@discussion The default vertical alignment is `TTTAttributedLabelVerticalAlignmentCenter`.
*/
@property (nonatomic, assign) TTTAttributedLabelVerticalAlignment verticalAlignment;
///----------------------------------
/// @name Setting the Text Attributes
///----------------------------------
/**
Sets the text displayed by the label.
@param text An `NSString` or `NSAttributedString` object to be displayed by the label. If the specified text is an `NSString`, the label will display the text like a `UILabel`, inheriting the text styles of the label. If the specified text is an `NSAttributedString`, the label text styles will be overridden by the styles specified in the attributed string.
@discussion This method overrides `UILabel -setText:` to accept both `NSString` and `NSAttributedString` objects. This string is `nil` by default.
*/
- (void)setText:(id)text;
/**
Sets the text displayed by the label, after configuring an attributed string containing the text attributes inherited from the label in a block.
@param text An `NSString` or `NSAttributedString` object to be displayed by the label.
@param block A block object that returns an `NSMutableAttributedString` object and takes a single argument, which is an `NSMutableAttributedString` object with the text from the first parameter, and the text attributes inherited from the label text styles. For example, if you specified the `font` of the label to be `[UIFont boldSystemFontOfSize:14]` and `textColor` to be `[UIColor redColor]`, the `NSAttributedString` argument of the block would be contain the `NSAttributedString` attribute equivalents of those properties. In this block, you can set further attributes on particular ranges.
@discussion This string is `nil` by default.
*/
- (void)setText:(id)text afterInheritingLabelAttributesAndConfiguringWithBlock:(NSMutableAttributedString *(^)(NSMutableAttributedString *mutableAttributedString))block;
///-------------------
/// @name Adding Links
///-------------------
/**
Adds a link to a URL for a specified range in the label text.
@param url The url to be linked to
@param range The range in the label text of the link. The range must not exceed the bounds of the receiver.
*/
- (void)addLinkToURL:(NSURL *)url withRange:(NSRange)range;
/**
Adds a link to an address for a specified range in the label text.
@param addressComponents A dictionary of address components for the address to be linked to
@param range The range in the label text of the link. The range must not exceed the bounds of the receiver.
@discussion The address component dictionary keys are described in `NSTextCheckingResult`'s "Keys for Address Components."
@see NSTextCheckingResult
*/
- (void)addLinkToAddress:(NSDictionary *)addressComponents withRange:(NSRange)range;
/**
Adds a link to a phone number for a specified range in the label text.
@param phoneNumber The phone number to be linked to.
@param range The range in the label text of the link. The range must not exceed the bounds of the receiver.
*/
- (void)addLinkToPhoneNumber:(NSString *)phoneNumber withRange:(NSRange)range;
/**
Adds a link to a date for a specified range in the label text.
@param date The date to be linked to.
@param range The range in the label text of the link. The range must not exceed the bounds of the receiver.
*/
- (void)addLinkToDate:(NSDate *)date withRange:(NSRange)range;
/**
Adds a link to a date with a particular time zone and duration for a specified range in the label text.
@param date The date to be linked to.
@param timeZone The time zone of the specified date.
@param duration The duration, in seconds from the specified date.
@param range The range in the label text of the link. The range must not exceed the bounds of the receiver.
*/
- (void)addLinkToDate:(NSDate *)date timeZone:(NSTimeZone *)timeZone duration:(NSTimeInterval)duration withRange:(NSRange)range;
@end
/**
The `TTTAttributedLabelDelegate` protocol defines the messages sent to an attributed label delegate when links are tapped. All of the methods of this protocol are optional.
*/
@protocol TTTAttributedLabelDelegate <NSObject>
///-----------------------------------
/// @name Responding to Link Selection
///-----------------------------------
@optional
/**
Tells the delegate that the user did select a link to a URL.
@param label The label whose link was selected.
@param url The URL for the selected link.
*/
- (void)attributedLabel:(TTTAttributedLabel *)label didSelectLinkWithURL:(NSURL *)url;
/**
Tells the delegate that the user did select a link to an address.
@param label The label whose link was selected.
@param addressComponents The components of the address for the selected link.
*/
- (void)attributedLabel:(TTTAttributedLabel *)label didSelectLinkWithAddress:(NSDictionary *)addressComponents;
/**
Tells the delegate that the user did select a link to a phone number.
@param label The label whose link was selected.
@param phoneNumber The phone number for the selected link.
*/
- (void)attributedLabel:(TTTAttributedLabel *)label didSelectLinkWithPhoneNumber:(NSString *)phoneNumber;
/**
Tells the delegate that the user did select a link to a date.
@param label The label whose link was selected.
@param date The datefor the selected link.
*/
- (void)attributedLabel:(TTTAttributedLabel *)label didSelectLinkWithDate:(NSDate *)date;
/**
Tells the delegate that the user did select a link to a date with a time zone and duration.
@param label The label whose link was selected.
@param date The date for the selected link.
@param timeZone The time zone of the date for the selected link.
@param duration The duration, in seconds from the date for the selected link.
*/
- (void)attributedLabel:(TTTAttributedLabel *)label didSelectLinkWithDate:(NSDate *)date timeZone:(NSTimeZone *)timeZone duration:(NSTimeInterval)duration;
@end