Inherits from UIView
Declared in IGLabel.h

Overview

The IGLabel is a rich text label that works similarly to the generic UILabel and applies styles to text in a similar fashion that is done when using attributed strings. It is based on Core Text to boost performance and functionality over the generic UILabel.

Attributes are used to decorate the displayed text using an NSRange or a regular expression search string through these two methods; addAttributes:range:, and addAttributes:forRegEx:error:. Attributes allow you to adjust these text characteristics; bold appearance, font used, text foreground color, italic appearance, kern spacing, text stroke color and width, interaction of text through tap, and underline appearance and color.

Text variables are added by using the addTextVariable:value: method and are used to allow for the usage of dynamic text values. When the text property changes and text variables were defined, they are automatically updated with the configured value.

Tasks

Initialization and Configuration

  •   delegate

    The object that acts as the delegate of the label.

    property
  •   font

    The font of the text.

    property
  •   text

    Sets the text displayed in the label.

    property

Overflow Indicator

  •   overflowIndicatorAlignment

    The edge alignment at which to display the overflow indicator. Type: IGTextOverflowAlignment. Default: IGTextOverflowAlignmentRightCenter.

    property
  •   overflowIndicatorView

    A view to display as the overflow indicator. Type: UIView. Default: nil.

    property
  •   overflowIndicatorVisible

    Sets whether or not to display an indicator when the text has exceeded the available space. Type: BOOL. Default: NO.

    property

Paragraph and Text Styling

  •   firstLineHeadIndent

    The distance, in points, from the leading marginAll of a label to the beginning of the paragraph’s first line. This value is always non-negative. Type: CGFloat. Default: 0.0.

    property
  •   headIndent

    The distance, in points, from the leading marginAll of the label to the beginning of lines other than the first. This value is always non-negative. Type: CGFloat Default: 0.0.

    property
  •   horizontalTextAlignment

    The text alignment. Type: IGTextAlignment. Default: IGTextAlignmentLeft.

    property
  •   lineBreakMode

    Specifies what happens when a line of text is too long for the width of the label. Type: IGLineBreakMode. Default: IGBreakByWordWrapping.

    property
  •   lineSpacing

    The space in points added between lines within the paragraph (commonly known as leading). This value is always non-negative. Type: CGFloat. Default: 0.0.

    property
  •   marginAll

    The space separating the edge of the label from the text. This value is always non-negative. When this property is set, the marginBottom, marginLeft, marginRight, and marginTop properties are invalidated and set to 0.0. Type: CGFloat. Default: 8.0.

    property
  •   marginBottom

    The space separating the bottom edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

    property
  •   marginLeft

    The space separating the left edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

    property
  •   marginRight

    The space separating the right edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

    property
  •   marginTop

    The space separating the top edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

    property
  •   paragraphSpacingBefore

    The distance between the paragraph’s top and the beginning of its text content. Type: CGFloat. Default: 0.0.

    property
  •   paragraphSpacingAfter

    The space added at the end of the paragraph to separate it from the following paragraph. This value is always non-negative. Type: CGFloat. Default: 0.0.

    property
  •   tailIndent

    The distance, in points, from the marginAll of a label to the end of lines. If positive, this value is the distance from the leading marginAll. If 0 or negative, it’s the distance from the trailing marginAll. Type: CGFloat. Default: 0.0.

    property
  •   textColor

    The color of the text.

    property

Text Styling Attributes

Text Variables

Properties

delegate

The object that acts as the delegate of the label.

@property (nonatomic, assign) id<> delegate

Discussion

The class must adopt the IGLabelDelegate protocol.

Declared In

IGLabel.h

firstLineHeadIndent

The distance, in points, from the leading marginAll of a label to the beginning of the paragraph’s first line. This value is always non-negative. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat firstLineHeadIndent

Declared In

IGLabel.h

font

The font of the text.

@property (nonatomic, retain) UIFont *font

Discussion

The default value for this property is the Helvetica font at a size of 12 points. The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

Declared In

IGLabel.h

headIndent

The distance, in points, from the leading marginAll of the label to the beginning of lines other than the first. This value is always non-negative. Type: CGFloat Default: 0.0.

@property (nonatomic, assign) CGFloat headIndent

Declared In

IGLabel.h

horizontalTextAlignment

The text alignment. Type: IGTextAlignment. Default: IGTextAlignmentLeft.

@property (nonatomic, assign) IGTextAlignment horizontalTextAlignment

