Available since version 0.9.4.
| Class | Extends | Implements |
|---|---|---|
| org.apache.royale.jewel.List{:target=‘_blank’} | org.apache.royale.jewel.DataContainer{:target=‘_blank’} | IVariableRowHeight{:target=‘_blank’} |
Note: This component is currently only available for JavaScript.
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{:target=‘_blank’}. 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.
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.
Check the Reference of org.apache.royale.jewel.List{:target=‘_blank’} for a more detailed list of properties and methods.
| 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{:target=‘_blank’} |
| 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{:target=‘_blank’} |
| strandChildren | IParent{:target=‘_blank’} | An object to access the immediate children of the strand. |
| 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. |
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
selectionChangedevent 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);
| Bead Type | Implementation | Description |
|---|---|---|
| ArrayListSelectionModel{:target=‘_blank’} | IBeadModel{:target=‘_blank’} | This is the default model bead. |
| ListSingleSelectionMouseController{:target=‘_blank’} | IBeadController{:target=‘_blank’} | This is the default controller for input and output. |
| ListView{:target=‘_blank’} | IBeadView{:target=‘_blank’} | This is the default view bead. |
| VerticalLayout{:target=‘_blank’} | IBeadLayout{:target=‘_blank’} | This is the default layout bead. |
| SelectionDataItemRendererFactoryForCollectionView{:target=‘_blank’} | IDataProviderItemRendererMapper{:target=‘_blank’} | Map data to itemrenders. |
| SelectableItemRendererClassFactory{:target=‘_blank’} | IItemRendererClassFactory{:target=‘_blank’} | The factory of itemrenders. |
| ListItemRenderer{:target=‘_blank’} | IItemRenderer{:target=‘_blank’} | The itemrenders class to instantiate. |
| ListItemRendererInitializer{:target=‘_blank’} | IItemRendererInitializer{:target=‘_blank’} | Configuration of itemrenders to instantiate. |
| ScrollingViewport{:target=‘_blank’} | IViewport{:target=‘_blank’} | Define the area that display content. |
| Bead Type | Implementation | Description |
|---|---|---|
| HorizontalListScroll{:target=‘_blank’} | org.apache.royale.core.IBead{:target=‘_blank’} | Provide horizontal scroll to the list. |
| ListAlternateRowColor{:target=‘_blank’} | org.apache.royale.core.IBead{:target=‘_blank’} | Provide alternate background color of every row with two colors. |
| ListPresentationModel{:target=‘_blank’} | EventDispatcher{:target=‘_blank’}(IListPresentationModel{:target=‘_blank’}) | Provide values used to present visuals. |
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.
Other useful Jewel containers components are: