MX List control

The List control displays a vertical list of items. Its functionality is very similar to that of the SELECT form element in HTML. It often contains a vertical scroll bar that lets users access the items in the list. An optional horizontal scroll bar lets users view items when the full width of the list items is unlikely to fit. The user can select one or more items from the list.

Flex also includes the Spark List control. When possible, Adobe recommends that you use the Spark List control. For more information, see Spark List control.

Note: The HorizontalList, TileList, DataGrid, Menu, and Tree controls are derived from the MX List control or its immediate parent, the MX ListBase class. As a result, much of the information for the List control applies to these controls.

For complete reference information, see the ActionScript 3.0 Reference for the Adobe Flash Platform.

The following image shows a List control:

List control

List control sizing

If you specify horizontalScrollPolicy="on", the default width of a List control does not change; it is still large enough to display the widest visible label. If you set horizontalScrollPolicy="on", and specify a List control pixel width, you can use the measureWidthOfItems() method to ensure that the scroll bar rightmost position corresponds to the right edge of the content, as the following example shows. Notice that the additional 5 pixels ensures that the rightmost character of the text displays properly.

<mx:List id="li2" 
    width="200" horizontalScrollPolicy="on" 
    maxHorizontalScrollPosition="{li2.measureWidthOfItems() - li2.width +5}">

The preceding line ensures that the rightmost position of the scroll bar puts the end of the longest measured list item near the right edge of the List control. Using this technique, however, can reduce application efficiency, so you might consider using explicit sizes instead.

Lists, and all subclasses of the ListBase class, determine their sizes when a style changes or the data provider changes.

If you set a width property that is less than the width of the longest label and specify the horizontalScrollPolicy="off", labels that exceed the control width are clipped.

Creating a List control

You use the <mx:List> tag to define a 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.

The List control uses a list-based data provider. For more information, see Data providers and collections.

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 dataProvider child tag of the <mx:List> tag. In the simplest case for creating a static List control, you need only put <fx:String> tags in the control body, because Flex also automatically interprets the multiple tags as an Array of Strings, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/ListDataProvider.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">

    <mx:List> 
        <mx:dataProvider>
            <fx:String>AK</fx:String>
            <fx:String>AL</fx:String>
            <fx:String>AR</fx:String>
        </mx:dataProvider>
    </mx:List>
</s:Application>

The executing SWF file for the previous example is shown below:

Because the data in this example is inline static data, it is not necessary to explicitly wrap it in an ArrayList or ArrayCollection object. However, when working with data that could change, it is always best to specify a list or collection explicitly; for more information, see Data providers and collections.

The index of items in the List control is zero-based, which means that values are 0, 1, 2, ... , n - 1, where n is the total number of items. The value of the item is its label text.

You typically use events to handle user interaction with a List control. The following example code adds a handler for a change event to the List control. Flex broadcasts a mx.ListEvent.CHANGE event when the value of the control changes due to user interaction.

<?xml version="1.0"?>
<!-- dpcontrols/ListChangeEvent.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>
    
    <fx:Script>
        <![CDATA[
            import flash.events.Event;

            public function changeEvt(event:Event):void {
                forChange.text=event.currentTarget.selectedItem.label + " " +
                event.currentTarget.selectedIndex;
            }
        ]]>
    </fx:Script>

    <mx:List width="35" change="changeEvt(event)"> 
        <fx:Object label="AL" data="Montgomery"/>
        <fx:Object label="AK" data="Juneau"/>
        <fx:Object label="AR" data="Little Rock"/>
    </mx:List>
    <mx:TextArea id="forChange" width="150"/>
</s:Application>

The executing SWF file for the previous example is shown below:

In this example, you use two properties of the List control, selectedItem and selectedIndex, in the event handler. Every change event updates the TextArea control with the label of the selected item and the item’s index in the control.

The target property of the object passed to the event handler contains a reference to the List control. You can reference any control property by using the event’s currentTarget property. The currentTarget.selectedItem field contains a copy of the selected item. If you populate the List control with an Array of Strings, the currentTarget.selectedItem field contains a String. If you populate it with an Array of Objects, the currentTarget.selectedItem field contains the Object that corresponds to the selected item, so, in this case, currentTarget.selectedItem.label refers to the selected item’s label field.

Using a label function

You can pass a label function to the List control to provide logic that determines the text that appears in the control. The label function must have the following signature:

labelFunction(item:Object):String

The item parameter passed in by the Label control contains the list item object. The function must return the string to display in the List control.

Note: Most subclasses of ListBase also take a labelFunction property with the signature described above. For the DataGrid and DataGridColumn controls, the method signature is labelFunction(item:Object, dataField:DataGridColumn):String, where item contains the DataGrid item object, and dataField specifies the DataGrid column.

The following example uses a function to combine the values of the label and data fields for each item for display in the List control:

<?xml version="1.0"?>
<!-- dpcontrols/ListLabelFunction.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" >
    
    <fx:Script>
        <![CDATA[
            public function myLabelFunc(item:Object):String {
                return item.data + ", " + item.label; 
            }
        ]]>
    </fx:Script>

    <fx:Declarations>
        <mx:ArrayList id="myDP">
            <mx:source>
                <fx:Object label="AL" data="Montgomery"/>
                <fx:Object label="AK" data="Juneau"/>
                <fx:Object label="AR" data="Little Rock"/>
            </mx:source>
        </mx:ArrayList>       
    </fx:Declarations>

    <mx:List dataProvider="{myDP}" labelFunction="myLabelFunc"/>
</s:Application>

The executing SWF file for the previous example is shown below:

Note: This example uses anArrayList object as the data provider. You should always use a list or collection as the data provider when the data can change at run time. For more information, see Data providers and collections.

Displaying DataTips

DataTips are similar to ToolTips, but display text when the mouse pointer hovers over a row in a List control. Text in a List control that is longer than the control width is clipped on the right side (or requires scrolling, if the control has scroll bars). DataTips can solve that problem by displaying all of the text, including the clipped text, when the mouse pointer hovers over a cell. If you enable data tips, they only appear for fields where the data is clipped. To display DataTips, set the showDataTips property of a List control to true.

Note: To use DataTips with a DataGrid control, you must set the showDataTips property on the individual DataGridColumns of the DataGrid.

The default behavior of the showDataTips property is to display the label text. However, you can use the dataTipField and dataTipFunction properties to determine what is displayed in the DataTip. The dataTipField property behaves like the labelField property; it specifies the name of the field in the data provider to use as the DataTip for cells in the column. The dataTipFunction property behaves like the labelFunction property; it specifies the DataTip string to display for list items.

The following example sets the showDataTips property for a List control:

<mx:List id="myList" dataProvider="{myDP}" width="220" height="200" showDataTips="true"/>

This example creates the following List control:

List control with a tool tip

Displaying ScrollTips

You use ScrollTips to give users context about where they are in a list as they scroll through the list. The tips appear only when you scroll; they don’t appear if you only hover the mouse over the scroll bar. ScrollTips are useful when live scrolling is disabled (the liveScrolling property is false) so scrolling does not occur until you release the scroll thumb. The default value of the showScrollTips property is false.

The default behavior of the showScrollTips property is to display the index number of the top visible item. You can use the scrollTipFunction property to determine what is displayed in the ScrollTip. The scrollTipFunction property behaves like the labelFunction property; it specifies the ScrollTip string to display for list items. You should avoid going to the server to fill in a ScrollTip.

The following example sets the showScrollTips and scrollTipFunction properties of a HorizontalList control, which shares many of the same properties and methods as the standard List control; for more information about the HorizontalList control, see MX HorizontalList control. The scrollTipFunction property specifies a function that gets the value of the description property of the current list item.

<mx:HorizontalList id="list" dataProvider="{album.photo}" width="100%" 
    itemRenderer="Thumbnail" columnWidth="108" height="100" 
    selectionColor="#FFCC00" liveScrolling="false" showScrollTips="true" 
    scrollTipFunction="scrollTipFunc" 
    change="currentPhoto=album.photo[list.selectedIndex]"/>

This code produces the following HorizontalList control:

HorizontalList control

Vertically aligning text in List control rows

You can use the verticalAlign style to vertically align text at the top, middle, or bottom of a List row. The default value is top. You can also specify a value of middle or bottom.

The following example sets the verticalAlign property for a List control to bottom:

<mx:List id="myList" dataProvider="{myDP}" 
    width="220" height="200" 
    verticalAlign="bottom"/>

Setting variable row height and wrapping List text

You can use the variableRowHeight property to make the height of List control rows variable based on their content. The default value is false. If you set the variableRowHeight property to true, the rowHeight property is ignored and the rowCount property is read-only.

The following example sets the variableRowHeight property for a List control to true:

<mx:List id="myList" dataProvider="{myDP}" 
    width="220" height="200" 
    variableRowHeight="true"/>

You can use the wordWrap property in combination with the variableRowHeight property to wrap text to multiple lines when it exceeds the width of a List row.