Discussion

Supported enumerated values:

  • IGTextAlignmentLeft – Text is visually left aligned.
  • IGTextAlignmentRight – Text is visually right aligned.
  • IGTextAlignmentCenter – Text is visually center aligned.
  • IGTextAlignmentJustified – Text is fully justified. The last line in a paragraph is naturally aligned.

Declared In

IGLabel.h

lineBreakMode

Specifies what happens when a line of text is too long for the width of the label. Type: IGLineBreakMode. Default: IGBreakByWordWrapping.

@property (nonatomic, assign) IGLineBreakMode lineBreakMode

Discussion

Supported enumerated values:

  • IGBreakByWordWrapping – Wrapping occurs at word boundaries unless the word itself doesn’t fit on a single line.
  • IGBreakByCharWrapping – Wrapping occurs before the first character that doesn’t fit.
  • IGBreakByClipping – Lines are simply not drawn past the edge of the label.
  • IGBreakByTruncatingHead – Each line is displayed so that the end fits in the label and the missing text is indicated by an ellipsis glyph.
  • IGBreakByTruncatingTail – Each line is displayed so that the beginning fits in the label and the missing text is indicated by an ellipsis glyph.
  • IGBreakByTruncatingMiddle – Each line is displayed so that the beginning and end fit in the label and the missing text is indicated by an ellipsis glyph in the middle.

Declared In

IGLabel.h

lineSpacing

The space in points added between lines within the paragraph (commonly known as leading). This value is always non-negative. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat lineSpacing

Declared In

IGLabel.h

marginAll

The space separating the edge of the label from the text. This value is always non-negative. When this property is set, the marginBottom, marginLeft, marginRight, and marginTop properties are invalidated and set to 0.0. Type: CGFloat. Default: 8.0.

@property (nonatomic, assign) CGFloat marginAll

Declared In

IGLabel.h

marginBottom

The space separating the bottom edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat marginBottom

Declared In

IGLabel.h

marginLeft

The space separating the left edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat marginLeft

Declared In

IGLabel.h

marginRight

The space separating the right edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat marginRight

Declared In

IGLabel.h

marginTop

The space separating the top edge of the label from the text. This value is always non-negative. When this property is set, the marginAll property is invalidated and set to -1.0. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat marginTop

Declared In

IGLabel.h

overflowIndicatorAlignment

The edge alignment at which to display the overflow indicator. Type: IGTextOverflowAlignment. Default: IGTextOverflowAlignmentRightCenter.

@property (nonatomic, assign) IGTextOverflowAlignment overflowIndicatorAlignment

Discussion

Supported enumeration values:

  • IGTextOverflowAlignmentBottomCenter – Aligns the overflow indicator to the bottom center of the label.
  • IGTextOverflowAlignmentBottomLeft – Aligns the overflow indicator to the bottom left of the label.
  • IGTextOverflowAlignmentBottomRight – Aligns the overflow indicator to the bottom right of the label.
  • IGTextOverflowAlignmentLeftCenter – Aligns the overflow indicator to the left center of the label.
  • IGTextOverflowAlignmentRightCenter – Aligns the overflow indicator to the right center of the label.
  • IGTextOverflowAlignmentTopCenter – Aligns the overflow indicator to the top center of the label.
  • IGTextOverflowAlignmentTopLeft – Aligns the overflow indicator to the top left of the label.
  • IGTextOverflowAlignmentTopRight – Aligns the overflow indicator to the top right of the label.

Declared In

IGLabel.h

overflowIndicatorView

A view to display as the overflow indicator. Type: UIView. Default: nil.

@property (nonatomic, retain) UIView *overflowIndicatorView

Declared In

IGLabel.h

overflowIndicatorVisible

Sets whether or not to display an indicator when the text has exceeded the available space. Type: BOOL. Default: NO.

@property (nonatomic, assign) BOOL overflowIndicatorVisible

Declared In

IGLabel.h

paragraphSpacingAfter

The space added at the end of the paragraph to separate it from the following paragraph. This value is always non-negative. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat paragraphSpacingAfter

Declared In

IGLabel.h

paragraphSpacingBefore

The distance between the paragraph’s top and the beginning of its text content. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat paragraphSpacingBefore

Declared In

IGLabel.h

tailIndent

The distance, in points, from the marginAll of a label to the end of lines. If positive, this value is the distance from the leading marginAll. If 0 or negative, it’s the distance from the trailing marginAll. Type: CGFloat. Default: 0.0.

@property (nonatomic, assign) CGFloat tailIndent

Declared In

IGLabel.h

text

Sets the text displayed in the label.

@property (nonatomic, retain) NSString *text

Discussion

Important: Setting this property will reset any previously applied attributes.

Declared In

IGLabel.h

textColor

The color of the text.

@property (nonatomic, retain) UIColor *textColor

Discussion

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.

Declared In

IGLabel.h

Instance Methods

addAttributes:forRegEx:error:

Adds styling attributes to the matched results of the supplied regular expression.

- (void)addAttributes:(NSDictionary *)attributes forRegEx:(NSString *)expression error:(NSError **)error

Parameters

attributes

The dictionary of styling key/value attributes.

error

The error output reference, should the regular expression contain any errors.

forRegEx

The regular expression that will apply the styling attributes to expression matches.

Discussion

Supported key enumeration values:

  • IGTextStyleBackgroundColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleBoldAttributeName – the value used with this key is a UIFont.
  • IGTextStyleFontAttributeName – the value used with this key is a UIFont.
  • IGTextStyleForegroundColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleItalicAttributeName – the value used with this key is a UIFont.
  • IGTextStyleKernAttributeName – the value used with this key is a NSNumber with float.
  • IGTextStyleStrokeColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleStrokeWidthAttributeName – the value used with this key is a NSNumber with float.
  • IGTextStyleTapAttributeName – the value used with this key is a NSObject.
  • IGTextStyleUnderlineAttributeName – the value used with this key is a NSNumber with int. An int value of 1 means on, 0 means off.
  • IGTextStyleUnderlineColorAttributeName – the value used with this key is a UIColor.

The following code is an example of adding attributes to an instanced label.

label.text = @"The quick brown fox jumped over the lazy dogs.";
NSDictionary *attributes = [NSDictionary dictionaryWithObjectsAndKeys:
                [UIFont systemFontOfSize:24], IGTextStyleBoldAttributeName,
                [UIColor darkTextColor], IGTextStyleForegroundColorAttributeName,
                @"The word 'fox' was tapped.", IGTextStyleTapAttributeName, nil];
NSError *error;
[label addAttributes:attributes forRegEx:@"fox" error:&error];

Declared In

IGLabel.h

addAttributes:range:

Adds styling attributes to a specific range of text.

- (void)addAttributes:(NSDictionary *)attributes range:(NSRange)styleRange

Parameters

attributes

The dictionary of styling key/value attributes.

styleRange

The range of text where the styling attributes are to be applied.

Discussion

Supported key enumeration values:

  • IGTextStyleBackgroundColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleBoldAttributeName – the value used with this key is a UIFont.
  • IGTextStyleFontAttributeName – the value used with this key is a UIFont.
  • IGTextStyleForegroundColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleItalicAttributeName – the value used with this key is a UIFont.
  • IGTextStyleKernAttributeName – the value used with this key is a NSNumber with float.
  • IGTextStyleStrokeColorAttributeName – the value used with this key is a UIColor.
  • IGTextStyleStrokeWidthAttributeName – the value used with this key is a NSNumber with float.
  • IGTextStyleTapAttributeName – the value used with this key is a NSObject.
  • IGTextStyleUnderlineAttributeName – the value used with this key is a NSNumber with int. An int value of 1 means on, 0 means off.
  • IGTextStyleUnderlineColorAttributeName – the value used with this key is a UIColor.

The following code is an example of adding attributes to an instanced label.

label.text = @"The quick brown fox jumped over the lazy dogs.";
NSDictionary *attributes = [NSDictionary dictionaryWithObjectsAndKeys:
        [NSNumber numberWithInt:1], IGTextStyleUnderlineAttributeName,
        [UIColor greenColor], IGTextStyleUnderlineColorAttributeName, nil];
[label addAttributes:attributes range:NSMakeRange(16, 3)];

Declared In

IGLabel.h

addTextVariable:value:

Adds a text variable to the label that replaces occurrences of the variable with a string value.

- (void)addTextVariable:(NSString *)variable value:(NSString *)value

Parameters

variable

The text variable to search and replace.

value

The string value to replace occurrences of the variable with.

Discussion

Changing the text property will automatically reapply the variables.

The following code is an example of adding text variables to an instanced label.

