Inherits from UILabel
Declared in MarqueeLabel.h

Overview

MarqueeLabel is a UILabel subclass adds a scrolling marquee effect when the text of a label instance outgrows the available width. Instances of MarqueeLabel can be configured for label scrolling direction/looping, speed/rate, and other options.

Tasks

Creating MarqueeLabels

Configuration Options

  •   animationCurve

    Specifies the animation curve used in the scrolling motion of the labels.

    property
  •   labelize

    A boolean property that sets whether the MarqueeLabel should behave like a normal UILabel.

    property
  •   holdScrolling

    A boolean property that sets whether the MarqueeLabel should hold (prevent) label scrolling.

    property
  •   tapToScroll

    A boolean property that sets whether the MarqueeLabel should only begin a scroll when tapped.

    property
  •   marqueeType

    Defines the direction and method in which the MarqueeLabel instance scrolls.

    property
  •   scrollDuration

    Defines the duration of the scrolling animation.

    property
  •   rate

    Defines the rate at which the label will scroll, in pixels per second.

    property
  •   leadingBuffer

    A buffer (offset) between the leading edge of the label text and the label frame.

    property
  •   trailingBuffer

    A buffer (offset) between the trailing edge of the label text and the label frame.

    property
  •   )

    The additional amount of space (in points) inbetween the strings of a continuous-type label. (Deprecated: Use trailingBuffer instead. Values set to this property are simply forwarded to trailingBuffer.)

    property
  •   fadeLength

    The length of transparency fade at the left and right edges of the MarqueeLabel instance’s frame.

    property
  •   animationDelay

    The length of delay in seconds that the label pauses at the completion of a scroll.

    property

Animation control

  • – restartLabel

    Immediately resets the label to the home position, and restarts the scroll animation if the appropriate conditions are met.

  • – resetLabel

    Resets the label text, recalculating the scroll animation.

  • – pauseLabel

    Pauses the text scrolling animation, at any point during the animation.

  • – unpauseLabel

    Un-pauses a previously paused text scrolling animation

  • – triggerScrollStart

    Overrides any non-size condition which is preventing the receiver from automatically scrolling, and begins a scroll animation.

Animation Status

  • – labelWillBeginScroll

    Called when the label animation is about to begin.

  • – labelReturnedToHome:

    Called when the label animation has finished, and the label is at the home position.

  •   isPaused

    A boolean property that indicates if the label’s scroll animation has been paused.

    property
  •   awayFromHome

    A boolean property that indicates if the label is currently away from the home location.

    property

Bulk-manipulation Methods

  • + restartLabelsOfController:

    Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

  • + controllerViewDidAppear:

    Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

  • + controllerViewWillAppear:

    Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

  • + controllerViewAppearing:

    Restarts all MarqueeLabel instances that have the specified view controller in their next responder chain. (Deprecated: Use controllerViewDidAppear: instead.)

  • + controllerLabelsShouldLabelize:

    Labelizes all MarqueeLabel instances that have the specified view controller in their next responder chain.

  • + controllerLabelsShouldAnimate:

    De-Labelizes all MarqueeLabel instances that have the specified view controller in their next responder chain.

Properties

)

@property (nonatomic, assign) CGFloat continuousMarqueeExtraBuffer DEPRECATED_MSG_ATTRIBUTE ( "Use trailingBuffer property instead." )
Discussion

The additional amount of space (in points) inbetween the strings of a continuous-type label.

Defaults to 0.

Declared In

MarqueeLabel.h

animationCurve

@property (nonatomic, assign) UIViewAnimationOptions animationCurve
Discussion

Specifies the animation curve used in the scrolling motion of the labels.

Allowable options:

- `UIViewAnimationOptionCurveEaseInOut`
- `UIViewAnimationOptionCurveEaseIn`
- `UIViewAnimationOptionCurveEaseOut`
- `UIViewAnimationOptionCurveLinear`

Defaults to UIViewAnimationOptionCurveEaseInOut.

Declared In

MarqueeLabel.h

animationDelay

@property (nonatomic, assign) IBInspectable CGFloat animationDelay
Discussion

The length of delay in seconds that the label pauses at the completion of a scroll.

Declared In

MarqueeLabel.h

awayFromHome

@property (nonatomic, assign, readonly) BOOL awayFromHome
Discussion

A boolean property that indicates if the label is currently away from the home location.

The “home” location is the traditional location of UILabel text. This property essentially reflects if a scroll animation is underway.

Declared In

MarqueeLabel.h

fadeLength

@property (nonatomic, assign) IBInspectable CGFloat fadeLength
Discussion

The length of transparency fade at the left and right edges of the MarqueeLabel instance’s frame.