The following example sets the wordWrap and variableRowHeight properties to true:

<mx:List id="myList" dataProvider="{myDP}" 
    width="220" height="200" 
    variableRowHeight="true" wordWrap="true"/>

This code produces the following List control:

List control with variable row height

Alternating row colors in a List control

You can use the alternatingItemColors style property to specify an Array that defines the color of each row in the List control. The Array must contain two or more colors. After using all the entries in the Array, the List control repeats the color scheme.

The following example 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.

<mx:List alternatingItemColors="[#66FFFF, #33CCCC]".../> 

Using a custom item renderer

An item renderer is the object that displays a List control’s data items. The simplest way to use a custom item renderer is to specify an MXML component as the value of the itemRenderer property. When you use an MXML component as a item renderer, it can contain multiple levels of containers and controls. You can also use an ActionScript class as a custom item renderer. For detailed information on custom item renderers, see MX item renderers and item editors

The following example sets the itemRenderer property to an MXML component named FancyCellRenderer. It also sets the variableRowHeight property to true because the MXML component exceeds the default row height:

<mx:List id="myList1" dataProvider="{myDP}" 
    width="220" height="200" 
    itemRenderer="FancyItemRenderer" 
    variableRowHeight="true"/>

Specifying an icon to the List control

You can specify an icon to display with each List item, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/ListIcon.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">
    
    <fx:Script>
        <![CDATA[
            [Embed(source="assets/radioIcon.jpg")] 
            public var iconSymbol1:Class; 

            [Embed(source="assets/topIcon.jpg")] 
            public var iconSymbol2:Class; 
        ]]>
    </fx:Script>

   <mx:List iconField="myIcon"> 
      <mx:dataProvider>
         <fx:Array>
            <fx:Object label="AL" data="Montgomery" myIcon="iconSymbol1"/>
            <fx:Object label="AK" data="Juneau" myIcon="iconSymbol2"/>
            <fx:Object label="AR" data="Little Rock" myIcon="iconSymbol1"/>
         </fx:Array>     
      </mx:dataProvider>
   </mx:List>
</s:Application>

The executing SWF file for the previous example is shown below:

In this example, you use the iconField property to specify the field of each item containing the icon. You use the Embed metadata to import the icons, and then reference them in the List control definition.

You can also use the iconFunction property to specify a function that determines the icon, similar to the way that you can use the labelFunction property to specify a function that determines the label text. The icon function must have the following signature:

iconFunction(item:Object):Class

The item parameter passed in by the List control contains the list item object. The function must return the icon class to display in the List control.

The following example shows a List control that uses the iconFunction property to determine the icon to display for each item in the list:

<?xml version="1.0"?>
<!-- dpcontrols/ListIconFunction.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">
    
    <fx:Script>
        <![CDATA[   
            // Embed icons.
            [Embed(source="assets/radioIcon.jpg")] 
            public var pavementSymbol:Class; 

            [Embed(source="assets/topIcon.jpg")] 
            public var normalSymbol:Class;   
      
            // Define data provider.
            private var myDP: Array;
            private function initList():void {
                myDP = [
                    {Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
                    {Artist:'Pavarotti', Album:'Twilight', Price:11.99},
                    {Artist:'Other', Album:'Other', Price:5.99}];
   
                list1.dataProvider = myDP;
            }
   
            // Determine icon based on artist. Pavement gets a special icon. 
            private function myiconfunction(item:Object):Class {
                var type:String = item.Artist;
                if (type == "Pavement") {
                    return pavementSymbol;
                } 
                return normalSymbol;       
            }
        ]]>
    </fx:Script>
   
    <mx:VBox >
        <mx:List id="list1" 
            initialize="initList();" 
            labelField="Artist" 
            iconFunction="myiconfunction" />
    </mx:VBox>
</s:Application>

The executing SWF file for the previous example is shown below:

List control user interaction

The user clicks individual list 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.)

All mouse or keyboard selections broadcast a change event. For mouse interactions, the List control broadcasts this event when the mouse button is released.

If you set the allowDragSelection property to true, the control scrolls up or down when the user presses the mouse button over the one or more rows, holds the mouse button down, drags the mouse outside the control, and then moves the mouse up and down.

A List control shows the number of records that fit in the display. Paging down through the data displayed by a 10-line List control shows records 0-10, 9-18, 18-27, and so on, with one line overlapping from one page to the next.

The List control has the following keyboard navigation features:

Key

Action

Up Arrow

Moves selection up one item.

Down Arrow

Moves selection down one 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.