Menu ▾ ▴

Spark List

SourceForge Editorial Staff

Spark List - Functional and Design Specification

Glossary

itemRenderer - The visual representation of an item in a list. In Flex 3, item renderers were only responsible for the display of the item data. In Gumbo, item renderers are responsible for all item interaction in addition to all display, including highlighting and selection.

Summary and Background

The Spark list will aim to be a much more flexible, straightforward, and predictable component. It will contain most of the functionality included in the Halo list: single and multiple selection, keyboard navigation, virtualization and rendering through item renderers. Some functionality will be added in a later release including drag & drop and paged data support.

Goals and Requirements

A Spark list control has the following goals and requirements:

  • Easy to customize:
    • Item display (format, images, colors, etc.)
    • Item highlight/selection
    • Layouts, including custom
    • Scroll bar location, size, and appearance
    • Interaction behavior
  • Expressive:
    • Data/layout effects
    • Item resizing
    • Mixed item types
  • Scalable:
    • Simple lists must be lightweight
    • "Pay as you Go" strategy
    • Additional functionality added through subclassing or aggregation

There are several key differences between the Halo and Spark list control. They are enumerated below:

Layout- The layout and visual appearance of the Spark list (where scrollbars appear, whether the list lays out horizontally, vertically, tile-like, etc) is decoupled from the component logic. The Halo list baked in layout and composite component placement directly into the component class while the Spark list utilizes composition to achieve that extensibility.

Out of the box behavior- The Halo list control baked in higher level functionality like paged-data support directly into the base component. The Spark list control offers basic functionality out of the box (single and multiple selection, item rendering, scrolling support) but higher-level functionality like paged-data is offered by a 'layering' mechanism.

Editability- The Halo list control had a global flag to toggle editability. This added some hairy complexity to the control that we don't want to tackle in the Spark timeframe. Additionally, its relatively straightforward to extend the Spark list to include the concept of an editable state and author an edit-aware skin.

Items for display- The Halo list control could only display UIComponents. The Spark list can display raw data-items (non-display objects) by having them auto-wrapped by renderers as well as visual primitives (which includes UIComponents and graphic elements).

Additionally, the Halo list control expected all data items in the data provider to be unique (or to implement IUID for uniqueness). In Spark, this restriction has been lifted. So, the following list will work correctly (hovering, selection, etc). 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List>
        <s:ArrayCollection>
            <fx:String>Flex</fx:String>
            <fx:String>Flex</fx:String>
            <fx:String>Flex</fx:String>
        </s:ArrayCollection>
    </s:List>

</s:Application>

Selection- Like the Halo list, the Spark list will support both single and multiple selection. Selection changes can be intercepted in order to cancel or modify the default selection behavior.

Item Renderers- The Halo list had a default item renderer and developers could create their own item renderers in MXML or in ActionScript. Similarly, the Spark list allows for item renderers to be used as the visual representation of a data item in its data provider. This is all behavior built into DataGroup - please review that spec for details on item renderer creation and management. The key thing to note is that DataGroup, and thus Spark List, allows for the conditional creation of item renderers with the itemRendererFunction property. More information specific to Spark item renderers can be read in the Item Renderer spec.

Additionally, in Spark, item renderers have behaviors as well as appearance. Item renderers (governed by the spark.components.supportClasses.ItemRenderer baseclass) have a default set of states: "normal", "hovered", "selected", "normalAndCaret", "hoveredAndCaret" and "selectedAndCaret". A Spark list can put its item renderers into these states, and the item renderer can update visually however it desires. Users can extend item renderers to add in their own custom states as well as change the appearance of the renderer in default states. There are examples below showing off this behavior.

Usage Scenarios

The Detailed Description section includes usage scenarios for all features.

Detailed Description

Basic List

The simplest Spark list consists of a collection of objects (typically Strings). The inherited dataProvider property (from DataGroup) specifies the items in the list. In Spark, DataGroup's dataProvider property is typed to only take objects of IList.

The inherited layout property can be used to specify a different layout for the items. The default layout is vertical.

When no itemRenderer is specified, the list uses the DefaultItemRenderer to render the data items.

A Spark list has no required or optional parts, by default. It inherits the dataGroup part from SkinnableDataContainer. A spark lists's required states are the normal and disabled states.

Example: Simple list.

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List>
        <s:ArrayCollection>
            <fx:String>Ely</fx:String>
            <fx:String>Glenn</fx:String>
            <fx:String>Evtim</fx:String>
        </s:ArrayCollection>
    </s:List>

</s:Application>

!Picture 2.png!

Example: List with tile layout.

Here we use assignable layout so that the list lays its renderers out in a tile-like fashion. 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List>
        <s:layout>
            <s:TileLayout />
        </s:layout>
        <s:ArrayCollection>
            <fx:String>Ely</fx:String>
            <fx:String>Glenn</fx:String>
            <fx:String>Evtim</fx:String>
            <fx:String>Ryan</fx:String>
            <fx:String>Jason</fx:String>
            <fx:String>Corey</fx:String>
            <fx:String>Deepa</fx:String>
            <fx:String>Gordon</fx:String>
            <fx:String>Chet</fx:String>
            <fx:String>Hans</fx:String>
        </s:ArrayCollection>
    </s:List>

</s:Application>

!Picture 4.png!

Simple item renderers

Custom item renderers use the root tag ItemRenderer, and can contain "normal", "hovered", "selected", "normalAndCaret"", "hoveredAndCaret" and "selectedAndCaret"" states. The item renderer is responsible for ALL visual aspects of the item, including highlight and selected states. There are no required states for an ItemRenderer, however most item renderers should author for the "normal", "hovered", "selected" states since those are most common to lists. Spark item renderers are only put into one of the states listed above if the renderer defines that state.

