List Control and Label Function

The label function in lists is very important when complex manipulation of lists is required (like getting data from external sources, files etc and displaying it when no label property is defined). This gives the solution to the situation when you do not have a label property defined for your items in the data provider collections. You can use the label function as :

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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
    <mx:Script><![CDATA[
        public function myLabelFunc(item:Object):String {
            return item.data + ", " + item.label; 
        }
    ]]></mx:Script>

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

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

This example creates the following List control:

Note: This example uses an ArrayCollection object as the data provider. You should always use a collection as the data provider when the data can change at run time. For more information, see Using 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: