Spark List control

The Spark List control displays a list of data items. Its functionality is very similar to that of the SELECT form element in HTML. The user can select one or more items from the list. The List control automatically displays horizontal and vertical scroll bar when the list items do not fit the size of the control.

The List control is a subclass of the SkinnableDataContainer container. Therefore, you can set the layout of the List control, apply a skin to it, and define a custom item renderer. For more information on the SkinnableDataContainer container, see The Spark DataGroup and Spark SkinnableDataContainer containers. To define a look and feel of items displayed in the List control, read more about Define a custom Spark item renderer.

Creating a Spark List control

You use the <s:List> tag to define a Spark List control. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

You specify the data for the List control by using the dataProvider property of the control. However, because dataProvider is the List control’s default property, you do not have to specify a <s:dataProvider> child tag of the <s:List> tag, as the following example shows: 
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkListSimpleNoDP.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:List> 
        <mx:ArrayCollection>
            <fx:String>Flash</fx:String> 
            <fx:String>Director</fx:String> 
            <fx:String>Dreamweaver</fx:String> 
            <fx:String>ColdFusion</fx:String> 
        </mx:ArrayCollection>
    </s:List>
</s:Application>
The executing SWF file for the previous example is shown below:
The default skin for the List control, ListSkin, defines scroll bars by including a Scroller component in the skin class. You can reference the Scroller component from the List by using the List.scroller skin part. Therefore, if the data items do not fit in the size of the control, Flex automatically display scroll bars, as the following example shows: 
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkListSimpleScroll.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:List height="100"> 
        <s:dataProvider>
            <mx:ArrayCollection>
                <fx:String>Flex</fx:String> 
                <fx:String>Flash Builder</fx:String> 
                <fx:String>Flash</fx:String> 
                <fx:String>Director</fx:String> 
                <fx:String>Dreamweaver</fx:String> 
                <fx:String>ColdFusion</fx:String> 
                <fx:String>Illustrator</fx:String> 
                <fx:String>PhotoShop</fx:String> 
            </mx:ArrayCollection>
        </s:dataProvider>
    </s:List>
</s:Application>
The executing SWF file for the previous example is shown below:

Using the styles of the Spark List control

The List control defines several styles that you can use to modify the appearance of the control. You can use styles to make some visual changes to the control, but you create a skin for total control over the display.

The following example uses the alternatingItemColors and rollOverColor styles with the List control. The alternatingItemColors styles defines an Array with two entries, #66FFFF for light blue and #33CCCC for a blue-gray. Therefore, the rows of the List control alternate between these two colors. If you specify a three-color array, the rows alternate among the three colors, and so on. 
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\spark\SparkListSimpleStyles.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:List 
        alternatingItemColors="[#66FFFF, #33CCCC]" 
        rollOverColor="#CC6600"> 
        <s:dataProvider>
            <mx:ArrayCollection>
                <fx:String>Flex</fx:String> 
                <fx:String>Flash Builder</fx:String> 
                <fx:String>Flash</fx:String> 
                <fx:String>Director</fx:String> 
                <fx:String>Dreamweaver</fx:String> 
                <fx:String>ColdFusion</fx:String> 
            </mx:ArrayCollection>
         </s:dataProvider>
    </s:List>
</s:Application>
The executing SWF file for the previous example is shown below:

Handling multiple selection in the Spark List control

The List control lets you select multiple items in the control. To enable multiple selection, set the allowMultipleSelection property to true. The default value is false.

After enabling multiple selection, select the first data item in the List by clicking on it. Then hold down the Control key to select additional items. If the item is currently deselected, clicking on it while holding down the Control key selects it. If the item is already selected, clicking on it while holding down the Control key deselects it.

You can also use the Shift key to select a range of data items. To select a range, select the first data item in the List by clicking on it. Then hold down the Shift key to select one additional item. The List control selects all data items between the two data items.

The List control defines two Vector properties that you use with multiple selection: selectedIndices and selectedItems. The selectedIndices Vector is of type int, and the selectedItems Vector is of type Object. These Vectors contain a list of the selected indices and selected data items in the reverse order in which they were selected. That means the first element in each Vector corresponds to the last item selected. The length of each Vector is the same as the number of selected items in the control. If your list contains 100 data items, these Vectors can be up to 100 elements long.

The following example enables multiple selection for the List control. It displays the index of all selected items in one TextArea control, and the data item itself in a second TextArea control: 
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkListSimpleMultipleSelection.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"
    height="450">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <fx:Script>
        <![CDATA[
            import spark.events.IndexChangeEvent;
            
            private function myChangedHandler(event:IndexChangeEvent):void {
                
                var selIndices:Vector.<int> = event.currentTarget.selectedIndices;
                var selItems:Vector.<Object> = event.currentTarget.selectedItems;
                var numItems:Number = selIndices.length;
                
                selIndicesTA.text = "";
                selItemsTA.text = "";
                
                for (var i:Number = 0; i<numItems; i++)
                {
                    selIndicesTA.text = selIndicesTA.text + selIndices[i] + "\n";
                    selItemsTA.text = selItemsTA.text + selItems[i] + "\n";
                }
            }
        ]]>
    </fx:Script>

    <s:List allowMultipleSelection="true"
        change="myChangedHandler(event);"> 
        <mx:ArrayCollection>
            <fx:String>Flex</fx:String> 
            <fx:String>Flash Builder</fx:String> 
            <fx:String>Flash</fx:String> 
            <fx:String>Director</fx:String> 
            <fx:String>Dreamweaver</fx:String> 
            <fx:String>ColdFusion</fx:String> 
        </mx:ArrayCollection>
    </s:List>
    
    <s:Label text="Selected indices"/>
    <s:TextArea id="selIndicesTA" height="75"/>
    <s:Label text="Selected items"/>
    <s:TextArea id="selItemsTA" height="75"/>
</s:Application>
The executing SWF file for the previous example is shown below:

Selecting multiple items does not dispatch the changing event. It only dispatches the change event.

Spark List control user interaction

The user clicks individual data items to select them, and holds down the Control and Shift keys while clicking to select multiple items. You must set the allowMultipleSelection property to true to allow multiple selection.

A List control shows the number of data items that fit in the display. Paging down through the data items displayed by a 10-line List control shows records 0-9, 10-19, 20-29, and so on.

The List control has the following default keyboard navigation features:

Key

Action

Up Arrow

Moves selection up one item. Hold down the Control key (Windows) or Command key (OSX) to only move focus, but not change the selected item.

Down Arrow

Moves selection down one item. Hold down the Control key (Windows) or Command key (OSX) to only move focus, but not change the selected item.

Left Arrow

Moves selection one column to the left, if you are using HorizontalLayout or TileLayout only. Hold down the Control key (Windows) or Command key (OSX) to only move focus, but not change the selected item.

Right Arrow

Moves selection one column to the right, if you are using HorizontalLayout or TileLayout only. Hold down the Control key (Windows) or Command key (OSX) to only move focus, but not change the selected item.

Page Up

Moves selection up one page.

Page Down

Moves selection down one page.

Home

Moves selection to the top of the list.

End

Moves selection to the bottom of the list.

Alphanumeric keys

Jumps to the next item with a label that begins with the character typed.

Control

Toggle key. Allows for multiple (noncontiguous) selection and deselection. Works with key presses, click selection, and drag selection.

Shift

Contiguous selection key. Allows for contiguous selections. Works with key presses, click selection, and drag selection.