The ItemRenderer class has a data property that is a reference to the item in the data provider.

Gumbo packages up two default item renderers: DefaultItemRenderer, which simply displays a SimpleText for the renderer's data, and DefaultComplexItemRenderer which exposes a content group that other components can be added to.

By default, Spark lists use a DefaultItemRenderer in the DataGroup part contained in the Spark List skin. If the itemRenderer property has been set by the component or in the skin, that renderer is what is used.

Example: Simple item renderer

This list explicitly uses the DefaultComplexItemRenderer to display a bunch of Image components as the renderer by setting the itemRenderer property. 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List itemRenderer="spark.skins.default.DefaultComplexItemRenderer">
        <s:ArrayCollection>
            <mx:Image source="assets/lion1.jpg" />
            <mx:Image source="assets/lion2.jpg" />
            <mx:Image source="assets/lion3.jpg" />
        </s:ArrayCollection>
    </s:List>

</s:Application>

The List above renders as such:

!Picture 9.png!

Example: Simple custom item renderer

Here, the user writes a custom renderer as a separate file. Note, ItemRenderer is the top-level tag for their renderer. The ItemRenderer defines the selected, hovered and normal states for visual distinction when the renderers are interacted with.

MyApp.mxml 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List itemRenderer="spark.skins.default.DefaultComplexItemRenderer">
        <s:ArrayCollection>
            <mx:Image source="assets/lion1.jpg" />
            <mx:Image source="assets/lion2.jpg" />
            <mx:Image source="assets/lion3.jpg" />
        </s:ArrayCollection>
    </s:List>

</s:Application>

ColorRenderer.mxml 

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/halo">
    <s:states>
        <s:State name="normal" />
        <s:State name="hovered" />
        <s:State name="selected" />
    </s:states>

    <!-- hover/select highlight -->
    <s:Rect left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0x000000"
                        alpha="0" alpha.hovered="0.1" alpha.selected="0.4" />
        </s:fill>
    </s:Rect>

    <!-- color name -->
    <s:SimpleText text="{data.name}" width="100" verticalCenter="0" fontFamily="Arial" />

    <!-- color swatch -->
    <s:Rect right="5" width="20" height="20">
        <s:fill>
            <s:SolidColor color="{data.rgb}" />
        </s:fill>
    </s:Rect>

</s:ItemRenderer>

The same list can be written with the item renderer declared inline, like so:

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List>
        <s:itemRenderer>
            <fx:Component>
                <s:ItemRenderer>
                    <s:states>
                        <s:State name="normal" />
                        <s:State name="hovered" />
                        <s:State name="selected" />
                    </s:states>

                    <!-- hover/select highlight -->
                    <s:Rect left="0" right="0" top="0" bottom="0">
                        <s:fill>
                            <s:SolidColor color="0x000000"
                                    alpha="0" alpha.hovered="0.1" alpha.selected="0.4" />
                        </s:fill>
                    </s:Rect>

                    <!-- color name -->
                    <s:SimpleText text="{data.name}" width="100" verticalCenter="0" fontFamily="Arial" />

                    <!-- color swatch -->
                    <s:Rect right="5" width="20" height="20">
                        <s:fill>
                            <s:SolidColor color="{data.rgb}" />
                        </s:fill>
                    </s:Rect>
                </s:ItemRenderer>
            </fx:Component>
        </s:itemRenderer>
        <s:ArrayCollection>
            <fx:Object name="Red" rgb="0xFF0000" />
            <fx:Object name="Green" rgb="0x00FF00" />
            <fx:Object name="Blue" rgb="0x0000FF" />
            <fx:Object name="Cyan" rgb="0x00FFFF" />
            <fx:Object name="Yellow" rgb="0xFFFF00" />
        </s:ArrayCollection>
    </s:List>

</s:Application>

Both code examples above result in a List that looks like this:

!Picture 5.png!

Resizing item renderer

The List component uses the same layout classes as all other containers in Gumbo. Relative layouts like VerticalLayout and HorizontalLayout can work with variable sized items. Standard Flex transitions can be used within an item to provide smooth effects when changing the size of an item.

Example: Resizing item renderer with transitions

This example shows an item renderer that is small in its "normal" state and expanded in its "hovered" and "selected" states. Transitions are used to smoothly expand and collapse the items.

MyApp.mxml 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List itemRenderer="ResizingRenderer">
        <s:ArrayCollection>
            <fx:Object firstName="Bob" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
            <fx:Object firstName="John" lastName="Smith" phone="415-555-1212" 
                    department="Marketing" />
            <fx:Object firstName="Linda" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
            <fx:Object firstName="Steve" lastName="Smith" phone="415-555-1212" 
                    department="Marketing" />
            <fx:Object firstName="Mary" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
        </s:ArrayCollection>
    </s:List>

</s:Application>

ResizingRenderer.mxml 

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/halo">
    <s:states>
        <s:State name="normal" />
        <s:State name="hovered" />
        <s:State name="selected" />
    </s:states>

    <s:transitions>
        <s:Transition fromState="normal">
            <s:Sequence>
                <s:Resize target="{this}" />
             </s:Sequence>
        </s:Transition>
        <s:Transition toState="normal">
            <s:Sequence>
                <s:Resize target="{this}" />
            </s:Sequence>
        </s:Transition>
    </s:transitions>

    <!-- hover/select highlight -->
    <s:Rect left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0x000088" alpha="0" 
                 alpha.hovered="0.1" alpha.selected="0.4" />
        </s:fill>
    </s:Rect>

    <!-- name -->
    <s:SimpleText text="{data.firstName} {data.lastName}" fontFamily="Arial" fontWeight="bold" 
             left="3" top="3" right="10" bottom="3" />

    <!-- department and phone -->
    <s:SimpleText includeIn="hovered, selected" id="dept" text="{data.department}" 
             fontFamily="Arial" top="20" left="3" />
    <s:SimpleText includeIn="hovered, selected" id="phone" text="{data.phone}" 
             fontFamily="Arial" top="38" left="3" />

