Titanium Mobile

# Titanium.UI.ScrollView

A view that contains a horizontally and/or vertically-scrollable region of content.

Availability
0.9
0.9
9.2.0
Extends
Titanium.UI.View

# Overview

Use the Titanium.UI.createScrollView method or <ScrollView> Alloy element to create a scroll view.

Views added to the scroll view will be scrolled based on the size of the scrollable region of content. If a scrollable region fits within the size of its scroll view, the view will not scroll.

# Android Platform Notes

On Android, a scroll view can only scroll in one direction, either vertically or horizontally, and not both at the same time. The Titanium.UI.ScrollView.scrollType property sets the scroll direction explicitly. If the scrollType property is not assigned a value, the scroll view attempts to determine the scroll direction based on some the following rules:

Pinching a ScrollableView to zoom in and out of content is not supported on Android. On iOS, this action is natively supported by the UIScrollView class, but on Android, the native ScrollView class does not support this action.

# Examples

# Simple Scroll View

Create a scroll view with content.

var win = Ti.UI.createWindow({
  backgroundColor: 'white',
  exitOnClose: true,
  fullscreen: false,
  title: 'ScrollView Demo'
});

var scrollView = Ti.UI.createScrollView({
  showVerticalScrollIndicator: true,
  showHorizontalScrollIndicator: true,
  height: '80%',
  width: '80%'
});
var view = Ti.UI.createView({
  backgroundColor:'#336699',
  borderRadius: 10,
  top: 10,
  height: 2000,
  width: 1000
});
scrollView.add(view);
win.add(scrollView);
win.open();

# Scroll View as a Table View

Create a scroll view that contains a set of views in a layout to resemble a table view with rows. This approach can mitigate the native Android issue described in the "TextFields in Tables with SOFT_INPUT_ADJUST_PAN" section of Titanium.UI.TableView.

var win = Ti.UI.createWindow({
  backgroundColor:'white'
});

if (Ti.UI.Android){
  win.windowSoftInputMode = Ti.UI.Android.SOFT_INPUT_ADJUST_PAN;
}

function createRow(i) {
  var row = Ti.UI.createView({
    backgroundColor: 'white',
    borderColor: '#bbb',
    borderWidth: 1,
    width:'100%', height: 70,
    top: 0, left: 0
  });
  var inputTextField = Ti.UI.createTextField({
    hintText: 'Enter value ' + i,
    keyboardType: Ti.UI.KEYBOARD_NUMBERS_PUNCTUATION,
    top: 10, left: '10%',
    width: '80%', height: 60
  });
  row.add(inputTextField);
  return row;
}

var scrollView = Ti.UI.createScrollView({
  bottom:120,
  layout: 'vertical'
});

for(var i = 0; i <= 20; i++){
var row = createRow(i);
  scrollView.add(row);
}
win.add(scrollView);

var label = Ti.UI.createLabel({
  backgroundColor:'darkgray',
  text: 'Your advert here',
  textAlign: 'center',
  bottom:0,
  width: Titanium.UI.FILL,
  height:100
});
win.add(label);
win.open();

# Alloy XML Markup

Previous simple scroll view example as an Alloy view.

<Alloy>
    <Window id="win" backgroundColor="white" exitOnClose="true" fullscreen="false" title="ScrollView Demo">
        <ScrollView id="scrollView" showVerticalScrollIndicator="true" showHorizontalScrollIndicator="true" height="80%" width="80%">
            <View id="view" backgroundColor="#336699" borderRadius="10" top="10" height="2000" width="1000" />
        </ScrollView>
    </Window>
</Alloy>

# Properties

# canCancelEvents

Availability
0.9
0.9
9.2.0
canCancelEvents :Boolean

Determines whether this scroll view can cancel subview touches in order to scroll instead.

On iOS, this property maps to the native canCancelContentTouches property which controls whether touches in the content view always lead to tracking. See UIScrollView for more details.

On Android, setting this property to false prevents the scroll view from intercepting any touch events from its subviews. Note that this behavior may be slightly different from iOS.

Default: true

# contentHeight

Availability
0.9
0.9
9.2.0
contentHeight :Number | String

Height of the scrollable region.

While absolute dimensions are supported, relative values, such as those provided in percentages, are not. The minimum value for contentHeight is the height of the scroll view. Measured in platform-specific units; pixels on Android, effective pixels on Windows and density-independent pixels (dip) on iOS.

# contentOffset

Availability
0.9
0.9
9.2.0
contentOffset :Point

X and Y coordinates to which to reposition the top-left point of the scrollable region.

On iOS, a new value causes the scroll view to perform an animated scroll to the new offset. The setContentOffset method can be used to prevent this animation.

# contentWidth

Availability
0.9
0.9
9.2.0
contentWidth :Number | String

Width of the scrollable region.

