UIScrollView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UIScrollView.h
Related sample code

Overview

The UIScrollView class provides support for displaying content that is larger than the size of the application’s window. It enables users to scroll within that content by making swiping gestures, and to zoom in and back from portions of the content by making pinching gestures.

UIScrollView is the superclass of several UIKit classes including UITableView and UITextView.

The central notion of a UIScrollView object (or, simply, a scroll view) is that it is a view whose origin is adjustable over the content view. It clips the content to its frame, which generally (but not necessarily) coincides with that of the application’s main window. A scroll view tracks the movements of fingers and adjusts the origin accordingly. The view that is showing its content “through” the scroll view draws that portion of itself based on the new origin, which is pinned to an offset in the content view. The scroll view itself does no drawing except for displaying vertical and horizontal scroll indicators. The scroll view must know the size of the content view so it knows when to stop scrolling; by default, it “bounces” back when scrolling exceeds the bounds of the content.

The object that manages the drawing of content displayed in a scroll view should tile the content’s subviews so that no view exceeds the size of the screen. As users scroll in the scroll view, this object should add and remove subviews as necessary.

Because a scroll view has no scroll bars, it must know whether a touch signals an intent to scroll versus an intent to track a subview in the content. To make this determination, it temporarily intercepts a touch-down event by starting a timer and, before the timer fires, seeing if the touching finger makes any movement. If the timer fires without a significant change in position, the scroll view sends tracking events to the touched subview of the content view. If the user then drags their finger far enough before the timer elapses, the scroll view cancels any tracking in the subview and performs the scrolling itself. Subclasses can override the touchesShouldBegin:withEvent:inContentView:, pagingEnabled, and touchesShouldCancelInContentView: methods (which are called by the scroll view) to affect how the scroll view handles scrolling gestures.

A scroll view also handles zooming and panning of content. As the user makes a pinch-in or pinch-out gesture, the scroll view adjusts the offset and the scale of the content. When the gesture ends, the object managing the content view should should update subviews of the content as necessary. (Note that the gesture can end and a finger could still be down.) While the gesture is in progress, the scroll view does not send any tracking calls to the subview.

The UIScrollView class can have a delegate that must adopt the UIScrollViewDelegate protocol. For zooming and panning to work, the delegate must implement both viewForZoomingInScrollView: and scrollViewDidEndZooming:withView:atScale:; in addition, the maximum (maximumZoomScale) and minimum ( minimumZoomScale) zoom scale must be different.

For information about basic view behaviors, see View Programming Guide for iOS.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it attempts to preserve its scrolling-related information between app launches. Specifically, the values of the zoomScale, contentInset, and contentOffset properties are preserved. During restoration, the scroll view restores these values so that the content appears scrolled to the same position as before. For more information about how state preservation and restoration works, see iOS App Programming Guide.

For more information about appearance and behavior configuration, see “Scroll Views”.

Tasks

Managing the Display of Content

Managing Scrolling

Managing the Scroll Indicator

Zooming and Panning

Managing the Delegate

Managing the Keyboard

Properties

alwaysBounceHorizontal

A Boolean value that determines whether bouncing always occurs when horizontal scrolling reaches the end of the content view.

@property(nonatomic) BOOL alwaysBounceHorizontal
Discussion

If this property is set to YES and bounces is YES, horizontal dragging is allowed even if the content is smaller than the bounds of the scroll view. The default value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

alwaysBounceVertical

A Boolean value that determines whether bouncing always occurs when vertical scrolling reaches the end of the content.

@property(nonatomic) BOOL alwaysBounceVertical
Discussion

If this property is set to YES and bounces is YES, vertical dragging is allowed even if the content is smaller than the bounds of the scroll view. The default value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

bounces

A Boolean value that controls whether the scroll view bounces past the edge of content and back again.

@property(nonatomic) BOOL bounces
Discussion

If the value of this property is YES, the scroll view bounces when it encounters a boundary of the content. Bouncing visually indicates that scrolling has reached an edge of the content. If the value is NO, scrolling stops immediately at the content boundary without bouncing. The default value is YES.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

bouncesZoom

A Boolean value that determines whether the scroll view animates the content scaling when the scaling exceeds the maximum or minimum limits.

@property(nonatomic) BOOL bouncesZoom
Discussion

If the value of this property is YES and zooming exceeds either the maximum or minimum limits for scaling, the scroll view temporarily animates the content scaling just past these limits before returning to them. If this property is NO, zooming stops immediately at one a scaling limits. The default is YES .

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

canCancelContentTouches

A Boolean value that controls whether touches in the content view always lead to tracking.

