Creating a sectioned list

How to

Create a list with sections of items in your application.

Solution

Construct the SectionList object in your class

// To allow other applications to reference 
// this object, you can place it in the class root
var mySectionList:SectionList = new SectionList();

Initialize your SectionList's attributes

// Set location
mySectionList.x = 100;
mySectionList.y = 50;

// Set width
mySectionList.width = 300;
// Set height
mySectionList.height = 500;
// Set height for section headers
mySectionList.headerHeight = 48; 

// Optional: Set selection mode
mySectionList.selectionMode = ListSelectionMode.MULTIPLE;
// Optional: Set scroll direction
mySectionList.scrollDirection = ScrollDirection.VERTICAL;

// Call event functions when list is tapped or scrolled
mySectionList.addEventListener(ListEvent.ITEM_CLICKED, onListClick);
mySectionList.addEventListener(ScrollEvent.SCROLL_END, onScroll);
mySectionList.addEventListener(ScrollEvent.SCROLL_BEGIN, onScrollStart);

// Add list to stage
this.addChild( mySectionList );

Create and apply your sectioned list's contents

// Create an array for objects
var arrMonth:Array=[];

// Add objects with a label property
arrMonth.push({label: "January"});
arrMonth.push({label: "February"});
arrMonth.push({label: "March"});
arrMonth.push({label: "April"});
arrMonth.push({label: "May"});
arrMonth.push({label: "June"});
arrMonth.push({label: "July"});
arrMonth.push({label: "August"});
arrMonth.push({label: "September"});
arrMonth.push({label: "October"});
arrMonth.push({label: "November"});
arrMonth.push({label: "December"}); 

var mySDP:SectionDataProvider = new SectionDataProvider();
 
// Populate section data provider
for( var i:int = 0; i < arrMonth.length; i++ )
{
    // Add month names from array to data provider
    var section:Object = new Object();
    section.label = arrMonth[i].label;
    mySDP.addItem( section );
                
    // Add day numbers to each section, (all 31 for now. further
    // logic to remove non-existing dates could be implemented)
    for( var j:int = 1; j<32; j++ )
    {
        mySDP.addChildToItem( {label: j}, section );    
    }
} 

// Link section data provider to list as a data provider
mySectionList.dataProvider = mySDP;

Create the functions that are called by your sectioned list's interaction events

private function onListClick(event:ListEvent):void 
{
	trace("Item clicked: " + event.data.label);
	trace("Index clicked: " + event.index);
	trace("Section clicked: " + event.section);
    trace(mySectionList.selectedItems.length + " items selected");
	
    for( var n:int = 0; n < mySectionList.selectedItems.length; n++ )
    {        
        trace(mySectionList.selectedItems[n].label + " is currently selected");
    }
}

private function onScroll(event:ScrollEvent):void
{
	trace("Finished scrolling...");
}

private function onScrollStart(event:ScrollEvent):void
{
	trace("Start scrolling...");
}

Build requirements

You must include the following classes in the class:

import qnx.fuse.ui.events.ListEvent;
import qnx.fuse.ui.events.ScrollEvent;
import qnx.fuse.ui.listClasses.ListSelectionMode;
import qnx.fuse.ui.listClasses.ScrollDirection;
import qnx.fuse.ui.listClasses.SectionList;
import qnx.ui.data.SectionDataProvider;

Discussion

When you create a section list, you declare the SectionList variable and set its properties to whatever values your application requires. After you set up your list's properties, you can create an array of data to provide the list's contents and use the list's dataProvider property to apply the contents. To add functionality, you can add listener functions for ITEM_CLICKED, SCROLL_BEGIN, and SCROLL_END events to perform the actions that are defined in the functions, when the user interacts with your list. You can also reference the currently selected items in your list elsewhere in the class by using your list's selectedItems property.

The selectedItems property returns an array of objects. You can iterate through this array and obtain the labels of selected list items. If you have duplicate labels, (for example, the calendar data in the example code) consider adding code to track the selections more specifically when section data is available.