</s:ItemRenderer>

!Picture 7.png!

Adding states to an item renderer

The default states of the pre-packaged spark renderers are normal, hovered, selected, normalAndCaret, hoveredAndCaret, and selectedAndCaret. You can add more states by overriding the getCurrentRendererState().

The next example is similar to the previous one, except each item has a "disclosure" arrow that is used to expand or collapse the item. The expanded state is independent from the standard "normal", "hovered", and "selected" states.

Example: Adding states to an item renderer

MyApp.mxml 

<?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <s:List itemRenderer="ResizingRenderer">
        <s:ArrayCollection>
            <fx:Object firstName="Bob" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
            <fx:Object firstName="John" lastName="Smith" phone="415-555-1212" 
                    department="Marketing" />
            <fx:Object firstName="Linda" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
            <fx:Object firstName="Steve" lastName="Smith" phone="415-555-1212" 
                    department="Marketing" />
            <fx:Object firstName="Mary" lastName="Smith" phone="415-555-1212" 
                    department="Sales" />
        </s:ArrayCollection>
    </s:List>

</s:Application>

ResizingRendererWithStates.mxml 

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/halo">

    <fx:Script>
        <![CDATA[
            // Flag for expanded state
            protected var expanded:Boolean = false;

            // Toggle the expanded state of the renderer
            protected function toggleExpand():void
            {
               expanded = !expanded;
               currentState = getCurrentRendererState();
            }

            // Override getCurrentRendererState(). The superclass returns
            // "normal", "hovered","selected", "normalAndCaret", 
            // "hoveredAndCaret", "selectedAndCaret". This method appends
            // "AndExpanded" if we are expanded.
            override protected function getCurrentRendererState():String
            {
               var skinState:String = super.getCurrentRendererState();

               if (expanded)
                   skinState += "AndExpanded";

               return skinState;
            }
        ]]>
    </fx:Script>

    <!-- Declare the states for this renderer. 
      State groups are used to simplify the markup below. -->
    <s:states>
        <s:State name="normal" />
        <s:State name="normalAndCaret" />
        <s:State name="hovered" stateGroups="hoveredGroup" />
        <s:State name="selected" stateGroups="selectedGroup" />
        <s:State name="hoveredAndCaret" stateGroups="hoveredGroup" />
        <s:State name="selectedAndCaret" stateGroups="selectedGroup" />
        <s:State name="normalAndExpanded" stateGroups="expandedGroup" />
        <s:State name="normalAndCaretAndExpanded" stateGroups="expandedGroup" />
        <s:State name="hoveredAndExpanded" stateGroups="hoveredGroup, expandedGroup" />
        <s:State name="selectedAndExpanded" stateGroups="selectedGroup, expandedGroup" />
        <s:State name="selectedAndCaretAndExpanded" stateGroups="selectedGroup, expandedGroup" />

    </s:states>

    <!-- hover/select highlight -->
    <s:Rect left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0x000088" alpha="0" 
                 alpha.hoveredGroup="0.1" alpha.selectedGroup="0.4" />
        </s:fill>
    </s:Rect>

    <!-- expand arrow -->
    <s:Group click="toggleExpand()">    
        <s:Path data="M 3 3 l 5 5 l -5 5 z" 
                  data.expandedGroup="M 3 3 h 10 l -5 5 z" 
                  id="arrow">
            <s:fill>
                <s:SolidColor color="0x444444" />
            </s:fill>
        </s:Path>
    </s:Group>

    <!-- name -->
    <s:SimpleText text="{data.firstName} {data.lastName}" 
             fontFamily="Arial" fontWeight="bold" 
             left="20" top="3" right="10" bottom="3" />

    <!-- department and phone -->
    <s:SimpleText includeIn="expandedGroup" text="{data.department}" 
             fontFamily="Arial" top="20" left="20" />
    <s:SimpleText includeIn="expandedGroup" text="{data.phone}" 
             fontFamily="Arial" top="38" left="20" />

</s:ItemRenderer>

!Picture 7.png!

Using itemRendererFunction

Inherited from DataGroup is the itemRendererFunction property. Using this, you can conditionally choose which renderer to use for an item in the data provider.

The following example shows how an itemRendererFunction is used to display managers in red and employees in black.

MyApp.mxml 

       <?xml version="1.0" encoding="utf-8"?>
<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/halo">

    <fx:Script>
        <![CDATA[
            import ManagerRenderer;
            import EmployeeRenderer;
            import spark.skins.default.DefaultItemRenderer;
            import mx.core.ClassFactory;

            private function introspectRole(item:Object):IFactory {
                if (item.role == "employee") {
                    return new ClassFactory(EmployeeRenderer);
                } else if (item.role == "manager") {
                    return new ClassFactory(ManagerRenderer);   
                } else { 
                    return new ClassFactory(DefaultItemRenderer);
                }
            }
        ]]>
    </fx:Script>

    <s:List width="200" itemRendererFunction="introspectRole">
        <s:ArrayCollection>
            <fx:Object firstName="Ely" lastName="Greenfield" role="employee"/>
            <fx:Object firstName="Steve" lastName="Breinberg" role="manager"/>
            <fx:Object firstName="Glenn" lastName="Ruehle" role="employee"/>
            <fx:Object firstName="Evtim" lastName="Georgiev" role="employee"/>
            <fx:Object firstName="Susan" lastName="Lally" role="manager"/>
            <fx:Object firstName="Ryan" lastName="Frishberg" role="employee"/>
        </s:ArrayCollection>
    </s:List>

