Class: SC.ScrollView


Extends SC.View.

Implements a complete scroll view. SproutCore implements its own JS-based scrolling in order to unify scrolling behavior across platforms, and to enable progressive rendering (via the clipping frame) during scroll on all devices.

Important Properties

ScrollView positions its contentView according to three properties: verticalScrollOffset, horizontalScrollOffset, and scale. These properties are bindable and observable, but you should not override them.

Gutter vs. Overlaid Scrollers

Scroll views use swappable scroll-bar views with various behavior (see verticalScrollerView and horizontalScrollerView). SC.ScrollerView is a gutter-based scroller which persists and takes up fourteen pixels. (By default, no scroller is shown for content that is too small to scroll; see autohidesHorizontalScroller and autohidesVerticalScroller.) SC.OverlayScrollerView is a gutterless view which fades when not scrolling. If you would like your view to always have OS X-style fading overlaid scrollers, you can use the following:

SC.ScrollView.extend({
    horizontalOverlay: true,
    verticalOverlay: true
  });

Defined in: scroll_view.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.View:
acceptsFirstResponder, ariaHidden, ariaRole, attributeBindings, autoMixins, backgroundColor, childViewLayout, childViewLayoutOptions, childViews, childViewsNeedLayout, classNameBindings, concatenatedProperties, createdByParent, designMode, displayProperties, enabledState, firstKeyView, hasLayout, hasTouch, hasVisibility, isBuildingIn, isBuildingOut, isChildViewLayoutLive, isEnabled, isFixedHeight, isFixedPosition, isFixedSize, isFixedWidth, isKeyResponder, isTextSelectable, isView, isVisible, lastKeyView, layerLocationNeedsUpdate, layerNeedsUpdate, layout, modeAdjust, nextKeyView, page, pane, parentView, previousKeyView, renderDelegateName, shouldInheritCursor, shouldInheritEnabled, tagName, themeName, toolTip, touchBoundary, transitionAdjust, transitionAdjustOptions, transitionHide, transitionHideOptions, transitionIn, transitionInOptions, transitionOut, transitionOutOptions, transitionShow, transitionShowOptions, useStaticLayout
Fields borrowed from SC.Responder:
hasFirstResponder, isFirstResponder, responderContext
Fields borrowed from SC.Object:
isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:
isObservable

Instance Methods

Field Detail

acceptsMultitouch Boolean
Default value:
true
See:
SC.View.prototype.acceptsMultitouch
autohidesHorizontalScroller Boolean

If true, the horizontal scroller will automatically hide if the contentView is smaller than the visible area. The hasHorizontalScroller property must be set to true in order for this property to have any effect.

Default value:
true
autohidesVerticalScroller Boolean

If true, the vertical scroller will automatically hide if the contentView is smaller than the visible area. The hasVerticalScroller property must be set to true in order for this property to have any effect.

Default value:
true
canScale Boolean
Determines whether scaling is allowed.
Default value:
false
Read Only
canScrollHorizontal Boolean
Returns true if the view has both a horizontal scroller and the scroller is visible.
Read Only
canScrollVertical Boolean
Returns true if the view has both a vertical scroller and the scroller is visible.
classNames Array
Default value:
['sc-scroll-view']
See:
SC.View#classNames
containerView SC.ContainerView

The container view that will wrap your content view. You can replace this property with your own custom class if you prefer.

Default value:
SC.ContainerView
contentView SC.View
The content view you want the scroll view to manage.
Default value:
null
decelerationRate Number
The scroll deceleration rate.
Default value:
SC.SCROLL.DRAG_SCROLL_DECELERATION
fadeOutDelay
Determines how long (in seconds) scrollbars wait before fading out.
Default value:
0.4
hasHorizontalScroller Boolean

True if the view should maintain a horizontal scroller. This property must be set when the view is created.

Default value:
true
hasVerticalScroller Boolean

True if the view should maintain a vertical scroller. This property must be set when the view is created.

Default value:
true
horizontalAlign String

The horizontal alignment for non-filling content inside of the ScrollView. Possible values:

  • SC.ALIGN_LEFT
  • SC.ALIGN_RIGHT
  • SC.ALIGN_CENTER
Default value:
SC.ALIGN_CENTER
horizontalFade

Determines whether the horizontal scroller should fade out while in overlay mode. Has no effect if horizontalOverlay is set to false.

Default value:
true
horizontalLineScroll Number

Amount to scroll one horizontal line.

Used by the default implementation of scrollLeftLine() and scrollRightLine().

Default value:
20
horizontalOverlay Boolean

Use this to overlay the horizontal scroller.

This ensures that the content container will not resize to accommodate the horizontal scroller, hence overlaying the scroller on top of the container.

Default value:
true
horizontalPageScroll Number

Amount to scroll one horizontal page.

Used by the default implementation of scrollLeftPage() and scrollRightPage().

Default value:
value of frame.width
horizontalScrollerLayout Object

Use to control the positioning of the horizontal scroller. If you do not set 'horizontalOverlay' to true, then the content view will be automatically sized to meet the left edge of the vertical scroller, wherever it may be.

This allows you to easily, for example, have “one pixel higher and one pixel lower” scroll bars that blend into their parent views.

If you do set 'horizontalOverlay' to true, then the scroller view will “float on top” of the content view.

Example: { left: -1, bottom: 0, right: -1 }

Default value:
null
horizontalScrollerView SC.View

The horizontal scroller view class. This will be replaced with a view instance when the ScrollView is created unless hasHorizontalScroller is false.

If horizontalOverlay is true, the default view used will be an SC.OverlayScrollerView, otherwise SC.ScrollerView will be used.

Default value:
SC.ScrollerView | SC.OverlayScrollerView
horizontalScrollOffset Number

The current horizontal scroll offset. Changing this value will update both the position of the contentView and the horizontal scroller, if there is one.

Default value:
0
initialHorizontalAlign String

Your content view's initial horizontal alignment, if wider than the container. This allows you to e.g. center the content view when zoomed out, but begin with it zoomed in and left-aligned. If not specified, defaults to value of horizontalAlign. May be:

  • SC.ALIGN_LEFT
  • SC.ALIGN_RIGHT
  • SC.ALIGN_CENTER
Default value:
SC.ALIGN_LEFT
initialVerticalAlign String

Your content view's initial vertical alignment, if taller than the container. This allows you to e.g. center the content view when zoomed out, but begin with it zoomed in and top-aligned. If not specified, defaults to the value of verticalAlign. May be:

  • SC.ALIGN_TOP
  • SC.ALIGN_BOTTOM
  • SC.ALIGN_MIDDLE
Default value:
SC.ALIGN_TOP
isHorizontalScrollerVisible Boolean

True if the horizontal scroller should be visible. You can change this property value anytime to show or hide the horizontal scroller. If you do not want to use a horizontal scroller at all, you should instead set hasHorizontalScroller to false to avoid creating a scroller view in the first place.

Default value:
true
isScrollable Boolean
Walk like a duck.
Default value:
true
isVerticalScrollerVisible Boolean

True if the vertical scroller should be visible. You can change this property value anytime to show or hide the vertical scroller. If you do not want to use a vertical scroller at all, you should instead set hasVerticalScroller to false to avoid creating a scroller view in the first place.

Default value:
true
maximumHorizontalScrollOffset Number

The maximum horizontal scroll offset allowed given the current contentView size and the size of the scroll view. If horizontal scrolling is disabled, this will always return 0.

Default value:
0
maximumScale Number
The maximum scale.
Default value:
2.0
maximumVerticalScrollOffset Number

The maximum vertical scroll offset allowed given the current contentView size and the size of the scroll view. If vertical scrolling is disabled, this will always return 0 (or whatever alignment dictates).

Default value:
0
minimumHorizontalScrollOffset Number

The minimum horizontal scroll offset allowed given the current contentView size and the size of the scroll view. If horizontal scrolling is disabled, this will always return 0 (or whatever alignment dictates).

Default value:
0
minimumScale Number
The minimum scale.
Default value:
0.25
minimumVerticalScrollOffset Number

The minimum vertical scroll offset allowed given the current contentView size and the size of the scroll view. If vertical scrolling is disabled, this will always return 0 (or whatever alignment dictates).

Default value:
0
scale Number

The current scale. Setting this will adjust the scale of the contentView.

If the contentView implements the SC.Scalable protocol, it will instead pass the scale to the contentView's applyScale method instead.

Note that on platforms that allow bounce, setting scale outside of the minimum/maximumScale bounds will result in a bounce. It is up to the developer to alert this view when the action is over and it should bounce back.

Default value:
1.0
scaleGestureThreshold Number

This determines how much a gesture must pinch or spread apart (in pixels) before it is registered as a scale action.

You can change this value for all instances of SC.ScrollView in your application by overriding SC.SCROLL.SCALE_GESTURE_THRESHOLD at launch time.

Default value:
SC.SCROLL.SCALE_GESTURE_THRESHOLD
scrollGestureThreshold Number

This determines how far (in pixels) a gesture must move before it is registered as a scroll.

You can change this value for all instances of SC.ScrollView in your application by overriding SC.SCROLL.SCROLL_THRESHOLD at launch time.

Default value:
SC.SCROLL.SCROLL_GESTURE_THRESHOLD
scrollLockGestureThreshold Number

Once a vertical or horizontal scroll has been triggered, this determines how far (in pixels) the gesture must move on the other axis to trigger a two-axis scroll. If your scroll view's content is omnidirectional (e.g. a map) you should set this value to 0.

You can change this value for all instances of SC.ScrollView in your application by overriding SC.SCROLL.SCROLL_LOCK_GESTURE_THRESHOLD at launch time.

Default value:
SC.SCROLL.SCROLL_LOCK_GESTURE_THRESHOLD
verticalAlign String

The vertical alignment for non-filling content inside of the ScrollView. Possible values:

  • SC.ALIGN_TOP
  • SC.ALIGN_BOTTOM
  • SC.ALIGN_MIDDLE
Default value:
SC.ALIGN_TOP
verticalFade

Determines whether the vertical scroller should fade out while in overlay mode. Has no effect if verticalOverlay is set to false.