label.text = @"Hello Mr. {LastName}, welcome back to the application.";
[label addTextVariable:@"{LastName}" value:@"Betts"];

Declared In

IGLabel.h

removeAttribute:forRegEx:error:

Removes a styling attribute from the matched results of the supplied regular expression.

- (void)removeAttribute:(NSString *)name forRegEx:(NSString *)expression error:(NSError **)error

Parameters

name

A supported styling key enumeration value.

expression

The regular expression that will apply the styling attributes to expression matches.

error

The error output reference, should the regular expression contain any errors.

Discussion

Supported key enumeration values:

  • IGTextStyleBackgroundColorAttributeName
  • IGTextStyleBoldAttributeName
  • IGTextStyleFontAttributeName
  • IGTextStyleForegroundColorAttributeName
  • IGTextStyleItalicAttributeName
  • IGTextStyleKernAttributeName
  • IGTextStyleStrokeColorAttributeName
  • IGTextStyleStrokeWidthAttributeName
  • IGTextStyleTapAttributeName
  • IGTextStyleUnderlineAttributeName
  • IGTextStyleUnderlineColorAttributeName

The following code is an example of removing an attribute from an instanced label.

label.text = @"The quick brown fox jumped over the lazy dogs.";
NSDictionary *attributes = [NSDictionary dictionaryWithObjectsAndKeys:
                [UIFont systemFontOfSize:24], IGTextStyleBoldAttributeName,
                [UIColor darkTextColor], IGTextStyleForegroundColorAttributeName,
                @"The word 'fox' was tapped.", IGTextStyleTapAttributeName, nil];
[label addAttributes:attributes range:NSMakeRange(16, 3)];

//Removing an applied style attribute
[label removeAttribute:IGTextBoldAttributeName forRegEx:@"fox" error:nil];

Declared In

IGLabel.h

removeAttribute:range:

Removes a styling attribute from a specific range of text.

- (void)removeAttribute:(NSString *)name range:(NSRange)styleRange

Parameters

name

A supported styling key enumeration value.

styleRange

The range of text where the styling attributes are to be removed.

Discussion

Supported key enumeration values:

  • IGTextStyleBackgroundColorAttributeName
  • IGTextStyleBoldAttributeName
  • IGTextStyleFontAttributeName
  • IGTextStyleForegroundColorAttributeName
  • IGTextStyleItalicAttributeName
  • IGTextStyleKernAttributeName
  • IGTextStyleStrokeColorAttributeName
  • IGTextStyleStrokeWidthAttributeName
  • IGTextStyleTapAttributeName
  • IGTextStyleUnderlineAttributeName
  • IGTextStyleUnderlineColorAttributeName

The following code is an example of removing style attributes from an instanced label.

label.text = @"The quick brown fox jumped over the lazy dogs.";
NSDictionary *attributes = [NSDictionary dictionaryWithObjectsAndKeys:
                [UIFont systemFontOfSize:12], IGTextStyleFontAttributeName,
                [UIFont systemFontOfSize:28], IGTextStyleBoldAttributeName,
                [UIColor redColor], IGTextStyleForegroundColorAttributeName, nil];
[label addAttributes:attributes range:NSMakeRange(0, 3)];

//Removing an applied style attribute
[label removeAttribute:IGTextStyleForegroundColorAttributeName range:NSMakeRange(0, 3)];

Declared In

IGLabel.h

removeTextVariable:

Removes a text variable entry

- (void)removeTextVariable:(NSString *)variable

Parameters

variable

The text variable to remove from auto replacement.

Discussion

This removes a text variable entry from the label, so that is no longer auto replaced should the text property be set again.

Declared In

IGLabel.h

resetAttributes

Removes all attributes that have been added to the label.

- (void)resetAttributes

Declared In

IGLabel.h

resetTextVariables

Removes all text variables that have been added to the label.

- (void)resetTextVariables

Declared In

IGLabel.h

sizeToFitWidth

Resizes the IGLabel height to fit the text.

- (void)sizeToFitWidth

Discussion

Use this method when you need to resize the IGLabel to fit its text and respect the width bounds. This method requires the IGLabel to have drawn to the screen beforehand.

Declared In

IGLabel.h

updateTextVariableValue:value:

Updates a text variable value

- (void)updateTextVariableValue:(NSString *)variable value:(NSString *)value

Parameters

variable

The text variable to update its value.

value

The updated string value to replace occurrences of the variable with.

Declared In

IGLabel.h