# 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. - Source: https://titaniumsdk.com/docs/sdk/12.6.1/Titanium.UI.ScrollableView - Titanium SDK version: 12.6.1 - Kind: view - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.8 - Extends: Titanium.UI.View - Inheritance: Titanium.UI.View > Titanium.Proxy | Android | iOS | | ------- | --- | | ![Android](./scrollableview_android.png) | | Use the [Titanium.UI.createScrollableView](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createScrollableView) method or **``** 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#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](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md), 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. ## Example: Simple Scrollable View with 3 Views Create three views and assign them as pages to a scrollable view. ``` js 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(); ``` ## Example: 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. ``` js var win = Ti.UI.createWindow(); 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); ``` ## Example: 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. ``` js 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(); ``` ## Example: Alloy XML Markup First example as an Alloy view. ``` xml ``` ## Example: 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. ``` js 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 - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 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 - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 - Default: `true` 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#width) must be smaller than its parent view in order to make this property effective on iOS. For Android you have to set the [padding](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#padding) property. Check the `Scrollable View with multiple visible views` example for both platforms. ### currentPage - Type: Number - Platforms: Android, iPhone, iPad, macOS 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 - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 - Default: `undefined (system-default white)` 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### disableBounce - Type: Boolean - Platforms: iPhone, iPad, macOS - Default: `false` Determines whether page bouncing effect is disabled. ### hitRect - Type: Dimension - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 2.1 - Default: `undefined (hit against size of view)` Sets the region where this view responds to gestures. This property is particularly useful when [clipViews](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#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. ### overlayEnabled - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 - Default: `false` 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#pagingControlAlpha) along with this property, so that the underlying view content may be seen properly. ### overScrollMode - Type: Number - Platforms: Android - Since: Titanium SDK 3.1.0 - Default: `Titanium.UI.Android.OVER_SCROLL_ALWAYS` Determines the behavior when the user overscolls the view. Accepts: `Titanium.UI.Android.OVER_SCROLL_ALWAYS`, `Titanium.UI.Android.OVER_SCROLL_IF_CONTENT_SCROLLS`, `Titanium.UI.Android.OVER_SCROLL_NEVER` ### padding - Type: Padding - Platforms: Android - Since: Titanium SDK 7.5.0 The padding applied to the scrollable view. ### pageIndicatorColor - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 - Default: `undefined (system-default gray)` Color of the paging control, as a color name or hex triplet. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### pagingControlAlpha - Type: Number - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 - Default: `1` Alpha value of the paging control. ### pagingControlColor - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS - Default: `black` Color of the paging control, as a color name or hex triplet. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### pagingControlHeight - Type: Number - Platforms: iPhone, iPad, macOS - Default: `20` Height of the paging control, in pixels. ### pagingControlOnTop - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 - Default: `false` 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. ### pagingControlTimeout - Type: Number - Platforms: Android - Default: `3000` 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. ### preferredIndicatorImage - Type: String | Titanium.Blob - Platforms: iPhone, iPad - Since: Titanium SDK 9.2.0 - Requires: iOS 14.0+ The preferred image for indicators, defined using a local filesystem path, or a `Blob` object containing image data. Symbol images are recommended. Use [Titanium.UI.iOS.systemImage](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#systemImage) to get system-supplied symbol images. See examples section for usage. ### scrollingEnabled - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 2.1.0, iPhone 2.0.0, iPad 2.0.0 - Default: `undefined (scrolling enabled)` Determines whether scrolling is enabled for the view. If this property is unset or `true`, scrolling is enabled. ### showPagingControl - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `false` Determines whether the paging control is visible. Set to `true` to show paging control. ### views - Type: Array - Platforms: Android, iPhone, iPad, macOS Sets the pages within this Scrollable View. ## Methods ### addView - Platforms: Android, iPhone, iPad, macOS Adds a new page to this Scrollable View. Parameters: - `view` (Titanium.UI.View): The page to add. ### insertViewsAt - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 Inserts views at the specified position in the [views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views) array. Parameters: - `position` (Number): Position(index) in the [views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views) array to insert the view - `views` (Array): Views to insert. ### moveNext - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.3.0 Sets the current page to the next consecutive page in [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). Since Titanium Mobile Release 3.3.0, using this method to change current page animates the change on iOS and Android. ### movePrevious - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.3.0 Sets the current page to the previous consecutive page in [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). Since Titanium Mobile Release 3.3.0, using this method to change current page animates the change on iOS and Android. ### removeView - Platforms: Android, iPhone, iPad, macOS Removes an existing page from this Scrollable View. On Android, does nothing if the page does not exist in [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). On iOS, throws an exception if the page does not exist in [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views) or the index is invalid. Parameters: - `view` (Number | Titanium.UI.View): A [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md) object (all platforms) or integer index (Android and iOS only) of the page to remove. ### scrollToView - Platforms: Android, iPhone, iPad, macOS Scrolls to the specified page in [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). Parameters: - `view` (Number | Titanium.UI.View): An integer index or [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md) object to set as the current page. ### setIndicatorImageForPage - Platforms: iPhone, iPad - Since: Titanium SDK 9.2.0 - Requires: iOS 14.0+ Sets the indicator image for the specified page. Override the indicator image for a specific page. Symbol images are recommended. Use [Titanium.UI.iOS.systemImage](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#systemImage) to get system-supplied symbol images. See examples section for usage. Parameters: - `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. ## Events ### dblclick - Platforms: iPhone, iPad, macOS Fired when the device detects a double click against the view. Event properties: - `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. ### doubletap - Platforms: iPhone, iPad, macOS Fired when the device detects a double tap against this page. Event properties: - `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. ### dragend - Platforms: Android - Since: Titanium SDK 3.0.0 Fired when the scrolling drag gesture on the view has been completed. Event properties: - `currentPage` (Number): Index of the currently visible view of [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). - `view` (Titanium.UI.View): The currently visible view. ### longpress - Platforms: iPhone, iPad, macOS 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. Event properties: - `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. ### scroll - Platforms: Android, iPhone, iPad, macOS 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. Event properties: - `currentPage` (Number): Index of the currently visible view of [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#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. ### scrollend - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 Fired when the view has stopped moving completely. Event properties: - `currentPage` (Number): Index of the currently visible view of [Titanium.UI.ScrollableView.views](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollableView.md#views). - `view` (Titanium.UI.View): The currently visible view. ### singletap - Platforms: iPhone, iPad, macOS Fired when the device detects a single tap against this view. Event properties: - `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. ### touchcancel - Platforms: iPhone, iPad, macOS 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. Event properties: - `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. ### touchstart - Platforms: iPhone, iPad, macOS Fired as soon as the device detects a touch gesture against this view. Event properties: - `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. ### twofingertap - Platforms: iPhone, iPad, macOS Fired when the device detects a two-finger tap against the view. Event properties: - `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. ## Inherited members 86 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` - [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.6.1/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `clipMode`, `convertPointToView`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `layout`, `left`, `opacity`, `overrideCurrentAnimation`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.