Default value:
true
verticalLineScroll Number

Amount to scroll one vertical line.

Used by the default implementation of scrollDownLine() and scrollUpLine().

Default value:
20
verticalOverlay Boolean

Use this to overlay the vertical scroller.

This ensures that the content container will not resize to accommodate the vertical scroller, hence overlaying the scroller on top of the container.

Default value:
true
verticalPageScroll Number

Amount to scroll one vertical page.

Used by the default implementation of scrollUpPage() and scrollDownPage().

Default value:
value of frame.height
verticalScrollerLayout Object

Use to control the positioning of the vertical scroller. If you do not set 'verticalOverlay' to true, then the content view will be automatically sized to meet the left edge of the vertical scroller, wherever it may be.

This allows you to easily, for example, have “one pixel higher and one pixel lower” scroll bars that blend into their parent views.

If you do set 'verticalOverlay' to true, then the scroller view will “float on top” of the content view.

Example: { top: -1, bottom: -1, right: 0 }

Default value:
null
verticalScrollerView SC.View

The vertical scroller view class. This will be replaced with a view instance when the ScrollView is created unless hasVerticalScroller is false.

If verticalOverlay is true, the default view used will be an SC.OverlayScrollerView, otherwise SC.ScrollerView will be used.

Default value:
SC.ScrollerView | SC.OverlayScrollerView
verticalScrollOffset Number

The current vertical scroll offset. Changing this value will update both the position of the contentView and the vertical scroller, if there is one.

Default value:
0

Instance Method Detail

init()
SC.Object.prototype
scrollBy(x, y)

Scrolls the receiver in the horizontal and vertical directions by the amount specified, if allowed. The actual scroll amount will be constrained by the current scroll minimums and maximums. (If you wish to scroll outside of those bounds, you should call scrollTo directly.)

If you only want to scroll in one direction, pass null or 0 for the other direction.

Parameters:
x Number
change in the x direction (or hash)
y Number
change in the y direction
Returns:
SC.ScrollView
receiver
scrollDownLine(lines)

Scrolls the receiver down one or more lines if allowed. If number of lines is not specified, scrolls one line.

Parameters:
lines Number
number of lines
Returns:
SC.ScrollView
receiver
scrollDownPage(pages)

Scrolls the receiver down one or more page if allowed. If number of pages is not specified, scrolls one page. The page size is determined by the verticalPageScroll value. By default this is the size of the current scrollable area.

Parameters:
pages Number
number of lines
Returns:
SC.ScrollView
receiver
scrollLeftLine(lines)

Scrolls the receiver left one or more lines if allowed. If number of lines is not specified, scrolls one line.

Parameters:
lines Number
number of lines
Returns:
SC.ScrollView
receiver
scrollLeftPage(pages)

Scrolls the receiver left one or more page if allowed. If number of pages is not specified, scrolls one page. The page size is determined by the verticalPageScroll value. By default this is the size of the current scrollable area.

Parameters:
pages Number
number of lines
Returns:
SC.ScrollView
receiver
scrollRightLine(lines)

Scrolls the receiver right one or more lines if allowed. If number of lines is not specified, scrolls one line.

Parameters:
lines Number
number of lines
Returns:
SC.ScrollView
receiver
scrollRightPage(pages)

Scrolls the receiver right one or more page if allowed. If number of pages is not specified, scrolls one page. The page size is determined by the verticalPageScroll value. By default this is the size of the current scrollable area.

Parameters:
pages Number
number of lines
Returns:
SC.ScrollView
receiver
scrollTo(x, y)

Scrolls to the specified x,y coordinates. This should be the offset into the contentView that you want to appear at the top-left corner of the scroll view.

This method will contain the actual scroll based on whether the view can scroll in the named direction and the maximum distance it can scroll.

If you only want to scroll in one direction, pass null for the other direction.

Parameters:
x Number
the x scroll location
y Number
the y scroll location
Returns:
SC.ScrollView
receiver
scrollToRect(rect)

Scroll to the supplied rectangle.

If the rectangle is bigger than the viewport, the top-left will be preferred.

(Note that if your content is scaled, the rectangle must be relative to the contentView's scale, not the ScrollView's.)

Parameters:
rect Rect
Rectangle to which to scroll.
Returns:
Boolean
YES if scroll position was changed.
scrollToVisible(view)

Scroll the view to make the view's frame visible. For this to make sense, the view should be a subview of the contentView. Otherwise the results will be undefined.

Parameters:
view SC.View
view to scroll or null to scroll receiver visible
Returns:
Boolean
YES if scroll position was changed
scrollUpLine(lines)

Scrolls the receiver up one or more lines if allowed. If number of lines is not specified, scrolls one line.

Parameters:
lines Number
number of lines
Returns:
SC.ScrollView
receiver
scrollUpPage(pages)

Scrolls the receiver up one or more page if allowed. If number of pages is not specified, scrolls one page. The page size is determined by the verticalPageScroll value. By default this is the size of the current scrollable area.

Parameters:
pages Number
number of lines
Returns:
SC.ScrollView
receiver
touchStart(touch)
Parameters:
touch
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)