< Jewel Components list

Jewel List

Available since version 0.9.4.

Class Extends Implements
org.apache.royale.jewel.List org.apache.royale.jewel.DataContainer IVariableRowHeight

Note: This component is currently only available for JavaScript.

Overview

The List class is a DataContainer component that provides item selection and keyboard navigation through items (check DataContainer for more info about core List functionality). If you just need to show a list of items you can use a DataContainer; if you need interaction with items, use List.

List default item renderer is ListItemRenderer. When there’s a need of any advanced item, we recommend using layout to extend ListItemRenderer to create a custom renderer. List can also use factories and data mappers for renderers that suport selection.

This component supports scrolling by default and gives you control over rollover and row height for each cell in every column. You can also programatically scroll to any item by index.

Example of use

In MXML declare a List like this:

<j:List width="100%" height="250">
    <js:ArrayList localId="avengers" source="[Iron Man, Hulk, Thor, Captain America, Black Widow, Hawkeye]"/>
</j:List>

We can nest the ArrayList directly into the DataContainer tag because “dataProvider” is its DefaultProperty.

In ActionScript we can do the same in the following way:

var list:List = new List();
list.dataProvider = new ArrayList(["Iron Man", "Hulk", "Thor", "Captain America", "Black Widow", "Hawkeye"]);
// add the List to the parent
parent.addElement(list);

where parent is the container where the control will be added.

Relevant Properties and Methods

Check the Reference of org.apache.royale.jewel.List for a more detailed list of properties and methods.

Properties

PROPERTY Type Description
currentState String The name of the current state.
itemRenderer String The class or factory used to display each item.
labelField String The name of field within the data used for display.
dataProvider Object The data being display by the List. Is the DefaultProperty. In Jewel an ArrayList
numElements int The number of element children that can be laid out.
rollOverIndex int The index of the item currently below the pointer.
selectedIndex int The index of the currently selected item.
selectedItem Object The item currently selected.
states Array The array of view states. These should be instances of org.apache.royale.states.State
strandChildren IParent An object to access the immediate children of the strand.

Methods

Method Parameters Description
addElement c(IChild), dispatchEvent(Boolean=true) Add a component to the parent.
addElementAt c(IChild), index(int), dispatchEvent(Boolean=true) Add a component to the parent at the specified index.
getElementIndex c(IChild) Gets the index of this subcomponent.
getElementAt index(int) Get a component from the parent at specified index.
removeElement c(IChild), dispatchEvent(Boolean=true) Remove a component from the parent.
scrollToIndex index(int) Ensures that the data provider item at the given index is visible.

Relevant Events

The most important event is change, which is dispatched whenever the list’s selected item changes.

You can attach callback listeners to the change event in MXML as follows:

<j:List change="changeHandler(event)"/>

the change event will use the changeHandler callback function you provide in ActionScript:

<fx:Script>
    <![CDATA[      
        private function changeHandler(event:Event):void {
            trace("[Selection] index", event.target.selectedIndex, "item", event.target.selectedItem);
        }
    ]]>
</fx:Script>

When the user selects any item a change event is dispatched and a message appears in the console log showing the “index” and the “item” that correspond to the selection.

When a programmatic change event is needed you can use the selectionChanged event instead to listen for selection changes.

In ActionScript we can add an event handler this way:

var list:List = new List();
list.addEventListener(Event.CHANGE, changeHandler);
parent.addElement(list);

Relevant Beads

Bead Type Implementation Description
ArrayListSelectionModel IBeadModel This is the default model bead.
ListSingleSelectionMouseController IBeadController This is the default controller for input and output.
ListView IBeadView This is the default view bead.
VerticalLayout IBeadLayout This is the default layout bead.
SelectionDataItemRendererFactoryForCollectionView IDataProviderItemRendererMapper Map data to itemrenders.
SelectableItemRendererClassFactory IItemRendererClassFactory The factory of itemrenders.
ListItemRenderer IItemRenderer The itemrenders class to instantiate.
ListItemRendererInitializer IItemRendererInitializer Configuration of itemrenders to instantiate.
ScrollingViewport IViewport Define the area that display content.

Optional Beads

Bead Type Implementation Description
HorizontalListScroll org.apache.royale.core.IBead Provide horizontal scroll to the list.
ListAlternateRowColor org.apache.royale.core.IBead Provide alternate background color of every row with two colors.
ListPresentationModel EventDispatcher(IListPresentationModel) Provide values used to present visuals.

Common Beads

Jewel List can use any of the layout beads available in Jewel library. Also you can check Related controls section to see some advanced or preconfigured data containers.

More examples

Other useful Jewel containers components are: