A description of the List component

The FlexJS List component is fairly complex component compared to such components as Label, TextButton, and even Panel. Originally, the List component started out simply, especially on the JavaScript side, but it is now a more robust component.

The original List component (now SimpleList) consisted of a model and item renderers but on the JavaScript side, it was merely a wrapper for the HTML <select> element. Since the JavaScript FlexJS components should reflect their ActionScript counterparts as much as possible, the JavaScript List had to also make use of item renderers.This is that story.

The following diagram shows how the ActionScript List component is composed.

The List contains:

• A selection model which encapsulates a data provider as well knowledge about which item is selected (the item and the index).
• A view bean that displays the container housing the list control.
• A factory bean that can produce instances of item renderers as needed.
• An item renderer to display each element of the list; created by the factory bean.
• A mouse controller for the list as a whole that handles the selection for the list.
• A mouse controller for item renderer to handle the hover and selected states.

These parts are specified by the List's style definition in the defaults.css file:

List
{
    IBeadModel: ClassReference("org.apache.flex.html.staticControls.beads.models.ArraySelectionModel");
    IBeadView:  ClassReference("org.apache.flex.html.staticControls.beads.ListView");
    IBeadController: ClassReference("org.apache.flex.html.staticControls.beads.controllers.ListSingleSelectionMouseController");
    IBeadLayout: ClassReference("org.apache.flex.html.staticControls.beads.layouts.NonVirtualVerticalScrollingLayout");
    IDataProviderItemRendererMapper: ClassReference("org.apache.flex.html.staticControls.beads.TextItemRendererFactoryForArrayData");
    IItemRendererClassFactory: ClassReference("org.apache.flex.core.ItemRendererClassFactory");
    IItemRenderer: ClassReference("org.apache.flex.html.staticControls.supportClasses.StringItemRenderer");
}

The diagram above does not show the item renderer class factory nor does it specify the item renderer. For the List, the IDataProviderItemRendererMapper marries the information. That is, when the List component is being created, an instance of the IDataProviderItemRendererMapper is created and it looks at the List's style definition for the IItemRendererClassFactory which it instantiates. Then for each item in the data provider, the IDataProviderItemRendererMapper has the IItemRendererClassFactory create a new instance of the IItemRenderer.

Item Renderers

Once the List component and all of the item renderers have been created, the interactive part comes into play. Each item renderer is also a component (strand and beads) and follows the same pattern as other FlexJS components. For the List, the IItemRenderer is specified in defaults.css as the StringItemRenderer class which has its own style definition, show here:

StringItemRenderer
{
    IBeadController: ClassReference("org.apache.flex.html.staticControls.beads.controllers.ItemRendererMouseController");
    height: 16;
}

The StringItemRenderer's IBeadController is the generic ItemRendererMouseController which looks for mouse events: over, out, down, and up. These events set the item renderer's hover and selected properties.

When the item renderer's controller selects an item renderer, it also dispatches an event that is picked up the List's controller, ListSingleSelectionMouseController. This controller updates the List's model and dispatch's the List's change event.

JavaScript

The JavaScript implementation of List closely follows the ActionScript implementation, although they are not exact. The main difference is that events in ActionScript are chained through the component's display list parts (the item renderers and the view bead which have a parent/child relationship on the display list). That is, the bead classes that make up the view and item renderers extend Flash display list objects.

In the JavaScript, the bead classes are normal classes and events do not propagate from inner to outer class (the UI in JavaScript are HTML elements that the JavaScript classes are wrapping). This event flow makes it a little challenging to have an event dispatched on an item renderer be detected by the ListSingleSelectionMouseController which is listening for events coming through the view bead. In JavaScript, the event dispatched on the item renderer does not have an event chain parent so that detection is not possible.

// from ItemRendererMouseController's handleMouseUp function
this.strand_.get_itemRendererParent().dispatchEvent(newEvent);

Instead, the JavaScript implementation of the List component provides a property, itemRendererParent, to help with the event flow. By dispatching on this property, the same event can reach the ListSingleSelectionMouseController so that the model can be updated in the same way it does in the ActionScript version.