</s:Application>

EmployeeRenderer.mxml 

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/halo">
    <s:states>
        <s:State name="normal" />
        <s:State name="hovered" />
        <s:State name="selected" />
    </s:states>

    <!-- hover/select highlight -->
    <s:Rect left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0x000088"
                        alpha="0" alpha.hovered="0.1" alpha.selected="0.4" />
        </s:fill>
    </s:Rect>

    <!-- name -->
    <s:SimpleText text="{data.firstName} {data.lastName}" fontFamily="Arial" fontWeight="bold" 
             left="3" top="3" right="10" bottom="3" color="0x000000"/>

</s:ItemRenderer>

ManagerRenderer.mxml 

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/halo">
    <s:states>
        <s:State name="normal" />
        <s:State name="hovered" />
        <s:State name="selected" />
    </s:states>

    <!-- hover/select highlight -->
    <s:Rect left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0x000088"
                        alpha="0" alpha.hovered="0.1" alpha.selected="0.4" />
        </s:fill>
    </s:Rect>

    <!-- name -->
    <s:SimpleText text="{data.firstName} {data.lastName}" fontFamily="Arial" fontWeight="bold" 
             left="3" top="3" right="10" bottom="3" color="0xFF0000"/>

</s:ItemRenderer>

!Picture 8.png!

Displaying data

The ItemRenderer base class has a property, data, which is the reference to the item in the data provider that renderer is visualizing. The Spark list will provide the labelField and labelFunction properties to control what text is displayed by each renderer. Like in Halo, labelFunction beats out labelField.

labelField and labelFunction are implemented by using the method, List.itemToLabel which stuffs into the renderer the correct text to display given a data item, a labelField and a labelFunction.

With the Spark list, other amenities like iconField and iconFunction are not needed as they were in Halo. If users want to display icons based on data in their item renderers, they can simply write custom renderers since that is so much easier in spark.

Single Selection

Single selection is governed by the spark.components.supportClasses.ListBase class, a shared baseclass for single selection-aware controls like the Spark list and Spark button bar controls. Subclasses dictate the behavior when an item is selected. In a Spark list, the corresponding renderer is put into the selected state.

Like the Halo ListBase class, Spark ListBase exposes the selectedIndex and selectedItem properties to track single selection. Like Halo, the Spark list handles the re-jiggering of selection when items are added or deleted in the dataProvider and items can be de-selected by the Command/Ctrl keys on the keyboard and selecting with the mouse.

There are a few key difference in single selection between the Spark ListBase and Halo ListBase classes. A new API, requiresSelection has been added. When true, selectedIndex is always set to a value between 0 and dataProvider.length - 1, or -1 if there are no items. If no selectedIndex or selectedItem is set by default, the first item in the ListBase-derived control is selected.

When an item has been selected, the selectionChanged event is fired. When an item is about to be selected, the selectionChanging event is fired. Users can opt to cancel or modify the default selection behavior before it is committed by listening to the selectionChanging event. Both events dispatch an IndexChangedEvent-type event object, which contains information about the old and new selection indices.

Multiple Selection

Multiple selection is implemented at the List-class level (single-selection is inherited from Spark ListBase). Users opt in for multiple-selection by setting the allowMultipleSelection property to true.

Like Halo multiple selection, Spark multiple selection provides the selectedIndices and selectedItems properties. Like Halo, the multiple selection properties are kept in-sync with the single-selection properties for consistency across the selection model. This means that even when a Spark List is in single-selection mode (ie: allowMultipleSelection is false), selectedItems and selectedIndices are kept in-sync with selectedIndex and selectedItem. Given the code below 

<s:List allowMultipleSelection="false">
    <s:ArrayCollection>
        <fx:String>Apple</fx:String>
    <fx:String>Banana</fx:String>
    <fx:String>Orange</fx:String>
    <fx:String>Kiwi</fx:String>
    <fx:String>Mango</fx:String>
    </s:ArrayCollection>
</s:List>

And the user selects Banana, the selection properties are: 

selectedIndex = 1
selectedItem = Banana
selectedIndices = <a href="1">1</a>
selectedItems = <a href="Banana">Banana</a>

Multiple selection will not send selectionChanging events, but only a single selectionChanged event when the selection has changed. selectionChanging was primarily so people could cancel out of selection and there is no good use-case for people needing that with multiple selection.

And finally, to aid folks in determining whether a particular item is selected, there is the inherited convenience method to determine that. 

    /**
     *  Returns true if the item at the index is selected.
     */
    override public function isItemIndexSelected(index:int):Boolean{};

Scrolling

By default, the Spark list skin has an Scroller wrapping its required dataGroup part. This automatically adds scrolling behavior to the list. As such, there is the optional part, Scroller which gets set if a Scroller is detected in the List skin.

Unlike Halo, there are no scroll policy properties to govern when the horizontal and vertical scrollbars appear. Instead, we rely on skinning for this functionality. To change the scroll policies of a Spark List, you could reskin the list control and set the verticalScrollPolicy and horizontalScrollPolicy properties on the FxScroller in the skin itself. In subsequent releases of Spark, we could potentially provide customized subclasses, ie: VerticalList, HorizontalList and TileList which offer these convenience properties settable on the List itself. However, in Flex 4, skinning the List control or configuring the layout object in markup are the ways to control scroller and layout properties directly on the List.

Placement and sizing of the scrollbars and their related parts can also be controlled through the list skin.

Keyboard Navigation

The Spark list delegates to a method in the layout to figure out the next index to navigate to based on the current index and the key stroke that came in. The following method is being added to LayoutBase (a shared base-class between all concrete layouts in Spark, and the class which those writing custom layouts will naturally extend):