This propery sets the size (in points) of the view edge transparency fades on the left and right edges of a MarqueeLabel. The transparency fades from an alpha of 1.0 (fully visible) to 0.0 (fully transparent) over this distance. Values set to this property will be sanitized to prevent a fade length greater than ½ of the frame width.

Defaults to 0.

Declared In

MarqueeLabel.h

holdScrolling

@property (nonatomic, assign) IBInspectable BOOL holdScrolling
Discussion

A boolean property that sets whether the MarqueeLabel should hold (prevent) label scrolling.

When set to YES, the MarqueeLabel will not automatically scroll even its text is larger than the specified frame, although the specified edge fades will remain.

To set the MarqueeLabel to act like a normal UILabel, use the labelize property.

Defaults to NO.

Warning: The label will not automatically scroll when this property is set to YES.

Declared In

MarqueeLabel.h

isPaused

@property (nonatomic, assign, readonly) BOOL isPaused
Discussion

A boolean property that indicates if the label’s scroll animation has been paused.

Declared In

MarqueeLabel.h

labelize

@property (nonatomic, assign) IBInspectable BOOL labelize
Discussion

A boolean property that sets whether the MarqueeLabel should behave like a normal UILabel.

When set to YES the MarqueeLabel will behave like a normal UILabel, and will not begin scrolling when the text is larger than the specified frame. The change takes effect immediately, removing any in-flight animation as well as any current edge fade. Note that the MarqueeLabel will respect the current values of the lineBreakMode and textAlignment properties while labelized.

To simply prevent automatic scrolling, use the holdScrolling property.

Defaults to NO.

Warning: The label will not automatically scroll when this property is set to YES.

Warning: The UILabel default setting for the lineBreakMode property is NSLineBreakByTruncatingTail, which truncates the text adds an ellipsis glyph (…). Set the lineBreakMode property to NSLineBreakByClipping in order to avoid the ellipsis, especially if using an edge transparency fade.

Declared In

MarqueeLabel.h

leadingBuffer

@property (nonatomic, assign) IBInspectable CGFloat leadingBuffer
Discussion

A buffer (offset) between the leading edge of the label text and the label frame.

This property adds additional space between the leading edge of the label text and the label frame. The leading edge is the edge of the label text facing the direction of scroll (i.e. the edge that animates offscreen first during scrolling).

Defaults to 0.

Note: The value set to this property affects label positioning at all times (including when labelize is set to YES), including when the text string length is short enough that the label does not need to scroll.

Note: For MLContinuous-type labels, the smallest value of leadingBuffer, ‘trailingBuffer, andfadeLength` is used as spacing between the two label instances. Zero is an allowable value for all three properties.

Availability

Available in 2.1.0 and later.

Declared In

MarqueeLabel.h

marqueeType

@property (nonatomic, assign) MarqueeType marqueeType
Discussion

Defines the direction and method in which the MarqueeLabel instance scrolls.

MarqueeLabel supports four types of scrolling: MLLeftRight, MLRightLeft, MLContinuous, and MLContinuousReverse.

Given the nature of how text direction works, the options for the marqueeType property require specific text alignments and will set the textAlignment property accordingly.

  • MLLeftRight type is ONLY compatible with a label text alignment of NSTextAlignmentLeft.
  • MLRightLeft type is ONLY compatible with a label text alignment of NSTextAlignmentRight.
  • MLContinuous does not require a text alignment (it is effectively centered).
  • MLContinuousReverse does not require a text alignment (it is effectively centered).

Defaults to MLLeftRight.

See Also

Declared In

MarqueeLabel.h

rate

@property (nonatomic, assign) IBInspectable CGFloat rate
Discussion

Defines the rate at which the label will scroll, in pixels per second.

Setting this property will automatically override any value previousy set to the scrollDuration property, and the scrollDuration property will be set to 0.0. Note that this is the rate at which the label would scroll if it moved at a constant speed - with other animation curves the rate will be slightly different.

Declared In

MarqueeLabel.h

scrollDuration

@property (nonatomic, assign) IBInspectable CGFloat scrollDuration
Discussion

Defines the duration of the scrolling animation.

This property sets the amount of time it will take for the scrolling animation to complete a scrolling cycle. Note that for MLLeftRight and MLRightLeft, a cycle consists of the animation away, a pause (if a delay is specified), and the animation back to the original position.

Setting this property will automatically override any value previously set to the rate property, and the rate property will be set to 0.0.

See Also

Declared In

MarqueeLabel.h

tapToScroll

@property (nonatomic, assign) IBInspectable BOOL tapToScroll
Discussion

A boolean property that sets whether the MarqueeLabel should only begin a scroll when tapped.

If this property is set to YES, the MarqueeLabel will begin a scroll animation cycle only when tapped. The label will not automatically being a scroll. This setting overrides the setting of the holdScrolling property.

Defaults to NO .

Warning: The label will not automatically scroll when this property is set to YES.

Declared In

MarqueeLabel.h

trailingBuffer

@property (nonatomic, assign) IBInspectable CGFloat trailingBuffer
Discussion

A buffer (offset) between the trailing edge of the label text and the label frame.

This property adds additional space (buffer) between the trailing edge of the label text and the label frame. The trailing edge is the edge of the label text facing away from the direction of scroll (i.e. the edge that animates offscreen last during scrolling).

Defaults to 0.

Note: For MLContinuous-type labels, the smallest value of leadingBuffer, ‘trailingBuffer, andfadeLength` is used as spacing between the two label instances. Zero is an allowable value for all three properties.

