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)