While absolute dimensions are supported, relative values, such as those provided in percentages, are not. The minimum value for contentWidth is the width of the scroll view. Measured in platform-specific units; pixels on Android, effective pixels on Windows and density-independent pixels (dip) on iOS.

# decelerationRate

Availability
3.2.3
9.2.0
decelerationRate :Number

The deceleration rate of the ScrollView.

This API can be assigned the following constants:

Default: Undefined.

# disableBounce

Availability
0.9
9.2.0
disableBounce :Boolean

Determines whether scroll bounce of the scrollable region is enabled.

Set to true to disable horizontal and vertical bounce.

This property takes precedence over the horizontalBounce and verticalBounce properties.

Default: false

# horizontalBounce

Availability
0.9
9.2.0
horizontalBounce :Boolean

Determines whether horizontal scroll bounce of the scrollable region is enabled.

With the default value of true, dragging in the horizontal direction is always allowed and also bounces.

Set to false to disable horizontal scroll bounce if the horizontal content is smaller than the scroll view bounds. However, larger content will still bounce when scrolled.

Note that the disableBounce property takes precedence over the horizontalBounce and verticalBounce properties.

Default: true

# keyboardDismissMode

Availability
6.0.0
9.2.0
keyboardDismissMode :Number

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

This API can be assigned the following constants:

Default: Undefined (behaves like Titanium.UI.iOS.KEYBOARD_DISMISS_MODE_NONE)

# maxZoomScale

Availability
0.9
9.2.0
maxZoomScale :Number

Maximum scaling factor of the scrollable region and its content.

This value determines how large the content can be scaled. It must be greater than the minZoomScale for zooming to be enabled. The default value is 1.0 unless otherwise specified.

Note that specifying a value less than or equal to 0 will hide all contents of the scroll view.

Default: 1

# minZoomScale

Availability
0.9
9.2.0
minZoomScale :Number

Minimum scaling factor of the scrollable region and its content.

This value determines how small the content can be scaled. It must be less than the maxZoomScale for zooming to be enabled. The default value is 1.0 unless otherwise specified.

Default: 1

# overScrollMode

Availability
3.1.0
overScrollMode :Number

Determines the behavior when the user overscolls the view.

This API can be assigned the following constants:

Default: Titanium.UI.Android.OVER_SCROLL_ALWAYS

# refreshControl

Availability
6.3.0
6.0.0
9.2.0
refreshControl :Titanium.UI.RefreshControl

View positioned above the first row that is only revealed when the user drags the scroll view contents down.

An alternate to the pullView property. See Titanium.UI.RefreshControl for usage and examples. Since Titanium SDK 7.5.0, the RefreshControl API is also available on iOS < 10.

# scrollIndicatorStyle

Availability
0.9
9.2.0
scrollIndicatorStyle :Number

Style of the scrollbar.

This API can be assigned the following constants:

Default: Titanium.UI.iOS.ScrollIndicatorStyle.DEFAULT

# scrollingEnabled

Availability
3.0.0
3.0.0
9.2.0
scrollingEnabled :Boolean

Determines whether scrolling is enabled for the view.

Default: true

# scrollsToTop

Availability
2.0.0
9.2.0
scrollsToTop :Boolean

Controls whether the scroll-to-top gesture is effective.

The scroll-to-top gesture is a tap on the status bar; The default value of this property is true. This gesture works when you have a single visible scroll view. If there are multiple table views, web views, text areas, and/or scroll views visible, you will need to disable (set to false) on the above views that you don't want this behaviour on. The remaining view will then respond to scroll-to-top gesture.

Default: true

# scrollType CREATION ONLY

Availability
0.9
scrollType :String

Limits the direction of the scrollable region, overriding the deduced setting. Set to horizontal or vertical.

See the Titanium.UI.ScrollView description for more details about how the scroll direction is deduced when this property is not defined.

# showHorizontalScrollIndicator

Availability
0.9
0.9
9.2.0
showHorizontalScrollIndicator :Boolean

Determines whether the horizontal scroll indicator is visible.

Set to true to show the horizontal scroll indicator.

Default: false

# showVerticalScrollIndicator

Availability
0.9
0.9
9.2.0
showVerticalScrollIndicator :Boolean

Determines whether the vertical scroll indicator is visible.

Set to true to show the vertical scroll indicator.

Default: false

# verticalBounce

Availability
0.9
9.2.0
verticalBounce :Boolean

Determines whether vertical scroll bounce of the scrollable region is enabled.

With the default value of true, dragging in the vertical direction is always allowed and also bounces.

Set to false to disable vertical scroll bounce if the vertical content is smaller than the scroll view bounds. However, larger content will still bounce when scrolled.

Note that the disableBounce property takes precedence over the horizontalBounce and verticalBounce properties.

Default: true

# zoomScale

Availability
0.9
9.2.0
zoomScale :Number

