You can embed data in a Flex application for use by either a specific instance of a list control or as a separate data object that's then linked to a control through a binding expression. Hard-coding means that you declare actual data in the code, rather than retrieving it from an external data source at runtime.

Nesting hard-coded data in a data provider

You can nest hard-coded data in the declaration of a list control's dataProvider by declaring the property with child-element syntax rather than attribute syntax. The following code presents a List control populated with a hard-coded data provider containing simple String values:

<mx:List id="sizeList">
   <mx:dataProvider>
     <mx:String>Small</mx:String>
     <mx:String>Medium</mx:String>
     <mx:String>Large</mx:String>
     </mx:dataProvider>
</mx:List>

You also can declare the dataProvider with hard-coded collections of complex objects by nesting multiple <mx:Object> declarations within the <mx:dataProvider> tag set:

<mx:List id="stateList">
   <mx:dataProvider>
       <mx:Object>
        <label>California</stateName>
        <capitol>Sacramento</capitol>
      </mx:Object>
      <mx:Object>
         <label>Oregon</stateName>

<capitol>Salem</capitol>
         </mx:Object>
         <mx:Object>
           <label>Washington</stateName>
           <capitol>Olympia</capitol>
         </mx:Object>
      </mx:dataProvider>
    </mx:List>

Modifying data with the ArrayCollection API

At runtime, data that's hard-coded within a dataProvider is automatically wrapped inside an ArrayCollection object, so the ArrayCollection API can be used to access and manipulate the data. Even though the original data is hard-coded, this ActionScript statement code would add a new item to the List object's dataProvider when it contains simple String values:

sizeList.dataProvider.addItem('Extra Large'),

And this code would add a new item when it contains complex objects:

stateList.dataProvider.addItem({state:'New York','Albany'});

The application in Listing 17.1 uses a List object with a hard-coded data provider and then allows the user to add data to the object with the ArrayCollection.addItem() method.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   layout="vertical">
  <mx:List id="sizeList" width="300">
     <mx:dataProvider>
         <mx:String>Small</mx:String>
         <mx:String>Medium</mx:String>
         <mx:String>Large</mx:String>
      </mx:dataProvider>
   </mx:List>

<mx:HBox>
 <mx:Label text="New Item:"/>
 <mx:TextInput id="itemInput"/>
<mx:Button label="Add Item"
  click="sizeList.dataProvider.addItem(itemInput.text)"/>
</mx:HBox>

</mx:Application>

Declaring separate data objects with MXML tags

You also can provide hard-coded data to a list control using the <mx:Model>, <mx:Array>, and <mx:ArrayCollection> tags. Regardless of which of these tags you select, the dataProvider of the List object is transformed to an ArrayCollection at runtime, so you should select whichever tag makes most sense to you, keeping in mind that only an ArrayCollection will broadcast updates to properties of complex objects at runtime.

The application in Listing 17.2 declares an Array with the <mx:Array> tag and then provides the data to the List object through a binding expression. Notice that even though the data is declared as an Array, you can still manipulate it at runtime by referencing the List object's dataProvider as an ArrayCollection.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="vertical">
  <mx:Array id="myData">
     <mx:String>Small</mx:String>
     <mx:String>Medium</mx:String>
     <mx:String>Large</mx:String>
</mx:Array>
<mx:List id="sizeList" width="300" dataProvider="{myData}"/>
<mx:HBox>
     <mx:Label text="New Item:"/>
     <mx:TextInput id="itemInput"/>
     <mx:Button label="Add Item"
       click="sizeList.dataProvider.addItem(itemInput.text)"/>
</mx:HBox>
</mx:Application>

Data retrieved from an external source, such as the results of a remote server call through the Remote Procedure Call (RPC) components, or data retrieved from a local database (for an AIR desktop application) is typically stored in an ArrayCollection. As described in Chapter 16, the ArrayCollection object is typically declared in ActionScript code with the [Bindable] metadata tag or in MXML code.

In ActionScript code, the declaration looks like this:

[Bindable]
private var myData:ArrayCollection = new ArrayCollection();

And in MXML, it looks like this:

<mx:ArrayCollection id="myData"/>

Regardless of how the ArrayCollection object is declared, by making it bindable, you make it possible to pass the data to a List control with a simple binding expression:

<mx:List id="sizeList" dataProvider="{myData}"/>

Using RPC components

You can choose to retrieve data dynamically from many sources, including the Flex framework components that are grouped together as the RPC classes. These classes are distinguished from each other by the data format they use to communicate with a remote server:

These components and their methodologies are described starting in Chapter 24. All, however, are capable of returning data sets in the form of ArrayCollection objects that are suitable for use as List control data providers.

Retrieving local data in AIR applications

If you're building an AIR-based desktop application, you can retrieve data from local XML files using the File and FileStream classes or from the local SQLite embedded database with classes such as SQLConnection and SQLStatement. These classes aren't designed to return data in the ArrayCollection format directly; you typically need to manually move data into your data objects with explicit ActionScript code.

Most List controls support the labelField property. This property allows you to indicate which of the named properties of data items in the control's data provider is displayed at runtime.

The default value of labelField is label. As a result, if the data provider's objects have a property named label, that property's value is displayed. In the following code, the stateData Array contains data objects with a label property. The List control displays the label property's value on each of its items:

<mx:Array id="stateData">
    <mx:Object>
      <mx:label>CA</mx:label>
      <mx:capitol>Sacramento</mx:capitol>
   </mx:Object>
  <mx:Object>
    <mx:label>OR</mx:label>
    <mx:capitol>Salem</mx:capitol>
</mx:Object>
</mx:Array>
  <mx:List id="stateList" dataProvider="{stateData}"/>

More commonly, the complex objects in the ArrayCollection have names that are determined by the structure of a database table, XML file, value object, or other existing data source. If you forget to set the labelField property on a List control that displays complex data objects, the control displays labels consisting of a set of [] characters wrapped around the word object and the object's data type. If the data item is cast as an ActionScript Object, the result looks like this:

[object Object]

As shown in Figure 17.2, the results aren't particularly useful, even when working with a value object class.

Figure 17.2. A List control displaying a complex data object with no labelField setting

To fix this behavior, you explicitly set the List control's labelField to the property you want to display:

<mx:Array id="stateData">
     <vo:StateVO>
      <vo:state>CA</vo:state>
      <vo:capitol>Sacramento</vo:capitol>
  </vo:StateVO>
  <vo:StateVO>
      <vo:state>OR</vo:state>
      <vo:capitol>Salem</vo:capitol>
    </vo:StateVO>
  </mx:Array>
   <mx:List id="stateList" dataProvider="{stateData}"
        labelField="state"/>

Figure 17.3 shows the same List control, this time displaying the value of the property named in the control's labelField property.

Figure 17.3. A List control displaying a complex data object with the labelField set to one of the properties of the data provider's complex data objects

The application in Listing 17.3 uses the List control's labelField property to determine which property value of each data object is displayed at runtime.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      xmlns:vo="vo.*">
    <mx:Array id="stateData">
         <vo:StateVO>
            <vo:state>CA</vo:state>
            <vo:capitol>Sacramento</vo:capitol>
        </vo:StateVO>
        <vo:StateVO>
              <vo:state>OR</vo:state>
              <vo:capitol>Salem</vo:capitol>

</vo:StateVO>
<vo:StateVO>
  <vo:state>WA</vo:state>
   <vo:capitol>Washington</vo:capitol>
 </vo:StateVO>
</mx:Array>
<mx:List id="stateList" width="200"
     dataProvider="{stateData}" labelField="capitol"/>
</mx:Application>

Using the labelFunction property

Most List controls implement the labelFunction property to allow you to customize the label that appears on each of the control's items at runtime. The labelFunction property points to the name of a function that follows a specific signature:

[access modifier] function [functionName](item:Object):String

The access modifier for a custom label function can be anything you like, although when you're calling the function from within the same application or component in which it's defined, the access modifier is typically set to private because it's most often used only from within. The name of the function's only argument (item in the example syntax) can be anything you like, but it should be typed as either an Object or a custom class implementing the Value Object design pattern, depending on what type of data is stored in your List's dataProvider collection. And the function always returns a String, because its purpose is to generate a label for the List control's visual items.

At runtime, the List control calls the named function each time it needs to render an item visually. It passes the current data object to the custom function as its item argument and then displays the returned String value. This is an example of a function that's compatible with the labelFunction architecture:

private function getStateLabel(item:StateVO):String
{
  return item.capitol + ", " + item.state;
}

The application in Listing 17.4 displays a List control where each visual item's label is generated by the custom getStateLabel() function.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      xmlns:vo="vo.*">
<mx:Script>
    <![CDATA[
         import vo.StateVO;
         private function getStateLabel(item:StateVO):String
        {
          return item.capitol + ", " + item.state;
        }

]]>
</mx:Script>
<mx:Array id="stateData">
   <vo:StateVO>
   <vo:state>CA</vo:state>
   <vo:capitol>Sacramento</vo:capitol>
</vo:StateVO>
<vo:StateVO>
     <vo:state>OR</vo:state>
     <vo:capitol>Salem</vo:capitol>
</vo:StateVO>
<vo:StateVO>
     <vo:state>WA</vo:state>
     <vo:capitol>Washington</vo:capitol>
   </vo:StateVO>
</mx:Array>
<mx:List id="stateList" width="200"
     dataProvider="{stateData}" labelFunction="getStateLabel"/>
</mx:Application>

The resulting application is shown in Figure 17.4. Notice that each of the List control's labels is generated using both of the data object's named properties, concatenated with literal strings to separate the values.

Figure 17.4. A List control displaying String values calculated in a labelFunction

The change event is implemented in all List controls. It dispatches an event object typed as mx.events.ListEvent, which has a rowIndex property that indicates by index which data item was selected by the user.

You can detect which data item was clicked by the user by using the event object's rowIndex property and passing it to the getItemAt() method of the ArrayCollection data provider:

changeMessage = "You clicked on " +
  event.target.dataProvider.getItemAt(event.rowIndex);

This technique notifies you that the user clicked an item, but it doesn't always indicate that the item returned in the expression event.target.dataProvider.getItemAt(event.rowIndex) is currently selected. In most List controls, the user can hold down Ctrl and click to deselect an item, in which case you get a change event that can't be distinguished from the event that occurs when selecting an item.

A better approach is to use the List control's selectedItem property, which always returns a reference to the currently selected item. In the event the user has deselected all items in a List control, the selectedItem property returns null:

if (event.target.selectedItem == null)
{
   changeMessage = "None selected";
}
else
{
  changeMessage = "You selected " + event.target.selectedItem;
}

The application in Listing 17.5 uses a List control and a change event listener. Each time the change event is dispatched by the List control, an event handler function inspects the control's selectedItem and displays a message indicating which item (if any) is currently selected.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx=http://www.adobe.com/2006/mxml>
  <mx:Script>
    <![CDATA[
      [Bindable]
      private var changeMessage:String="None selected";
      private function changeHandler(event:Event):void
       {
        if (event.target.selectedItem == null)
        {
          changeMessage = "None selected";
        }
        else
        {
           changeMessage = "You selected " +  event.target.selectedItem;
       }
   }
]]>
</mx:Script>
<mx:Array id="myData">
     <mx:String>Small</mx:String>
     <mx:String>Medium</mx:String>
     <mx:String>Large</mx:String>
 </mx:Array>
<mx:List id="sizeList" width="200" dataProvider="{myData}"
     change="changeHandler(event)"/>
<mx:Label text="{changeMessage}" fontSize="12"/>
</mx:Application>

When testing this application, try holding down Ctrl and clicking an item that's already selected. You should see the message "None selected" displayed, because the control's selectedItem property now returns null.

All List controls implement the selectedIndex property, which returns the index position of the control's currently selected item. Because all indexing in ActionScript starts at 0, if the first item is selected the selectedIndex property returns 1, the second returns 2, and so on. When you use a List or ComboBox control in a data entry form, you can place a data item as the first item in a list that indicates that the user is selecting all options:

<mx:ComboBoxid="categoryList"change="changeHandler(event)">
   <mx:dataProvider>
        <mx:String>All Categories</mx:String>
        <mx:String>Comedy</mx:String>
        <mx:String>Drama</mx:String>
        <mx:String>Action</mx:String>
        <mx:String>Horror</mx:String>
  </mx:dataProvider>
</mx:ComboBox>

The following code would detect whether the user has selected the first item, indicating she wants all categories or a specific category:

private function changeHandler(event:Event):void
  {
    if (categoryList.selectedIndex == 0)
    {
       Alert.show("You selected all categories", "Everything!");
    }
    else
    {
      Alert.show("You selected " + categoryList.selectedItem,
         "One Thing!");
    }
  }

If no items are currently selected in a List control, the selectedIndex property returns a value of −1. This is particularly useful when you want to detect a state where the user hasn't yet selected a value from a List or DataGrid control:

private function changeHandler(event:Event):void
{
  if (categoryList.selectedIndex == −1)
  {
     Alert.show("You haven't selected anything!", "Nothin!");
  }
  else
  {
   Alert.show("You selected " + categoryList.selectedItem,
     "One Thing!");
  }
}

When a List control's data provider is a collection of complex objects instead of simple values, you can refer to selected data objects' named properties using either dot syntax or array-style syntax. Dot syntax is more common, because, especially when working with classes that implement the Value Object design pattern, they allow Flex Builder and the compiler to validate property names and provide code completion.

For example, when a user selects an item that represents a complex data object from a List control, you should first cast the control's selectedItem property as the appropriate ActionScript class. You can then refer to the object's named properties and gain the benefit of Flex Builder's and the compiler's syntax checking and code completion tools:

var selectedState:StateVO = stateList.selectedItem as StateVO;
var selectedCapitol = selectedState.capitol;

If you prefer, you can use array-style syntax to refer to a data object's named properties:

var selectedCapitol = stateList.selectedItem["capitol"];

This syntax allows you to use variables containing the names of the properties. The following code would have the same functional result as the other preceding examples:

var fieldName:String = "capitol";
var selectedCapitol = stateList.selectedItem[fieldName];

Particularly when using data model classes that implement the Value Object design pattern, you may want to declare a bindable instance of the class to store the most recently selected data item. This StateVO value object class contains two properties, both of which are bindable due to the use of the [Bindable] metadata tag before the class declaration:

package vo
{
   [Bindable]
   public class StateVO
   {
     public var state:String;
     public var capitol:String;
     public function StateVO()
     {
     }
  }
}

The application in Listing 17.6 uses a ComboBox with a data provider containing multiple instances of a value object class. Upon application startup, and then again when the user selects an item from the control, a reference to the currently selected data item is saved to the selectedState variable.

Notice that this variable is marked as bindable, and its internal [Bindable] tag also marks its properties as bindable. Both levels of "bindability" are required in order for the Label controls to successfully display the selected object's properties whenever the user selects new data.

<?xml version="1.0" encoding="utf-8"?>
 <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
       layout="vertical"
xmlns:vo="vo.*" creationComplete="setSelectedState()">
 <mx:Script>
    <![CDATA[
         import vo.StateVO;
         [Bindable]
         private var selectedState:StateVO;
         private function setSelectedState():void
         {
            selectedState=stateList.selectedItem as StateVO;
        }
]]>
</mx:Script>
<mx:Array id="stateData">
    <vo:StateVO>
         <vo:state>CA</vo:state>
         <vo:capitol>Sacramento</vo:capitol>
   </vo:StateVO>
   <vo:StateVO>
        <vo:state>OR</vo:state>
        <vo:capitol>Salem</vo:capitol7gt;
   </vo:StateVO>
   <vo:StateVO>
         <vo:state>WA</vo:state>
         <vo:capitol>Washington</vo:capitol>
      </vo:StateVO>
  </mx:Array>
  <mx:ComboBox id="stateList"
       dataProvider="{stateData}"
       labelField="capitol"
       change="setSelectedState()"/>
<mx:Label text="Selected State Information:"/>
<mx:Label text="State: {selectedState.state}"/>
<mx:Label text="Capitol: {selectedState.capitol}"/>
</mx:Application>

A drop-in renderer is a visual component that you assign to the List control's itemRenderer or itemEditor properties using its complete package and class name. A limited number of components implement the IDropInListItemRenderer interface, making them eligible for this use. They include:

At runtime, for each item the List control renders, it creates an instance of the visual component you name as the renderer and passes data to the default property for that component. For example, if you use an Image component as your custom renderer, the data is passed to the control's source property. The Label, Text, TextArea, and TextInput controls have a default property of text, and each of the other controls has its own unique property.

If a List control's data provider contains String values, each containing the location of a graphic image you want to display instead of a label, you assign the itemRenderer using the fully qualified name of the component's equivalent ActionScript class:

<mx:List id="answerList" dataProvider="{answerData}"
   itemRenderer="mx.controls.Image"/>

The application in Listing 17.7 uses an ArrayCollection of String values, each containing the name of an image file in the project's source root. The List control's variableRowHeight property is set to true, allowing each row of the control to adjust to the image it displays.

<?xml version="1.0" encoding="utf-8"?>
 <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
        backgroundColor="#EEEEEE">

 <mx:ArrayCollection id="answerData">
 <mx:String>assets/yesImage.png</mx:String>
 <mx:String>assets/noImage.png</mx:String>
 <mx:String>assets/maybeImage.png</mx:String>
</mx:ArrayCollection>

<mx:List id="answerList" dataProvider="{answerData}"
   itemRenderer="mx.controls.Image"
   rowCount="{answerData.length}"
   variableRowHeight="true"
   width="80" height="140"/>

</mx:Application>

Figure 17.5 shows the resulting application. Its List control displays the images based on the values in the control's data provider.

Figure 17.5. A List control with a drop-in item renderer

private function doIt(item:Object):String
    {
       return "http://www.myUrl.com/" + item as String;
    }

An inline renderer is an MXML component that you nest with the declaration of the List control. You first nest a <mx:itemRenderer> or <mx:itemEditor> child element with the List control's MXML tags, and then within that control, you nest a set of <mx:Component> tags. Finally, within the <mx:Component> tags, you nest the control or container from which you want to extend the custom component.

If the custom component you want to use as a custom renderer is extended from the VBox container, the structure of a List control's itemRenderer declaration looks like this:

<mx:List id="myList" dataProvider="{myData}">
     <mx:itemRenderer>
       <mx:Component>
           <mx:VBox>
         ... nested components ...
          </mx:VBox>
     </mx:Component>
    </mx:itemRenderer>
</mx:List>

Every visual component in the Flex framework has a bindable data property designed for use in the custom item renderer architecture. At runtime, the List control creates an instance of the custom component for each of its items and passes the data provider's current data item to the component instance's data property.

Within the component code, you can refer to the current data item in a binding expression to use its information. In the application in Listing 17.8, the List control displays the same image as before, but this time the image location is determined in the custom item renderer by including a literal string in the Image control declaration.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   backgroundColor="#EEEEEE">
    <mx:ArrayCollection id="answerData">
       <mx:String>yesImage.png</mx:String>
       <mx:String>noImage.png</mx:String>
       <mx:String>maybeImage.png</mx:String>
      </mx:ArrayCollection>
   <mx:List id="myList" dataProvider="{answerData}"
     rowCount="{answerData.length}"
     variableRowHeight="true"
     width="80" height="140">
  <mx:itemRenderer>
     <mx:Component>
  <mx:Image source="assets/{data}"/>
</mx:Component>
</mx:itemRenderer>
</mx:List>
</mx:Application>

Using an inline or component renderer also makes working with data providers containing complex objects easier. The List control's data property is data typed as an ActionScript Object and is compatible with any sort of data object that might be passed from the List control's data provider. For example, if the data object has an imageSource property, the custom item renderer can use that property in a binding expression to pass values to its nested visual controls:

