Wiki
Clone wikiVirtualScroller / Home
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 isgetView(itemIndex)
whereitemIndex
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 is0
. The view to initially display upon creation (zero-based indexing)touch
: Default istrue
. Whether a touch screen exists on the device. Used for enabling trackball navigation.autoFocus
: Default isfalse
. Whether to auto-focus the first child of a View when it is viewed.scrollerDef
: Default isshowPagingControl : false
. Options to pass directly to the underlyingScrollableView
instance.containerDef
: Default isbackgroundColor : '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
fromgetView
, 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)
Updated