< Jewel Components list

Jewel List

Available since version 0.9.4.

^{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

Methods

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

Optional Beads

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

• Adding an item to a Jewel List
• Using an Item Renderer with a List
• Using Jewel TileHorizontalLayout

Related controls

Other useful Jewel containers components are:

• DataGrid
• DataContainer
• DropDownList
• Table