# Titanium.UI.ScrollableView

A view that encapsulates a horizontally-scrolling set of child views, known as pages, navigable using its built-in horizontal swipe gestures.

Availability

0.8

9.2.0

Extends

Titanium.UI.View

# Overview

Use the Titanium.UI.createScrollableView method or <ScrollableView> Alloy element to create a scrollable view.

The ScrollableView supports an on-screen paging control to indicate whether a previous or next page exists. When the paging control is enabled on iOS, by default it appears as small dots on the bottom of the screen, whereas Android displays arrows on the left and right-hand sides.

Use the cacheSize property to cache views inside the scrollable view. This can be required when using complex view structures in the scrollable view (e.g. map views) and the app might crash if no proper cache size is specified. See the Titanium.UI.ScrollableView.cacheSize documentation for more infos regarding view caching.

Only the scroll event exists for the ScrollableView on Android. To support others, child views may be added to pages, and event listeners added to these views instead of the pages themselves.

In a previous Titanium version for iOS, the maxZoomScale and minZoomScale properties were removed for performance and parity reasons. As they still remain in Titanium.UI.ScrollView, the equivalent functionality may be obtained by adding a ScrollView to ScrollableView. See the "Simple Scrollable View with 2 Zoomable Images" example for a demonstration.

# Examples

# Simple Scrollable View with 3 Views

Create three views and assign them as pages to a scrollable view.

var win = Ti.UI.createWindow();

var view1 = Ti.UI.createView({ backgroundColor:'#123' });
var view2 = Ti.UI.createView({ backgroundColor:'#246' });
var view3 = Ti.UI.createView({ backgroundColor:'#48b' });

var scrollableView = Ti.UI.createScrollableView({
  views:[view1,view2,view3],
  showPagingControl:true
});

win.add(scrollableView);
win.open();

# Simple Scrollable View with 2 Zoomable Images

Create two scroll views, each containing an image view, and assign them as pages to a scrollable view.

var img1 = Ti.UI.createImageView({
    image:'http://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/' +
    'Mona_Lisa%2C_by_Leonardo_da_Vinci%2C_from_C2RMF_retouched.jpg/' +
    '402px-Mona_Lisa%2C_by_Leonardo_da_Vinci%2C_from_C2RMF_retouched.jpg'
});
var img1Wrapper = Ti.UI.createScrollView({
    maxZoomScale:4.0,
});
img1Wrapper.add(img1);

var img2 = Ti.UI.createImageView({
    image:'http://www.nasa.gov/images/content/' +
    '616903main_rover_comparison1600_1600-1200.jpg'
});
var img2Wrapper = Ti.UI.createScrollView({
    maxZoomScale:4.0,
});
img2Wrapper.add(img2);
var photosView = Ti.UI.createScrollableView({
    showPagingControl:true,
    views:[img1Wrapper, img2Wrapper]
});
win.add(photosView);

# Scrollable View with multiple visible views

Create three views and assign them as pages to a scrollable view. Each page is narrower than a scrollable view, so multiple views are visible at the same time.

var win = Ti.UI.createWindow();

var view1 = Ti.UI.createView({ backgroundColor:'#123' });
var view2 = Ti.UI.createView({ backgroundColor:'#246' });
var view3 = Ti.UI.createView({ backgroundColor:'#48b' });

// Common params
var params = {
  views:[view1,view2,view3],
  clipViews:false,
  showPagingControl:false,
  top: 0
};

if (Ti.Platform.name === 'android') {
  // Android specific params
  params.padding = {
    left:40,
    right:40
  };
} else {
  // iOS specific params
  params.width = '90%';
}
var scrollableView = Ti.UI.createScrollableView(params);
win.add(scrollableView);
win.open();

# Alloy XML Markup

First example as an Alloy view.

<Alloy>
    <Window id="win">
        <ScrollableView id="scrollableView" showPagingControl="true">
            <View id="view1" backgroundColor="#123">
              <Label>View 1</Label>
            </View>
            <View id="view2" backgroundColor="#246">
            <Label>View 2</Label>
            </View>
            <View id="view3" backgroundColor="#48b">
            <Label>View 3</Label>
            </View>
        </ScrollableView>
    </Window>
</Alloy>

# Scrollable View with indicator image (iOS only)

Create three views and assign them as pages to a scrollable view. Assign preferred indicator image. After window opens, update second page indicator image.

var win = Ti.UI.createWindow({ extendSafeArea: false });