LayoutBase.as 

    /**
     *  Delegation method that determines which item  
     *  to navigate to based on the current item in focus 
     *  and user input in terms of NavigationUnit. This method
     *  is used by derivatives of ListBase to handle 
     *  keyboard navigation. ListBase maps user input to
     *  NavigationUnit constants.
     * 
     *  Subclasses can override this method to compute other 
     *  values that are based on the current index and key 
     *  stroke encountered. 
     * 
     *  @param navigationUnit The NavigationUnit constant that determines
     *  which item to navigate to next.  
     * 
     *  @param currentIndex The current index of the item with focus.
     * 
     *  @return The index of the next item to jump to. Returns -1
     *  when if the layout doens't recognize the navigationUnit.  
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */  
     public function getDestinationIndex(navigationUnit:uint, currentIndex:int):int

Subclasses of LayoutBase, like VerticalLayout, HorizontalLayout and TileLayout implement this method in order to translate key events into the index of the next item to navigate to.

For example, in vertical and horizontal layouts, Left/Up keys will result in nextItemIndex returning index-1. Right/Down keys will result in nextItemIndex returning index+1. Home and End keys will be treated the same as in Halo as well as PageUp and PageDown.

Additionally, we will match the Halo functionality where when a list control is in focus, typing a letter will jump to the item whose first letter matches that key stroke. This method, findKey can be overridden by users to do fancier type-lookup support.

Caret support

In Halo, navigating a list control with the arrow-keys on the keyboard always caused the selection to change. For example, when you tabbed into a Halo list control and pressed the Down arrow-key, the first item in the list was selected and the selectedIndex property updated. You could hold down modifier keys (Apple-key on the Mac, Alt-key on Win) to focus into the item without selecting it. A non-solid rectangle was drawn around the item (captured in the image below). You could then select the item by clicking the space-bar. This behavior to divorce selection from keyboard navigation was called 'caret'.

!Picture 1.png!

In Gumbo, we will codify this behavior even further. As items are selected, that item is tracked as the item that is currently in caret mode (also can be thought of as the current item in focus). This item index can be queried by the read-only property getCurrentCaretIndex. As items are brought into focus, either by selection through the mouse or keyboard navigation, or brought into focus by holding the Command/Ctrl key down and navigating into caret mode, getCurrentCaretIndex is updated to reflect the current item in focus. It is off this index that keyboard interactions are based.

As an item is brought into focus, the IndexChangedEvent.itemFocusChanged event is dispatched. Users can query the oldIndex and newIndex properties to determine which item lost focus and which item gained focus.

Virtualization

Virtualization has been built directly into the concrete layouts in Gumbo. Spark lists provide a useVirtualLayout property, which defaults to true, such that Spark lists are virtualized by default. This property reaches down and sets the useVirtualLayout property on the layout.

<List dataProvider="{employeeList}">
    <layout>
        <VerticalLayout useVirtualLayout="true" />
    </layout>
</List>

is equivalent to: 

<List dataProvider="{employeeList}" />

And virtualization can be turned off by writing: 

<List dataProvider="{employeeList}" useVirtualLayout="false"/>

See Hans' Virtualization spec for more details.

Styles

The Spark list control introduces the following styles:

alternatingItemColors contentBackgroundColor rollOverColor selectionColor *symbolColor

The Spark list control also inherits styles from SkinnableDataContainer.

Skinning

The Spark list control has an associated skin, as defined by ListSkin.mxml. The skin specifies two skin states the component can go into: normal and disabled. Along with the visuals that dictate how the component looks in its two states, the skin contains the required part, dataGroup with an optional part Scroller wrapping it in order to add scrolling capabilities.

The default layout of a Spark list is vertical, as defined in the skin.

API Description

ListBase.as

////////////////////////////////////////////////////////////////////////////////
//
//  ADOBE SYSTEMS INCORPORATED
//  Copyright 2008 Adobe Systems Incorporated
//  All Rights Reserved.
//
//  NOTICE: Adobe permits you to use, modify, and distribute this file
//  in accordance with the terms of the license agreement accompanying it.
//
////////////////////////////////////////////////////////////////////////////////

