# 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
0.8
9.2.0
4.1.0

# 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
0.8
9.2.0
4.1.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.

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
4.1.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
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
0.8
9.2.0
4.1.0
views :Array<Titanium.UI.View>

Sets the pages within this Scrollable View.

# Methods

# addView

Availability
0.8
0.8
9.2.0
4.1.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
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
4.1.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
4.1.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
0.8
9.2.0
4.1.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
0.8
9.2.0
4.1.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

# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# scroll

Availability
0.8
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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# scrollend

Availability
3.0.0
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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# 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.

bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.