June 30, 2011 / Daniel Freeman

Tutorial 3: Lists and Pickers

Having laid the foundations with the previous two tutorials, now we can start to demonstrate the real power of MadComponents for mobile flash applications. In this tutorial, we’re going to investigate lists and pickers.

There have been a few version updates since the last tutorial – So always make sure that you have the latest version of the mad components library. (Currently, the latest is madComponentsLib0_5_3.swc). Download from here.

Beware Copy and Paste

Given that these tutorials are full of XML examples, it’s worth mentioning again that things can go wrong if you copy and paste XML into Flash or Flex Builder. You might get an error that says:- “TypeError: Error #2007: Parameter text must be non-null”. This is because the pasted text contains unprintable characters that screw things up. Refer to the previous tutorial for advise of how to remedy this.

Defining Data in XML

Let’s assume that we want to build an application, where the user can scroll through a list of names. We can first define the data that will populate the list like this:-

<data>

   <item label=”Sneezy”/>

   <item label=”Sleepy”/>

   <item label=”Dopey”/>

   <item label=”Doc”/>

   <item label=”Happy”/>

   <item label=”Bashful”/>

   <item label=”Grumpy”/>

</data>

There is also an alternative shorthand way of expressing XML data in MadComponents. Given that the names have no spaces or non-alphabetic characters, we can save some typing and write:-

<data>

   <Sneezy/>

   <Sleepy/>
<Dopey/>

   <Doc/>

   <Happy/>
<Bashful/>

   <Grumpy/>

</data>

Making a list

To put this data into a list, we simply write:-

<list>

{DATA}

</list>

So, the entire program looks like this:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;

	public class MadLists extends Sprite
	{
		protected static const DATA:XML = <data>
	<Sneezy/>
	<Sleepy/>
	<Dopey/>
	<Doc/>
	<Happy/>
	<Bashful/>
        <Grumpy/>
   </data>;

		protected static const LIST:XML = <list>{DATA}</list>;

		public function MadLists(screen:Sprite = null)
		{
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, LIST);
		}
	}
}

If you rapidly click and drag the list up or down, you’ll see it scroll, and the scrollbar appearing at the side. You probably want a longer list of data to really see this in action. Testing an app on the desktop, using a mouse or trackpad, it can be a bit tricky to control the difference between scroll/swipe gestures and click gestures. But on the device – it all makes sense.

Listen for clicks

Listen for list clicks as follows:-

protected var _list:UIList

_list = UIList(UI.findViewById(“list”));

_list.addEventListener(UIList.CLICKED, listClickedHandler);

protected function listClickedHandler(event:Event):void {

var index:int = _list.index;

// var group:int = _list.group; //divided and grouped lists only.

}

Divided and Grouped lists have a group property, that gives the group index of the clicked row.

Tick Lists

MadComponents has two kinds of tick list. <tickList/> and <tickOneList/>. As you’d expect, <tickOneList> only allows one row to be ticked at any time. (so click on a second row, and the first one un-ticks itself).

You can read the state of the tick list using ActionScript. When listening for the state of the data to change, listen for Event.CHANGE , rather than UIList.CLICKED.

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;

	public class MadTickList extends Sprite
	{
		protected static const DATA:XML = <data>
     <Sneezy/>
     <Sleepy/>
     <Dopey/>
     <Doc/>
     <Happy/>
     <Bashful/>
     <Grumpy/>
   </data>;

		protected static const TICKLIST:XML = <tickList id="ticks">{DATA}</tickList>;

		protected var _tickList:UITickList;

		public function MadTickList(screen:Sprite = null)
		{
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, TICKLIST);

			_tickList = UITickList(UI.findViewById("ticks"));
			_tickList.addEventListener(Event.CHANGE, tickListChanged);
		}

		protected function tickListChanged(event:Event):void {
			trace();
			for each(var item:uint in _tickList.tickIndexes) {
				trace(UILabel(_tickList.findViewById("label",item)).text);
			}
		}
	}
}

Defining Grouped Data in XML

Now, we’re going to look at grouped lists in MadComponents. But first, let’s look at how to define grouped data.

<data>

   <group label=”dwarfs”>

   <Sneezy/>

   <Sleepy/>
<Dopey/>

   <Doc/>

   <Happy/>
<Bashful/>

   <Grumpy/>

   </group>

   <group label=”reindeer”>

   <Dasher/>

   <Dancer/>

   <Prancer/>

   <Vixen/>

   <Comet/>

   <Cupid/>

   <Donder/>

   <Blitzen/>

   </group>

</data>

You can still use the alternative notation, for example: <item label=”Dasher”/> if you wish. Group label attributes above are optional. Include them if you require group headings on your grouped list.

Divided and Grouped Lists

You can create a divided list as follows:-

<dividedList>

{GROUPED_DATA}

</dividedList>

Or, create a grouped list like this:-

<groupedList>

{GROUPED_DATA}

</groupedList>

But we can improve the appearance of the grouped list, by choosing appropriate colours and spacing:-

<groupedList background=”#C6CCD6″ colour=”#CCCCCC” gapH=”32″ gapV=”4″>

{GROUPED_DATA}

</groupedList>

Colouring Lists

In the previous example, we used the colour, and background attributes to change the appearance of a list. This works for any list. Not just the grouped list.

The colour attributes defines the colours of the dividing lines. The background attribute can specify several colour values, separated by commas. The first parameter is the background colour, the second is the row colour. Any further parameters allow you to have rows with alternating colours. For example:-

<list colour=”#333366” background= ”#CCCCFF,#9999CC,#AAAACC”>

Creates the following result:-

Suppose you also want to make the text colour white. You can define <text> formatting as follows:-

<list colour=”#333366″ background= “#CCCCFF,#9999CC,#AAAACC”>

{DATA}

<font color=”#FFFFFF”/>

</list>

Notice that colour attribute inside an HTML font tag has American spelling. But Colour elsewhere in the layout is spelt with a ‘u’, with British spelling.

Custom renderers

You can define a custom list item renderer in XML. Suppose, for example, each row contains a label and a switch. You can define that as follows:-

<list colour=”#333366″ background= “#CCCCFF,#9999CC,#AAAACC”>

   {DATA}

   <horizontal>

   <label id=”label”/>

   <switch id=”state” alignH=”right”/>

   </horizontal>

</list>

Searching Lists

The <search> tag may be used to create a search bar at the top of a list. The field attribute can be used to enable searching and filtering of the list, without having to write any actionScript. In the previous “dwarfs” list example, you can modify the layout as follows to enable searching:-

<list>

{DATA}

<search field=”label”/>

</list>

Setting data in ActionScript

You can set list data from ActionScript, rather than defining it in XML. You can assign either an array, or XML. You can assign an array of objects to the data property like this:-

list.data = [{label:”one”}, {label:”two”}, {label:”three”}];

There is also a short way to do this, using an array of strings.

list.data = [“one”,”two”,”three”];

For a custom renderer, you might have more than one value in each object, for example:-

list.data = [{label:”one”,switch:"on"}, {label:”two”,switch:"off"}, {label:”three”,switch":on"}];

For a divided, or grouped list, use a two dimensional array:-

list.data = [[{label:”one”}, {label:”two”}], [{label:”three”}]];

You can assign XML data like this:-

list.xmlData = <data><one/><two/><three/></data>;

Or this:-

list.xmlData = <data><i label=”one”/><i label=”two”/></data>;

For a divided or grouped list, we would do something like this:-

list.xmlData = <data><group> <one/><two/></group> <group><three/> </group></data>;

Pickers

We use pickers in a similar way to a list. So we can set its data in XML, or using the data or xmlData properties, just like with a list.

The <picker> component tends to be used in conjunction with a <columns> layout. The column layout was described in the first tutorial.

Here is an example a three column picker:-

<columns gapH=”0″ widths=”40,50%,50%” pickerHeight=”200″>

   <picker alignH=”centre”>

   {NUMBERS}

   </picker>

   <picker>

   {DATA}

   </picker>

   <picker>

   {DATA}

   </picker>

</columns>

The pickerHeight attributes enabled you to declare the height of the picker bank.

Here’s a complete code example of using a picker bank:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;

	public class MadComponentsPicker extends Sprite {

		protected static const DATA:XML = <data>
     <Red/>
     <Orange/>
     <Yellow/>
     <Green/>
     <Blue/>
     <Indigo/>
   </data>;

		protected static const PICKER_EXAMPLE:XML = <columns gapH="0" widths="40,50%,50%" pickerHeight="180">
    <picker alignH="centre">
      <data>
         <item label="0"/>
         <item label="1"/>
         <item label="2"/>
         <item label="3"/>
         <item label="4"/>
         <item label="5"/>
         <item label="6"/>
         <item label="7"/>
         <item label="8"/>
         <item label="9"/>
       </data>
    </picker>
    <picker index="1">
        {DATA}
    </picker>
       <picker index="4">
        {DATA}
    </picker>
</columns>;

		public function MadComponentsPicker(screen:Sprite = null) {
			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, PICKER_EXAMPLE);
		}
	}
}

Notice the index attributes in the XML, that set the pickers to initial preset positions.