@property(nonatomic) BOOL canCancelContentTouches
Discussion

If the value of this property is YES and a view in the content has begun tracking a finger touching it, and if the user drags the finger enough to initiate a scroll, the view receives a touchesCancelled:withEvent: message and the scroll view handles the touch as a scroll. If the value of this property is NO, the scroll view does not scroll regardless of finger movement once the content view starts tracking.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

contentInset

The distance that the content view is inset from the enclosing scroll view.

@property(nonatomic) UIEdgeInsets contentInset
Discussion

Use this property to add to the scrolling area around the content. The unit of size is points. The default value is UIEdgeInsetsZero.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

contentOffset

The point at which the origin of the content view is offset from the origin of the scroll view.

@property(nonatomic) CGPoint contentOffset
Discussion

The default value is CGPointZero.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

contentSize

The size of the content view.

@property(nonatomic) CGSize contentSize
Discussion

The unit of size is points. The default size is CGSizeZero.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

decelerating

Returns whether the content is moving in the scroll view after the user lifted their finger. (read-only)

@property(nonatomic, readonly, getter=isDecelerating) BOOL decelerating
Discussion

The returned value is YES if user isn't dragging the content but scrolling is still occurring.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

decelerationRate

A floating-point value that determines the rate of deceleration after the user lifts their finger.

@property(nonatomic) CGFloat decelerationRate
Discussion

Your application can use the UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast constants as reference points for reasonable deceleration rates.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIScrollView.h

delaysContentTouches

A Boolean value that determines whether the scroll view delays the handling of touch-down gestures.

@property(nonatomic) BOOL delaysContentTouches
Discussion

If the value of this property is YES, the scroll view delays handling the touch-down gesture until it can determine if scrolling is the intent. If the value is NO , the scroll view immediately calls touchesShouldBegin:withEvent:inContentView:. The default value is YES.

See the class description for a fuller discussion.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

delegate

The delegate of the scroll-view object.

@property(nonatomic, assign) id<UIScrollViewDelegate> delegate
Discussion

The delegate must adopt the UIScrollViewDelegate protocol. The UIScrollView class, which does not retain the delegate, invokes each protocol method the delegate implements.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScrollView.h

directionalLockEnabled

A Boolean value that determines whether scrolling is disabled in a particular direction.

@property(nonatomic, getter=isDirectionalLockEnabled) BOOL directionalLockEnabled
Discussion

If this property is NO, scrolling is permitted in both horizontal and vertical directions. If this property is YES and the user begins dragging in one general direction (horizontally or vertically), the scroll view disables scrolling in the other direction. If the drag direction is diagonal, then scrolling will not be locked and the user can drag in any direction until the drag completes. The default value is NO

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

dragging

A Boolean value that indicates whether the user has begun scrolling the content. (read-only)

@property(nonatomic, readonly, getter=isDragging) BOOL dragging
Discussion

The value held by this property might require some time or distance of scrolling before it is set to YES.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIScrollView.h

indicatorStyle

The style of the scroll indicators.

@property(nonatomic) UIScrollViewIndicatorStyle indicatorStyle
Discussion

The default style is UIScrollViewIndicatorStyleDefault. See “Scroll Indicator Style” for descriptions of these constants.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

keyboardDismissMode

The manner in which the keyboard is dismissed when a drag begins in the scroll view.

@property(nonatomic) UIScrollViewKeyboardDismissMode keyboardDismissMode
Discussion

See “UIScrollViewKeyboardDismissMode” for possible values. The default value is UIScrollViewKeyboardDismissModeNone.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIScrollView.h

maximumZoomScale

A floating-point value that specifies the maximum scale factor that can be applied to the scroll view's content.

@property(nonatomic) CGFloat maximumZoomScale
Discussion

This value determines how large the content can be scaled. It must be greater than the minimum zoom scale for zooming to be enabled. The default value is 1.0.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScrollView.h

minimumZoomScale

A floating-point value that specifies the minimum scale factor that can be applied to the scroll view's content.

@property(nonatomic) CGFloat minimumZoomScale
Discussion

This value determines how small the content can be scaled. The default value is 1.0

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

pagingEnabled

A Boolean value that determines whether paging is enabled for the scroll view.

@property(nonatomic, getter=isPagingEnabled) BOOL pagingEnabled
Discussion

If the value of this property is YES, the scroll view stops on multiples of the scroll view’s bounds when the user scrolls. The default value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

panGestureRecognizer

The underlying gesture recognizer for pan gestures. (read-only)

@property(nonatomic, readonly) UIPanGestureRecognizer *panGestureRecognizer
Discussion