<mx:Image source="imageLocation/{data.imageSource}"/>

In the application in Listing 17.9, the List control's data provider contains objects with value and imageSource properties. The Image component used as the custom item renderer receives its source from the data object's imageSource property through a binding expression. The Label control at the bottom of the application displays the value property of the List control's currently selected data object through a binding expression of myList.selectedItem.value.

<?xml version="1.0" encoding="utf-8"?>
 <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
     backgroundColor="#EEEEEE">

<mx:ArrayCollection id="answerData">
  <mx:Object>
   <mx:value>Yes</mx:value>
     <mx:imageSource>yesImage.png</mx:imageSource>
 </mx:Object>
 <mx:Object>
       <mx:value>No</mx:value>
       <mx:imageSource>noImage.png</mx:imageSource>
  </mx:Object>
  <mx:Object>
    <mx:value>Maybe</mx:value>
    <mx:imageSource>maybeImage.png</mx:imageSource>
  </mx:Object>
</mx:ArrayCollection>

<mx:List id="myList" dataProvider="{answerData}"
     rowCount="{answerData.length}"
     variableRowHeight="true"
     width="80" height="140">
     <mx:itemRenderer>
       <mx:Component>
           <mx:Image source="assets/{data.imageSource}"/>
         </mx:Component>
      </mx:itemRenderer>
    </mx:List>
<mx:Label text="{myList.selectedItem.value}"
     fontSize="14"/>


</mx:Application>

A component item renderer is a separate class that can be created as either an MXML component or an ActionScript class that extends an existing visual component from the Flex framework. As with all visual components, the custom component has the same data property as was described in the previous section on inline components. At runtime, the List control creates an instance of the named component for each item it needs to render and passes the data provider's current data object to the component instance's data property.

You create item renderers as MXML components in the same manner as any other component. If you're using Flex Builder, you can use the New MXML Component wizard to create an MXML component source code file.

As with any MXML component, its root element is the visual component that you want your custom component to extend. The objects nested within the component's root element can use the data object and its named properties (determined by the List control's data provider) to display information dynamically.

The custom component in Listing 17.10 extends the VBox container and contains an Image and a Label component. It uses its data property to set the nested object's properties through binding expressions.

<?xml version="1.0" encoding="utf-8"?>
 <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml"
      horizontalAlign="center"
      verticalScrollPolicy="off"
      horizontalScrollPolicy="off">
         <mx:Image source="assets/{data.imageSource}"/>
         <mx:Label text="{data.value}"/>
     </mx:VBox>

You use the custom renderer component with the same syntax as a drop-in renderer, supplying the fully qualified name and path of the component in the List control's itemRenderer or itemEditor property:

<mx:List id="myList" dataProvider="{answerData}"
    itemRenderer="renderers.ImageRenderer"/>

The application in Listing 17.11 uses the custom component renderer to display all of each data object's values.

<?xml version="1.0" encoding="utf-8"?>
 <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      backgroundColor="#EEEEEE">
     <mx:ArrayCollection id="answerData">
    <mx:Object>
    <mx:value>Yes</mx:value>

<mx:imageSource>yesImage.png</mx:imageSource>
</mx:Object>
<mx:Object>
   <mx:value>No</mx:value>
   <mx:imageSource>noImage.png</mx:imageSource>
  </mx:Object>
<mx:Object>
   <mx:value>Maybe</mx:value>
   <mx:imageSource>maybeImage.png</mx:imageSource>
 </mx:Object>
</mx:ArrayCollection>
<mx:List id="myList" dataProvider="{answerData}"
    itemRenderer="renderers.ImageRenderer"
    rowCount="{answerData.length}"
    variableRowHeight="true"
    width="100" height="220"/>
<mx:Label text="{myList.selectedItem.value}"
     fontSize="14"/>
</mx:Application>

Figure 17.6 shows the completed application. Each visual item in the List displays both the Image and the Label, each populated with data from the current data object.

Figure 17.6. Using a component renderer with multiple nested visual components