var view1 = Ti.UI.createView({ backgroundColor:'#123' });
var view2 = Ti.UI.createView({ backgroundColor:'#246' });
var view3 = Ti.UI.createView({ backgroundColor:'#48b' });
var backwardImage = Ti.UI.iOS.systemImage('backward');
var scrollableView = Ti.UI.createScrollableView({
  views:[view1,view2,view3],
  showPagingControl:true,
  preferredIndicatorImage: backwardImage
});

win.add(scrollableView);
win.addEventListener('open', function () {
  var forwardImage = Ti.UI.iOS.systemImage('forward');
  scrollableView.setIndicatorImageForPage(forwardImage, 1);
});

win.open();

# Properties

# cacheSize

Availability

4.1.0

0.8

9.2.0

cacheSize :Number

Number of pages to cache (pre-render).

Pages are rendered in the range (currentPage +/- (cacheSize - 1)/2), rounded down for even values (i.e. cacheSize=4 renders 3 pages into the cache.) Keep in mind that improved performance (larger cache) will lead to faster performance, but greater memory usage.

# clipViews CREATION ONLY

Availability

7.5.0

0.9

9.2.0

clipViews :Boolean

Determines whether the previous and next pages are clipped, so that they are not visible adjacent to the current page.

Set to false to allow the previous or next pages to be seen. Note that ScrollableView's width must be smaller than its parent view in order to make this property effective.

Default: true

# currentPage

Availability

0.8

9.2.0

currentPage :Number

Index of the active page.

Since Titanium Mobile Release 3.3.0, using this property to change current page changes the page without animation on iOS and Android.

# currentPageIndicatorColor

Availability

5.4.0

9.2.0

currentPageIndicatorColor :String | Titanium.UI.Color

Color for the current page of the paging control, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: undefined (system-default white)

# disableBounce

Availability

0.8

9.2.0

disableBounce :Boolean

Determines whether page bouncing effect is disabled.

Default: false

# hitRect

Availability

2.1

9.2.0

hitRect :Dimension

Sets the region where this view responds to gestures.

This property is particularly useful when clipViews is set to false and the dimension of this view is small, to create a larger area for the user to perform swipe gestures against.

Note that the x and y values specified are relative to the position of the view.

Default: undefined (hit against size of view)

# overlayEnabled

Availability

2.1.0

9.2.0

overlayEnabled :Boolean

Determines whether the paging control is added as an overlay to the view.

If this property is set to true, the view takes up the entire height available in the parent view and the paging control is placed over the view. It is advisable to set an appropriate value for pagingControlAlpha along with this property, so that the underlying view content may be seen properly.

Default: false

# 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

# padding

Availability

7.5.0

padding :Padding

The padding applied to the scrollable view.

# pageIndicatorColor

Availability

5.4.0

9.2.0

pageIndicatorColor :String | Titanium.UI.Color

Color of the paging control, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: undefined (system-default gray)

# pagingControlAlpha

Availability

2.1.0

9.2.0

pagingControlAlpha :Number

Alpha value of the paging control.

Default: 1

# pagingControlColor

Availability

0.8

9.2.0

pagingControlColor :String | Titanium.UI.Color

Color of the paging control, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

# pagingControlHeight

Availability

0.8

9.2.0

pagingControlHeight :Number

Height of the paging control, in pixels.

Default: 20

# pagingControlOnTop

Availability

2.1.0

9.2.0

pagingControlOnTop :Boolean

Determines whether the paging control is displayed at the top or bottom of the view.

Set to true for the paging control at the top.

Default: false

# pagingControlTimeout CREATION ONLY

Availability

0.8

pagingControlTimeout :Number

Number of milliseconds to wait before hiding the paging control.

Set to less than or equal to 0 to disable timeout, to keep controls displayed.

Default: 3000

# preferredIndicatorImage

Availability

9.2.0

preferredIndicatorImage :String | Titanium.Blob

The preferred image for indicators, defined using a local filesystem path, or a Blob object containing image data.

Symbol images are recommended. Use systemImage to get system-supplied symbol images. See examples section for usage.

# scrollingEnabled

Availability

2.1.0

2.0.0

9.2.0

scrollingEnabled :Boolean

Determines whether scrolling is enabled for the view.

If this property is unset or true, scrolling is enabled.

Default: undefined (scrolling enabled)

# showPagingControl

Availability

0.8

9.2.0

showPagingControl :Boolean

Determines whether the paging control is visible.

Set to true to show paging control.

Default: false

# views

Availability

0.8

9.2.0

views :Array<Titanium.UI.View>

Sets the pages within this Scrollable View.

# Methods

# addView

Availability

0.8

9.2.0

addView(view) → void

Adds a new page to this Scrollable View.

Parameters

Name	Type	Description
`view`	Titanium.UI.View	The page to add.

Returns

Type: void

# insertViewsAt

Availability

5.4.0

9.2.0

insertViewsAt(position, views) → void

Inserts views at the specified position in the views array.

Parameters

Name	Type	Description
`position`	Number	Position(index) in the views array to insert the view
`views`	Array<Titanium.UI.View>	Views to insert.

Returns

Type: void

# moveNext

Availability

0.8

3.3.0

9.2.0

moveNext() → void

Sets the current page to the next consecutive page in views.

Since Titanium Mobile Release 3.3.0, using this method to change current page animates the change on iOS and Android.

Returns

Type: void

# movePrevious

Availability

0.8

3.3.0

9.2.0

movePrevious() → void

Sets the current page to the previous consecutive page in views.

Since Titanium Mobile Release 3.3.0, using this method to change current page animates the change on iOS and Android.

Returns

Type: void

# removeView

Availability

0.8

9.2.0

removeView(view) → void

Removes an existing page from this Scrollable View.

On Android, does nothing if the page does not exist in views.

On iOS, throws an exception if the page does not exist in views or the index is invalid.

Parameters

Name	Type	Description
`view`	Number \| Titanium.UI.View	A Titanium.UI.View object (all platforms) or integer index (Android and iOS only) of the page to remove.

Returns

Type: void

# scrollToView

Availability

0.8

9.2.0

scrollToView(view) → void

Scrolls to the specified page in views.

Parameters

Name	Type	Description
`view`	Number \| Titanium.UI.View	An integer index or Titanium.UI.View object to set as the current page.

Returns

Type: void

# setIndicatorImageForPage

Availability

9.2.0

setIndicatorImageForPage(image, pageNo) → void

Sets the indicator image for the specified page.

Override the indicator image for a specific page. Symbol images are recommended. Use systemImage to get system-supplied symbol images. See examples section for usage.

Parameters

Name	Type	Description
`image`	String \| Titanium.Blob	The image for the indicator, defined using a local filesystem path, or a `Blob` object containing image data. Resets to the default if image is null.
`pageNo`	Number	Page number to set the image.

Returns

Type: void

# Events

# dblclick

Availability

0.9

9.2.0

Fired when the device detects a double click against the view.

Properties

Name	Type	Description
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.

# doubletap

Availability

0.9

9.2.0

Fired when the device detects a double tap against this page.

Properties

Name	Type	Description
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.

# longpress

Availability

0.9

9.2.0

Fired when the device detects a long press against this view.

Generated by touching and holding on a touchscreen, this event occurs before the finger is lifted again. Note that longpress cannot be generated with a trackball.

Properties

Name	Type	Description
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.

# singletap

Availability

0.9

9.2.0

Fired when the device detects a single tap against this view.

Properties

Name	Type	Description
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.

# touchcancel

Availability

0.9

9.2.0

Fired when a touch gesture is interrupted by the device.

Generated in various circumstances, including an incoming call to allow the UI to clean up state.

Properties

Name	Type	Description
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.

# touchstart

Availability

0.9

9.2.0

Fired as soon as the device detects a touch gesture against this view.

Properties

Name	Type	Description
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.

# twofingertap

Availability

0.9

9.2.0

Fired when the device detects a two-finger tap against the view.

Properties

Name	Type	Description
y	Number	Y coordinate of the event from the `source` view's coordinate system.
x	Number	X 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.

# scroll

Availability

0.8

9.2.0

Fired repeatedly as the view is being scrolled.

Prior to 2.1, the scroll event did not fire consistently on all platforms. On iOS, it fired when scrolling ended, and on Android, it fired when drag ended. You can restore the pre-2.1 behavior by listening for the scrollEnd or dragEnd events instead.

Properties

Name	Type	Description
currentPage	Number	Index of the currently visible view of views.
currentPageAsFloat	Number	Current page index that the view is scrolled to as a float. For example, if the user is holding the `ScrollableView` in between the first and second page, this will have a value of 0.5.
view	Titanium.UI.View	The currently visible view.
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.

# scrollend

Availability

3.0.0

9.2.0

Fired when the view has stopped moving completely.

Properties

Name	Type	Description
currentPage	Number	Index of the currently visible view of views.
view	Titanium.UI.View	The currently visible view.
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.

# dragend

Availability

3.0.0

Fired when the scrolling drag gesture on the view has been completed.

Properties

Name	Type	Description
currentPage	Number	Index of the currently visible view of views.
view	Titanium.UI.View	The currently visible view.
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.