Scaling factor of the scroll view's content.

This value is bound by the minZoomScale and maxZoomScale properties.

Default: 1

# Methods

# scrollTo

Availability
0.9
0.9
9.2.0
scrollTo(x, y[, options]) → void

Moves the specified coordinate of the scrollable region into the viewable area.

Parameters

Name Type Description
x Number

X coordinate from the scrollable region's coordinate system.

y Number

Y coordinate from the scrollable region's coordinate system.

options AnimatedOptions

A simple object for specifying the animation properties when scrolling the view (since SDK 6.1.0). When set to { animated: true } it will scroll smoothly to the destination.

Note that the default here is equivalent to passing in { animated: true }

Returns

Type
void

# scrollToBottom

Availability
0.9
2.1.0
9.2.0
scrollToBottom() → void

Moves the end of the scrollable region into the viewable area.

On Android the behavior of scrollToBottom depends on whether this scroll view scrolls horizontally or vertically. For vertical scroll views, scrollToBottom moves the bottom of the scrollable region into the viewable area. For horizontal scroll views, scrollToBottom moves the rightmost edge of of the scrollable region into the viewable area.

On iOS, scrollToBottom moves the bottom-right corner of the scrollable region into the viewable area.

Returns

Type
void

# scrollToTop

Availability
7.0.0
7.0.0
9.2.0
scrollToTop() → void

Moves the top of the scrollable region into the viewable area.

On Android the behavior of scrollToTop depends on whether this scroll view scrolls horizontally or vertically. For vertical scroll views, scrollToTop moves the top of the scrollable region into the viewable area. For horizontal scroll views, scrollToTop moves the leftmost edge of of the scrollable region into the viewable area.

On iOS, scrollToTop moves the top-left corner of the scrollable region into the viewable area.

Returns

Type
void

# setContentOffset

Availability
0.9
9.2.0
setContentOffset(contentOffsetXY[, animated]) → void

Sets the value of the contentOffset property.

Parameters

Name Type Description
contentOffsetXY Point

X and Y coordinates to which to reposition the top-left point of the scrollable region.

animated AnimatedOptions

A JS object with an animated property which determines whether the scrollable region reposition should be animated.

Note that the default here is equivalent to passing in { animated: true }

Returns

Type
void

# setZoomScale

Availability
0.9
9.2.0
setZoomScale(zoomScale[, options]) → void

Sets the value of the zoomScale property.

Parameters

Name Type Description
zoomScale Number

Scaling factor of the scroll view's content.

options AnimatedOptions

A JS object with an animated property which determines whether the scrollable region reposition should be animated

Note that the default here is equivalent to passing in { animated: false }

Returns

Type
void

# Events

# scale

Availability
0.9
9.2.0

Fired when the zoom scale factor changes.

Properties

Name Type Description
scale Number

New scaling factor as a float.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# scroll

Availability
0.9
0.9
9.2.0

Fired when the scrollable region is scrolled.

Properties

Name Type Description
contentSize Size

The current content size of the scroll view defined by its width and height properties.

decelerating Boolean

Indicates whether the scroll is decelerating.

dragging Boolean

Indicates whether the event was fired during a dragging gesture, where the touch remained in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.

zooming Boolean

Indicates whether the event was fired during a zooming operation. This is only available from Release 3.2.3 of the Titanium Mobile SDK.

curZoomScale Number

The current scaling factor of the scroll view content. This might not be equal to the zoomScale property or be within the range specified by minZoomScale and maxZoomScale. This is only available from Release 3.2.3 of the Titanium Mobile SDK.

x Number

X coordinate of the event from the source view's coordinate system.

y Number

Y coordinate of the event from the source view's coordinate system.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# dragStart

Availability
0.9
9.2.0

Fired when the scrollable region starts being dragged.

This event has been deprecated and renamed dragstart (lower case).

A dragging gesture is when a touch remains in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.

# dragEnd

Availability
0.9
9.2.0

Fired when the scrollable region stops being dragged.

This event has been deprecated and renamed dragend (lower case).

A dragging gesture is when a touch remains in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.

Properties

Name Type Description
decelerate Boolean

Indicates whether scrolling will continue but decelerate, now that the drag gesture has been released by the touch. If false, scrolling will stop immediately.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# dragstart

Availability
6.2.0
3.0.0
9.2.0

Fired when the scrollable region starts being dragged.

A dragging gesture is when a touch remains in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.

# dragend

Availability
6.2.0
3.0.0
9.2.0

Fired when the scrollable region stops being dragged.

A dragging gesture is when a touch remains in contact with the display to physically drag the view, as opposed to it being the result of scrolling momentum.

Properties

Name Type Description
decelerate Boolean

Indicates whether scrolling will continue but decelerate, now that the drag gesture has been released by the touch. If false, scrolling will stop immediately. Is always true on Android.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

Contents