Note: The value set to this property has no effect when the labelize property is set to YES.

Availability

Available in 2.1.0 and later.

Declared In

MarqueeLabel.h

Class Methods

controllerLabelsShouldAnimate:

+ (void)controllerLabelsShouldAnimate:(UIViewController *)controller
Discussion

De-Labelizes all MarqueeLabel instances that have the specified view controller in their next responder chain.

This method sends an NSNotification to all MarqueeLabel instances with the specified view controller in their next responder chain. The labelize property of these MarqueeLabel instances will be set to NO .

Parameters

controller

The view controller for which all MarqueeLabel instances should be de-labelized.

Declared In

MarqueeLabel.h

controllerLabelsShouldLabelize:

+ (void)controllerLabelsShouldLabelize:(UIViewController *)controller
Discussion

Labelizes all MarqueeLabel instances that have the specified view controller in their next responder chain.

This method sends an NSNotification to all MarqueeLabel instances with the specified view controller in their next responder chain. The labelize property of these MarqueeLabel instances will be set to YES.

Parameters

controller

The view controller for which all MarqueeLabel instances should be labelized.

Declared In

MarqueeLabel.h

controllerViewAppearing:

+ (void)controllerViewAppearing:(UIViewController *)controller
Discussion

Restarts all MarqueeLabel instances that have the specified view controller in their next responder chain.

This method is intended to be placed in the viewDidAppear: method of view controllers, and sends an NSNotification to all MarqueeLabel instances with the specified view controller in their next responder chain. These instances will be automatically restarted.

Parameters

controller

The view controller that has appeared.

See Also

Declared In

MarqueeLabel.h

controllerViewDidAppear:

+ (void)controllerViewDidAppear:(UIViewController *)controller
Discussion

Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

Alternative to restartLabelsOfController:. This method is retained for backwards compatibility and future enhancements.

Parameters

controller

The view controller that has appeared.

Availability

Available in 1.2.7 and later.

Declared In

MarqueeLabel.h

controllerViewWillAppear:

+ (void)controllerViewWillAppear:(UIViewController *)controller
Discussion

Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

Alternative to restartLabelsOfController:. This method is retained for backwards compatibility and future enhancements.

Parameters

controller

The view controller that has appeared.

Availability

Available in 1.2.8 and later.

Declared In

MarqueeLabel.h

restartLabelsOfController:

+ (void)restartLabelsOfController:(UIViewController *)controller
Discussion

Convenience method to restart all MarqueeLabel instances that have the specified view controller in their next responder chain.

This method sends a NSNotification to all MarqueeLabel instances with the specified view controller in their next responder chain. The scrolling animation of these instances will be automatically restarted. This is equivalent to calling restartLabel on all affected instances.

There is currently no functional difference between this method and controllerViewDidAppear: or controllerViewWillAppear:. The methods may be used interchangeably.

Warning: View controllers that appear with animation (such as from underneath a modal-style controller) can cause some MarqueeLabel text position “jumping” when this method is used in viewDidAppear if scroll animations are already underway. Use this method inside viewWillAppear: instead to avoid this problem.

Warning: This method may not function properly if passed the parent view controller when using view controller containment.

Parameters

controller

The view controller that has appeared.

Availability

Available in 1.3.1 and later.

Declared In

MarqueeLabel.h

Instance Methods

initWithFrame:

- (instancetype)initWithFrame:(CGRect)frame
Discussion

Returns a newly initialized MarqueeLabel instance.

The default scroll duration of 7.0 seconds and fade length of 0.0 are used.

Parameters

frame

A rectangle specifying the initial location and size of the view in its superview’s coordinates. Text (for the given font, font size, etc.) that does not fit in this frame will automatically scroll.

Return Value

An initialized MarqueeLabel object or nil if the object couldn’t be created.

Declared In

MarqueeLabel.h

initWithFrame:duration:andFadeLength:

- (instancetype)initWithFrame:(CGRect)frame duration:(NSTimeInterval)scrollDuration andFadeLength:(CGFloat)fadeLength
Discussion

Returns a newly initialized MarqueeLabel instance with the specified scroll duration and edge transparency fade length.

You must specify a non-zero duration, and you cannot thereafter modify the duration.

