Introduction

Current version: 1.2.1 (last updated October 19, 2013)

VirtualScroller is an easy to use Titanium module that wraps around a ScrollableView and provides finite and infinite scrolling. All items (which are actually Views) are created on-demand, and only remain in memory when needed. At most, the ScrollableView only ever has five views, so only five Views maximum are ever in memory at the same time.

This method permits memory-efficient scrolling of large sets of views.

The project was based on this GitHub gist: https://gist.github.com/810171

Installing

Download the latest zip of VirtualScroller source files from the Download section. The only file you actually need to copy into your project is VirtualScroller.js. Copy this file into the *project_path*/Resources folder of your project. That's it!

License

This project is under an MIT license.

Testing and bug reporting

I've only tested this on Android so far, though it should work on iOS. The only changes I could foresee would relate to tinkering with the event listeners (e.g. maybe not disabling them between swipes). If anyone wants to do this, then please go ahead and create a pull request.

If you find any bugs, or would like to make any modifications, please create an Issue or a pull request.

Usage

Getting started

The first thing you need to do is to require the VirtualScroller factory method:

var VirtualScroller = require('ui/common/VirtualScroller');

Replace the path with wherever inside your Resources folder the file is located.

That isn't a VirtualScroller instance; it's the method that creates VirtualScrollers. To create a VirtualScroller, invoke the method with your options object (described below).

Finite scrolling

Here's an example of a finite VirtualScroller:

var virtualScroller = VirtualScroller({
    itemCount: 10,
    getView: function(i) {
        return Titanium.UI.createLabel({
            width: Titanium.UI.FILL,
            height: Titanium.UI.FILL,
            text: "This is item " + (i + 1)
        });
    }
});

Then add the view property of the instance to your View/Window.

window.add(virtualScroller.view);

We've just created a finite VirtualScroller. There are only 10 items that the VirtualScroller scrolls through. itemCount specified that number. The getView function is a callback that is called when the specified item (zero-based index, i) is needed.

Infinite scrolling

VirtualScroller also supports infinite scrolling. This is useful when there is no limit to the number of views the scroller needs to display. Create an infinite VirtualScroller by omitting the itemCount property.

Options

VirtualScroller supports the following options:

Required (for both finite and infinite scrolling):

getView: The callback function that is invoked to create each view. Signature is getView(itemIndex) where itemIndex is zero-based.

Required (for finite scrolling only):

itemCount: Total number of items (views). Only required when using finite scrolling; if this parameter is missing, the VirtualScroller assumes infinite scrolling.

Optional:

start: Default is 0. The view to initially display upon creation (zero-based indexing)
touch: Default is true. Whether a touch screen exists on the device. Used for enabling trackball navigation.
autoFocus: Default is false. Whether to auto-focus the first child of a View when it is viewed.
scrollerDef: Default is showPagingControl : false. Options to pass directly to the underlying ScrollableView instance.
containerDef: Default is backgroundColor : 'white', top/bottom/right/left : 0. Options to pass directly to the underlying View containers.

Disposing

VirtualScroller instances support a dispose method. This method destroys internal event listeners and underlying Views. Be sure to call it when you don't need the VirtualScroller anymore, to clean up resources.

Call it like so:

var virtualScroller = VirtualScroller({
    // ... options, etc.
});

window.add(virtualScroller.view);

// Later on... maybe the view is about to be closed because we are navigating to a new window
virtualScroller.dispose();

Future development

VirtualScroller currently lacks the following features, which I plan to implement if I get enough interest in the current offering. They are listed in no particular order.

Infinite scrolling currently exists only in one direction. View indexing starts at 0 and goes to infinity. I'd like to implement bidirectional infinite scrolling.
Iterator-like functionality: Sometimes you don't know how many items you have to scroll through. You should be able to return null from getView, which signals that there are no more items.
Programmatic scrolling: VirtualScroller currently lacks methods to control the state. The only way to change the scroll position, as of now, is to create a new VirtualScroller instance with start set to the index of the view you want to display.
Better parameter validation (e.g. check that getView is actually a function)
iOS compatibility (it might be already, but I don't have a Mac or iOS device to verify)

Wiki

VirtualScroller / Home