Your application accesses this property when it wants to more precisely control which pan gestures are recognized by the scroll view.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIScrollView.h

pinchGestureRecognizer

The underlying gesture recognizer for pinch gestures. (read-only)

@property(nonatomic, readonly) UIPinchGestureRecognizer *pinchGestureRecognizer
Discussion

Your application accesses this property when it wants to more precisely control which pinch gestures are recognized by the scroll view.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIScrollView.h

scrollEnabled

A Boolean value that determines whether scrolling is enabled.

@property(nonatomic, getter=isScrollEnabled) BOOL scrollEnabled
Discussion

If the value of this property is YES , scrolling is enabled, and if it is NO , scrolling is disabled. The default is YES.

When scrolling is disabled, the scroll view does not accept touch events; it forwards them up the responder chain.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

scrollIndicatorInsets

The distance the scroll indicators are inset from the edge of the scroll view.

@property(nonatomic) UIEdgeInsets scrollIndicatorInsets
Discussion

The default value is UIEdgeInsetsZero.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

scrollsToTop

A Boolean value that controls whether the scroll-to-top gesture is enabled.

@property(nonatomic) BOOL scrollsToTop
Discussion

The scroll-to-top gesture is a tap on the status bar. When a user makes this gesture, the system asks the scroll view closest to the status bar to scroll to the top. If that scroll view has scrollsToTop set to NO, its delegate returns NO from scrollViewShouldScrollToTop:, or the content is already at the top, nothing happens.

After the scroll view scrolls to the top of the content view, it sends the delegate a scrollViewDidScrollToTop: message.

The default value of scrollsToTop is YES.

Special Considerations

On iPhone, the scroll-to-top gesture has no effect if there is more than one scroll view on-screen that has scrollsToTop set to YES.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

showsHorizontalScrollIndicator

A Boolean value that controls whether the horizontal scroll indicator is visible.

@property(nonatomic) BOOL showsHorizontalScrollIndicator
Discussion

The default value is YES. The indicator is visible while tracking is underway and fades out after tracking.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScrollView.h

showsVerticalScrollIndicator

A Boolean value that controls whether the vertical scroll indicator is visible.

@property(nonatomic) BOOL showsVerticalScrollIndicator
Discussion

The default value is YES. The indicator is visible while tracking is underway and fades out after tracking.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScrollView.h

tracking

Returns whether the user has touched the content to initiate scrolling. (read-only)

@property(nonatomic, readonly, getter=isTracking) BOOL tracking
Discussion

The value of this property is YES if the user has touched the content view but might not have yet have started dragging it.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIScrollView.h

zoomBouncing

A Boolean value that indicates that zooming has exceeded the scaling limits specified for the receiver. (read-only)

@property(nonatomic, readonly, getter=isZoomBouncing) BOOL zoomBouncing
Discussion

The value of this property is YES if the scroll view is zooming back to a minimum or maximum zoom scaling value; otherwise the value is NO .

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

zooming

A Boolean value that indicates whether the content view is currently zooming in or out. (read-only)

@property(nonatomic, readonly, getter=isZooming) BOOL zooming
Discussion

The value of this property is YES if user is making a zoom gesture, otherwise it is NO .

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

zoomScale

A floating-point value that specifies the current scale factor applied to the scroll view's content.

@property(nonatomic) CGFloat zoomScale
Discussion

This value determines how much the content is currently scaled. The default value is 1.0.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIScrollView.h

Instance Methods

flashScrollIndicators

Displays the scroll indicators momentarily.

- (void)flashScrollIndicators
Discussion

You should call this method whenever you bring the scroll view to front.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

scrollRectToVisible:animated:

Scrolls a specific area of the content so that it is visible in the receiver.

- (void)scrollRectToVisible:(CGRect)rect animated:(BOOL)animated
Parameters
rect

A rectangle defining an area of the content view. The rectangle should be in the coordinate space of the scroll view.

animated

YES if the scrolling should be animated, NO if it should be immediate.

Discussion

This method scrolls the content view so that the area defined by rect is just visible inside the scroll view. If the area is already visible, the method does nothing.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

setContentOffset:animated:

Sets the offset from the content view’s origin that corresponds to the receiver’s origin.

- (void)setContentOffset:(CGPoint)contentOffset animated:(BOOL)animated
Parameters
contentOffset

A point (expressed in points) that is offset from the content view’s origin.

animated

YES to animate the transition at a constant velocity to the new offset, NO to make the transition immediate.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScrollView.h

setZoomScale:animated:

A floating-point value that specifies the current zoom scale.

- (void)setZoomScale:(CGFloat)scale animated:(BOOL)animated
Parameters
scale

The new value to scale the content to.

animated

YES to animate the transition to the new scale, NO to make the transition immediate.

Discussion

The new scale value should be between the minimumZoomScale and the maximumZoomScale.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIScrollView.h

touchesShouldBegin:withEvent:inContentView:

Overridden by subclasses to customize the default behavior when a finger touches down in displayed content.

- (BOOL)touchesShouldBegin:(NSSet *)touches withEvent:(UIEvent *)event inContentView:(UIView *)view
Parameters
touches

A set of UITouch instances that represent the touches for the starting phase of the event represented by event.

event

An object representing the event to which the touch objects in touches belong.

view

The subview in the content where the touch-down gesture occurred.

Return Value

Return NO if you don’t want the scroll view to send event messages to view. If you want view to receive those messages, return YES (the default).

Discussion

The default behavior of UIScrollView is to invoke the UIResponder event-handling methods of the target subview that the touches occur in.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

touchesShouldCancelInContentView:

Returns whether to cancel touches related to the content subview and start dragging.

- (BOOL)touchesShouldCancelInContentView:(UIView *)view
Parameters
view

The view object in the content that is being touched.

Return Value

YES to cancel further touch messages to view, NO to have view continue to receive those messages. The default returned value is YES if view is not a UIControl object; otherwise, it returns NO.

Discussion

The scroll view calls this method just after it starts sending tracking messages to the content view. If it receives NO from this method, it stops dragging and forwards the touch events to the content subview. The scroll view does not call this method if the value of the canCancelContentTouches property is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScrollView.h

zoomToRect:animated:

Zooms to a specific area of the content so that it is visible in the receiver.

- (void)zoomToRect:(CGRect)rect animated:(BOOL)animated
Parameters
rect

A rectangle defining an area of the content view. The rectangle should be in the coordinate space of the view returned by viewForZoomingInScrollView:.

animated

YES if the scrolling should be animated, NO if it should be immediate.

Discussion

This method zooms so that the content view becomes the area defined by rect, adjusting the zoomScale as necessary.

Availability
  • Available in iOS 3.0 and later.
Declared In
UIScrollView.h

Constants

Scroll Indicator Style

The style of the scroll indicators. You use these constants to set the value of the indicatorStyle style.

typedef enum : NSInteger {
   UIScrollViewIndicatorStyleDefault,
   UIScrollViewIndicatorStyleBlack,
   UIScrollViewIndicatorStyleWhite
} UIScrollViewIndicatorStyle;
Constants
UIScrollViewIndicatorStyleDefault

The default style of scroll indicator, which is black with a white border. This style is good against any content background.

Available in iOS 2.0 and later.

Declared in UIScrollView.h.

UIScrollViewIndicatorStyleBlack

A style of indicator which is black and smaller than the default style. This style is good against a white content background.

Available in iOS 2.0 and later.

Declared in UIScrollView.h.

UIScrollViewIndicatorStyleWhite

A style of indicator is white and smaller than the default style. This style is good against a black content background.

Available in iOS 2.0 and later.

Declared in UIScrollView.h.

Deceleration Constants

The rate of deceleration for a scrolling view.

const float UIScrollViewDecelerationRateNormal;
const float UIScrollViewDecelerationRateFast;
Constants
UIScrollViewDecelerationRateNormal

The default deceleration rate for a scroll view.

Available in iOS 3.0 and later.

Declared in UIScrollView.h.

UIScrollViewDecelerationRateFast

A fast deceleration rate for a scroll view.

Available in iOS 3.0 and later.

Declared in UIScrollView.h.

UIScrollViewKeyboardDismissMode

The manner in which the keyboard is dismissed when a drag begins in the scroll view.

typedef enum : NSInteger {
   UIScrollViewKeyboardDismissModeNone,
   UIScrollViewKeyboardDismissModeOnDrag,
   UIScrollViewKeyboardDismissModeInteractive
}UIScrollViewKeyboardDismissMode;
Constants
UIScrollViewKeyboardDismissModeNone

The keyboard does not get dismissed with a drag.

Available in iOS 7.0 and later.

Declared in UIScrollView.h.

UIScrollViewKeyboardDismissModeOnDrag

The keyboard is dismissed when a drag begins.

Available in iOS 7.0 and later.

Declared in UIScrollView.h.

UIScrollViewKeyboardDismissModeInteractive

The keyboard follows the dragging touch offscreen, and can be pulled upward again to cancel the dismiss.

Available in iOS 7.0 and later.

Declared in UIScrollView.h.