package spark.components.supportClasses
{
import flash.events.Event;

import spark.events.RendererExistenceEvent;
import spark.components.SkinnableDataContainer;
import spark.components.IItemRendererOwner; 
import spark.components.IItemRenderer; 
import spark.layouts.supportClasses.LayoutBase;
import spark.utils.LabelUtil;

import mx.collections.IList;
import mx.core.IVisualElement;
import mx.core.mx_internal;
import mx.core.UIComponent; 
import mx.events.FlexEvent;
import mx.events.IndexChangedEvent;
import mx.events.CollectionEvent;
import mx.events.CollectionEventKind;

use namespace mx_internal;  //ListBase and List share selection properties that are mx_internal

/**
 *  Dispatched when the selection is going to change. 
 *  Calling the <code>preventDefault()</code> method
 *  on the event prevents the selection from changing.
 *
 *  @eventType mx.events.IndexChangedEvent.SELECTION_CHANGING
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Event%28name%3D%26quot%3BselectionChanging%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="selectionChanging", type="mx.events.IndexChangedEvent")</a>

/**
 *  Dispatched after the selection has changed. 
 *
 *  @eventType mx.events.IndexChangedEvent.SELECTION_CHANGED
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Event%28name%3D%26quot%3BselectionChanged%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="selectionChanged", type="mx.events.IndexChangedEvent")</a>

/**
 *  Dispatched after the focus has changed.  
 *
 *  @eventType mx.events.IndexChangedEvent.ITEM_FOCUS_CHANGED
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Event%28name%3D%26quot%3BitemFocusChanged%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="itemFocusChanged", type="mx.events.IndexChangedEvent")</a>

/**
 *  The ListBase class is the base class for all components that support
 *  selection. 
 *
 *  @mxml <p>The <code>&lt;ListBase&gt;</code> tag inherits all of the tag 
 *  attributes of its superclass and adds the following tag attributes:</p>
 *
 *  <pre>
 *  &lt;ListBase
 *
 *    <strong>Properties</strong>
 *    dataProvider="null"
 *    labelField="null"
 *    labelFunction="null"
 *    requiresSelection="false"
 *    selectedIndex="-1"
 *    selectedItem="undefined"
 *    useVirtualLayout="false"
 * 
 *    <strong>Events</strong>
 *    itemFocusChanged="<i>No default</i>"
 *    selectionChanged="<i>No default</i>"
 *    selectionChanging="<i>No default</i>"
 *  /&gt;
 *  </pre>
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
public class ListBase extends SkinnableDataContainer 
{

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  Constructor.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function ListBase()
    {
        super();
    }

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    //----------------------------------
    //  currentCaretIndex
    //----------------------------------

    mx_internal var _currentCaretIndex:Number = NO_CARET;

    <a href="Bindable%28%26quot%3BitemFocusChanged%26quot%3B%29">Bindable("itemFocusChanged")</a>
    /**
     *  Item that is currently in focus. 
     *
     *  @default -1
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get currentCaretIndex():Number


    //----------------------------------
    //  labelField
    //----------------------------------

    /**
     *  The name of the field in the data provider items to display 
     *  as the label. 
     *  The <code>labelFunction</code> property overrides this property.
     *
     *  @default null 
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get labelField():String
    public function set labelField(value:String):void

    //----------------------------------
    //  labelFunction
    //----------------------------------


    /**
     *  A user-supplied function to run on each item to determine its label.  
     *  The <code>labelFunction</code> property overrides 
     *  the <code>labelField</code> property.
     *
     *  <p>You can supply a <code>labelFunction</code> that finds the 
     *  appropriate fields and returns a displayable string. The 
     *  <code>labelFunction</code> is also good for handling formatting and 
     *  localization. </p>
     *
     *  <p>The label function takes a single argument which is the item in 
     *  the data provider and returns a String.</p>
     *  <pre>
     *  myLabelFunction(item:Object):String</pre>
     *
     *  @default null
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get labelFunction():Function
    public function set labelFunction(value:Function):void


    //----------------------------------
    //  selectedIndex
    //----------------------------------

    <a href="Bindable%28%26quot%3BselectionChanged%26quot%3B%29">Bindable("selectionChanged")</a>
    /**
     *  The 0-based index of the selected item, or -1 if no item is selected.
     *  Setting the <code>selectedIndex</code> property deselects the currently selected
     *  item and selects the data item at the specified index.
     *
     *  <p>The value is always between -1 and (<code>dataProvider.length</code> - 1). 
     *  If items at a lower index than <code>selectedIndex</code> are 
     *  removed from the component, the selected index is adjusted downward
     *  accordingly.</p>
     *
     *  <p>If the selected item is removed, the selected index is set to:</p>
     *
     *  <ul>
     *    <li>-1 if <code>requiresSelection</code> = <code>false</code> 
     *     or there are no remaining items.</li>
     *    <li>0 if <code>requiresSelection</code> = <code>true</code> 
     *     and there is at least one item.</li>
     *  </ul>
     *
     *  @default -1
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get selectedIndex():int
    public function set selectedIndex(value:int):void

    //----------------------------------
    //  selectedItem
    //----------------------------------

    <a href="Bindable%28%26quot%3BselectionChanged%26quot%3B%29">Bindable("selectionChanged")</a>
    /**
     *  The item that is currently selected. 
     *  Setting this property deselects the currently selected 
     *  item and selects the newly specified item.
     *
     *  <p>Setting <code>selectedItem</code> to an item that is not 
     *  in this component results in no selection, 
     *  and <code>selectedItem</code> being set to <code>undefined</code>.</p>
     * 
     *  <p>If the selected item is removed, the selected item is set to:</p>
     *
     *  <ul>
     *    <li><code>undefined</code> if <code>requiresSelection</code> = <code>false</code> 
     *      or there are no remaining items.</li>
     *    <li>The first item if <code>requiresSelection</code> = <code>true</code> 
     *      and there is at least one item.</li>
     *  </ul>
     *
     *  @default undefined
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get selectedItem():*
    public function set selectedItem(value:*):void


    //----------------------------------
    //  requiresSelection
    //----------------------------------

    /**
     *  If <code>true</code>, a data item must always be selected in the control.
     *  If the value is <code>true</code>, the <code>selectedIndex</code> property 
     *  is always set to a value between 0 and (<code>dataProvider.length</code> - 1), 
     *
     *  @default false
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get requiresSelection():Boolean
    public function set requiresSelection(value:Boolean):void


    //----------------------------------
    //  useVirtualLayout
    //----------------------------------
    /**
     *  Sets the value of the <code>useVirtualLayout</code> property
     *  of the layout associated with this control.  
     *  If the layout is subsequently replaced and the value of this 
     *  property is <code>true</code>, then the new layout's 
     *  <code>useVirtualLayout</code> property is set to <code>true</code>.
     *
     *  @default false
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get useVirtualLayout():Boolean

    /**
     *  @private
     *  Note: this property deviates a little from the conventional delegation pattern.
     *  If the user explicitly sets ListBase.useVirtualLayout=false and then sets
     *  the layout property to a layout with useVirtualLayout=true, the layout's value
     *  for this property trumps the ListBase.  The convention dictates opposite
     *  however in this case, always honoring the layout's useVirtalLayout property seems 
     *  less likely to cause confusion.
     */
    public function set useVirtualLayout(value:Boolean):void


    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------


    /**
     *  Called when an item is selected or deselected. 
     *  Subclasses must override this method to display the selection.
     *
     *  @param index The item index that was selected.
     *
     *  @param selected <code>true</code> if the item is selected, 
     *  and <code>false</code> if it is deselected.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function itemSelected(index:int, selected:Boolean):void


    /**
     *  Called when an item is in its caret state or not. 
     *  Subclasses must override this method to display the caret. 
     *
     *  @param index The item index that was put into caret state. 
     *
     *  @param inFocus <code>true</code> if the item is in the caret state,  
     *  and <code>false</code> if it is not.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function itemInCaret(index:int, caret:Boolean):void


    /**
     *  Returns <code>true</code> if the item is selected by calling 
     *  <code>isItemIndexSelected()</code>.
     * 
     *  <p>If multiple instances of the item are in the list, 
     *  this method only checks to see whether the item at  
     *  <code>dataProvider.getItemIndex()</code> (usually the first 
     *  instance of that item) is selected.</p>
     * 
     *  @param item The item whose selection status is being checked
     *
     *  @return <code>true</code> if the item is selected, 
     *  and <code>false</code> otherwise.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function isItemSelected(item:Object):Boolean


    /**
     *  Returns <code>true</code> if the item at the index is selected.
     * 
     *  @param index The index of the item whose selection status is being checked
     *
     *  @return <code>true</code> if the item at that index is selected, 
     *  and <code>false</code> otherwise.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function isItemIndexSelected(index:int):Boolean


    /**
     *  Returns true if the item at the index is the caret item, which is
     *  essentially the item in focus. 
     * 
     *  @param index The index of the item whose caret status is being checked
     *
     *  @return true if the item at that index is the caret item, false otherwise.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function isItemInCaret(index:int):Boolean


    //--------------------------------------------------------------------------
    //
    //  Private Methods
    //
    //--------------------------------------------------------------------------


    /**
     *  Adjusts the selected index to account for items being added to or 
     *  removed from this component. This method adjusts the selected index
     *  value and dispatches a <code>selectionChanged</code> event. 
     *  It does not dispatch a <code>selectionChanging</code> event 
     *  or allow the cancellation of the selection. 
     *  It also does not call the <code>itemSelected()</code> method, 
     *  since the same item is selected; 
     *  the only thing that has changed is the index of the item.
     * 
     *  <p>A <code>selectionChanged</code> event is dispatched in the next call to 
     *  the <code>commitProperties()</code> method.</p>
     *
     *  <p>The <code>selectionChanging</code> event is not sent when
     *  the <code>selectedIndex</code> is adjusted.</p>
     *
     *  @param newIndex The new index.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function adjustSelectedIndex(newIndex:int):void


    //--------------------------------------------------------------------------
    //
    //  Event Handlers
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     *  Called when contents within the dataProvider changes.  
     *
     *  @param event The collection change event
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function dataProvider_collectionChangeHandler(event:Event):void

}

}

List.as

////////////////////////////////////////////////////////////////////////////////
//
//  ADOBE SYSTEMS INCORPORATED
//  Copyright 2008 Adobe Systems Incorporated
//  All Rights Reserved.
//
//  NOTICE: Adobe permits you to use, modify, and distribute this file
//  in accordance with the terms of the license agreement accompanying it.
//
////////////////////////////////////////////////////////////////////////////////

package spark.components
{
import flash.events.KeyboardEvent;
import flash.events.MouseEvent;
import flash.events.FocusEvent;
import flash.events.Event;
import flash.geom.Point;
import flash.ui.Keyboard;

import mx.core.IVisualElement;
import mx.core.mx_internal; 
import mx.events.IndexChangedEvent;
import mx.managers.IFocusManagerComponent;

import spark.components.supportClasses.ListBase;
import spark.events.RendererExistenceEvent;
import spark.layouts.HorizontalLayout;
import spark.layouts.VerticalLayout;
import spark.core.NavigationUnit;

use namespace mx_internal;  //ListBase and List share selection properties that are mx_internal

/**
 *  @copy spark.components.supportClasses.GroupBase#style:alternatingItemColors
 * 
 *  @default undefined
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Style%28name%3D%26quot%3BalternatingItemColors%26quot%3B%2C%20type%3D%26quot%3BArray%26quot%3B%2C%20arrayType%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="alternatingItemColors", type="Array", arrayType="uint", format="Color", inherit="yes", theme="spark")</a>

/**
 *  @copy spark.components.supportClasses.GroupBase#style:contentBackgroundColor
 *   
 *  @default 0xFFFFFF
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Style%28name%3D%26quot%3BcontentBackgroundColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="contentBackgroundColor", type="uint", format="Color", inherit="yes", theme="spark")</a>

/**
 *  @copy spark.components.supportClasses.GroupBase#style:rollOverColor
 *   
 *  @default 0xCEDBEF
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Style%28name%3D%26quot%3BrollOverColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="rollOverColor", type="uint", format="Color", inherit="yes", theme="spark")</a>

/**
 *  @copy spark.components.supportClasses.GroupBase#style:selectionColor
 *
 *  @default 0xA8C6EE
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Style%28name%3D%26quot%3BselectionColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="selectionColor", type="uint", format="Color", inherit="yes", theme="spark")</a>

/**
 *  @copy spark.components.supportClasses.GroupBase#style:symbolColor
 *   
 *  @default 0x000000
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */ 
<a href="Style%28name%3D%26quot%3BsymbolColor%26quot%3B%2C%20type%3D%26quot%3Buint%26quot%3B%2C%20format%3D%26quot%3BColor%26quot%3B%2C%20inherit%3D%26quot%3Byes%26quot%3B%2C%20theme%3D%26quot%3Bspark%26quot%3B%29">Style(name="symbolColor", type="uint", format="Color", inherit="yes", theme="spark")</a>

//--------------------------------------
//  Other metadata
//--------------------------------------

<a href="IconFile%28%26quot%3BList.png%26quot%3B%29">IconFile("List.png")</a>
<a href="DefaultTriggerEvent%28%26quot%3BselectionChanged%26quot%3B%29">DefaultTriggerEvent("selectionChanged")</a>

/**
 *  The List control displays a vertical list of items.
 *  Its functionality is very similar to that of the SELECT
 *  form element in HTML.
 *  If there are more items than can be displayed at once, it
 *  can display a vertical scroll bar so the user can access
 *  all items in the list.
 *  An optional horizontal scroll bar lets the user 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, depending
 *  on the value of the <code>allowMultipleSelection</code> property.
 *
 *  @mxml <p>The <code>&lt;List&gt;</code> tag inherits all of the tag 
 *  attributes of its superclass and adds the following tag attributes:</p>
 *
 *  <pre>
 *  &lt;List
 *    <strong>Properties</strong>
 *    allowMultipleSelection="false"
 *    selectedIndices="null"
 *    selectedItems="null"
 *    useVirtualLayout="true"
 * 
 *    <strong>Styles</strong>
 *    alternatingItemColors="undefined"
 *    contentBackgroundColor="0xFFFFFF"
 *    rollOverColor="0xCEDBEF"
 *    selectionColor="0xA8C6EE"
 *    symbolColor="0x000000"
 *  /&gt;
 *  </pre>
 *
 *  @see spark.skins.default.ListSkin
 *
 *  @includeExample examples/ListExample.mxml
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
public class List extends ListBase implements IFocusManagerComponent
{
    include "../core/Version.as";

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  Constructor.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function List()
    {
        super();
        useVirtualLayout = true;
    }

    //----------------------------------
    //  scroller
    //----------------------------------

    <a href="SkinPart%28required%3D%26quot%3Bfalse%26quot%3B%29">SkinPart(required="false")</a>

    /**
     *  The optional Scroller used to scroll the List.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public var scroller:Scroller;

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    //----------------------------------
    //  allowMultipleSelection
    //----------------------------------

    private var _allowMultipleSelection:Boolean = false;

    /**
     *  If <code>true</code> multiple selections is enabled. 
     *  When switched at run time, the current selection
     *  is cleared. 
     *
     *  @default false
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get allowMultipleSelection():Boolean
    public function set allowMultipleSelection(value:Boolean):void

    <a href="Bindable%28%26quot%3BselectionChanged%26quot%3B%29">Bindable("selectionChanged")</a>
    /**
     *  An Array of inidices of the currently selected item or items. 
     *  If multiple selection is disabled by setting <code>allowMultipleSelection</code>
     *  to <code>false</code>, and this property is set, the data item 
     *  corresponding to the first index in the Array is selected.  
     *  
     *  @default null
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get selectedIndices():Array
    public function set selectedIndices(value:Array):void

    <a href="Bindable%28%26quot%3BselectionChanged%26quot%3B%29">Bindable("selectionChanged")</a>
    /**
     *  An Array of the currently selected data items. 
     *  If multiple selection is disabled by setting <code>allowMultipleSelection</code>
     *  to <code>false</code>, and this property is set, the data item 
     *  corresponding to the first item in the Array is selected.  
     * 
     *  @default null
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get selectedItems():Array
    public function set selectedItems(value:Array):void

    /**
     *  Overrides the inherited default property , it is true for this class.
     * 
     *  Sets the value of the <code>useVirtualLayout</code> property
     *  of the layout associated with this control.  
     *  If the layout is subsequently replaced and the value of this 
     *  property is <code>true</code>, then the new layout's 
     *  <code>useVirtualLayout</code> property is set to <code>true</code>.
     *
     *  @default true
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    override public function set useVirtualLayout(value:Boolean):void

    /**
     *  If the data item at the specified index is not completely 
     *  visible, scroll until it is completely visible.
     * 
     *  @param index The index of the data item.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function ensureItemIsVisible(index:int):void
    {
    }

    /**
     *  Adjusts the selected indices to account for items being added to or 
     *  removed from this component. 
     *   
     *  @param index The new index.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function adjustSelectedIndices(index:int, add:Boolean):void
    {
    }

    /**
     *  Tries to find the next item in the data provider that
     *  starts with the character in the <code>eventCode</code> parameter.
     *  You can override this to do fancier typeahead lookups. The search
     *  starts at the <code>selectedIndex</code> location; if it reaches
     *  the end of the data provider it starts over from the beginning.
     *
     *  @param eventCode The key that was pressed on the keyboard.
     *  @return <code>true</code> if a match was found.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    protected function findKey(eventCode:int):Boolean
    {
    }

    /**
     *  Finds an item in the list based on a String,
     *  and moves the selection to it. The search
     *  starts at the <code>selectedIndex</code> location; if it reaches
     *  the end of the data provider it starts over from the beginning.
     *
     *  @param str The String to match.
     * 
     *  @return <code>true</code> if a match is found.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function findString(str:String):Boolean
    {
    }

}

}

Open Issues

B Features

Working with paged data Data effects

Additional Implementation Details

Enter implementation/design details for the feature here. This section may be updated after the spec signs off.

Flex Feature Dependencies

Dependencies on other Flex features.

Backwards Compatibility

None - new component.

Accessibility

N/A.

Performance

Describe any performance considerations or requirements.

Documentation

Describe any documentation issues or any tips for the doc team.

QA

If there are testing tips for QA, note them here, include a link to the test plan document.

Related

Wiki: Flex 4
Wiki: Spark DataGroup

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.