Parameters

frame

A rectangle specifying the initial location and size of the view in its superview’s coordinates. Text (for the given font, font size, etc.) that does not fit in this frame will automatically scroll.

scrollDuration

A scroll duration the label scroll animation. Must be non-zero. This will be the duration that the animation takes for one-half of the scroll cycle in the case of left-right and right-left marquee types, and for one loop of a continuous marquee type.

fadeLength

A length of transparency fade at the left and right edges of the MarqueeLabel instance’s frame.

Return Value

An initialized MarqueeLabel object or nil if the object couldn’t be created.

Declared In

MarqueeLabel.h

initWithFrame:rate:andFadeLength:

- (instancetype)initWithFrame:(CGRect)frame rate:(CGFloat)pixelsPerSec andFadeLength:(CGFloat)fadeLength
Discussion

Returns a newly initialized MarqueeLabel instance with the specified scroll rate and edge transparency fade length.

You must specify a non-zero rate, and you cannot thereafter modify the rate.

Parameters

frame

A rectangle specifying the initial location and size of the view in its superview’s coordinates. Text (for the given font, font size, etc.) that does not fit in this frame will automatically scroll.

pixelsPerSec

A rate of scroll for the label scroll animation. Must be non-zero. Note that this will be the maximum rate for ease-type animation.

fadeLength

A length of transparency fade at the left and right edges of the MarqueeLabel instance’s frame.

Return Value

An initialized MarqueeLabel object or nil if the object couldn’t be created.

Declared In

MarqueeLabel.h

labelReturnedToHome:

- (void)labelReturnedToHome:(BOOL)finished
Discussion

Called when the label animation has finished, and the label is at the home position.

The default implementation of this method does nothing. Subclasses may override this method in order to perform any custom actions jas as the label animation completes, and before the next animation would begin (assuming the scroll conditions are met).

Warning: This method will be called, and the finished parameter will be NO, when any property changes are made that would cause the label scrolling to be automatically reset. This includes changes to label text and font/font size changes.

Parameters

finished

A Boolean that indicates whether or not the scroll animation actually finished before the completion handler was called.

Availability

Available in 1.5.0 and later.

Declared In

MarqueeLabel.h

labelWillBeginScroll

- (void)labelWillBeginScroll
Discussion

Called when the label animation is about to begin.

The default implementation of this method does nothing. Subclasses may override this method in order to perform any custom actions just as the label animation begins. This is only called in the event that the conditions for scrolling to begin are met.

Availability

Available in 1.5.0 and later.

Declared In

MarqueeLabel.h

minimizeLabelFrameWithMaximumSize:adjustHeight:

- (void)minimizeLabelFrameWithMaximumSize:(CGSize)maxSize adjustHeight:(BOOL)adjustHeight
Discussion

Resizes the view to the minimum size necessary to fully enclose the current text (i.e. without scrolling), up to the maximum size specified.

The current origin of the frame is retained.

Parameters

maxSize

The maximum size up to which the view should be resized. Passing CGSizeZero will result in no maximum size limit.

adjustHeight

A boolean that can be used to indicate if the view’s height should also be adjusted. Note that this has no impact on scrolling.

Declared In

MarqueeLabel.h

pauseLabel

- (void)pauseLabel
Discussion

Pauses the text scrolling animation, at any point during the animation.

See Also

Declared In

MarqueeLabel.h

resetLabel

- (void)resetLabel
Discussion

Resets the label text, recalculating the scroll animation.

The text is immediately returned to the home position, and the scroll animation positions are cleared. Scrolling will not resume automatically after a call to this method. To re-initiate scrolling, use either a call to restartLabel or make a change to a UILabel property such as text, bounds/frame, font, font size, etc.

See Also

Declared In

MarqueeLabel.h

restartLabel

- (void)restartLabel
Discussion

Immediately resets the label to the home position, and restarts the scroll animation if the appropriate conditions are met.

Declared In

MarqueeLabel.h

triggerScrollStart

- (void)triggerScrollStart
Discussion

Overrides any non-size condition which is preventing the receiver from automatically scrolling, and begins a scroll animation.

Currently the only non-size conditions which can prevent a label from scrolling are the tapToScroll and holdScrolling properties. This method will not force a label with a string that fits inside the label bounds (i.e. that would not automatically scroll) to begin a scroll animation.

Upon the completion of the first forced scroll animation, the receiver will not automatically continue to scroll unless the conditions preventing scrolling have been removed.

Note: This method has no effect if called during an already in-flight scroll animation.

Availability

Available in 2.2.0 and later.

See Also

Declared In

MarqueeLabel.h

unpauseLabel

- (void)unpauseLabel
Discussion

Un-pauses a previously paused text scrolling animation

See Also

Declared In

MarqueeLabel.h