HorizontalList control -- Flex 2.01

The HorizontalList control displays a horizontal list of items. The HorizontalList control is particularly useful in combination with a custom item renderer for displaying a list of images and other data. For more information about custom item renderers, see Using Item Renderers and Item Editors.

For complete reference information, see HorizontalList in Adobe Flex 2 Language Reference.

Subtopics

About HorizontaList controls

The contents of a HorizontalList control can look very similar to the contents of an HBox container in which a Repeater object repeats components. However, performance of a HorizontalList control can be better than the combination of an HBox container and a Repeater object because the HorizontalList control only instantiates the objects that fit in its display area. Scrolling in a HorizontalList can be slower than it is when using a Repeater object. For more information about the Repeater object, see Dynamically Repeating Controls and Containers.

The HorizontalList control always displays items from left to right. The control usually contains a horizontal scroll bar, which lets users access all items in the list. An optional vertical scroll bar lets users view items when the full height 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 allowMultipleSelection property.

Property	Default value
Default size	Four columns, with the dimensions determined by the cell dimensions.
Minimum size	0
Maximum size	5000 by 5000

For complete reference information, see HorizontalList in Adobe Flex 2 Language Reference.

Creating a HorizontalList control

You use the <mx:HorizontalList> tag to define a HorizontalList control. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The HorizontalList control shares many properties and methods with the List control; see List control for information on how to use several of these shared properties. The HorizontalList control uses a list-based data provider. For more information, see About data providers.

You specify the data for a HorizontalList control using the dataProvider property of the <mx:HorizontalList> tag, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/HListDataProvider.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="450">
   <mx:Script>
      <![CDATA[
         import mx.collections.*;
         import mx.controls.Image;

         private var catalog:ArrayCollection;
         private static var cat:Array = [
            "assets/usbfan.jpg", "assets/usbwatch.jpg",
            "assets/007camera.jpg", "assets/radiowatch.jpg"
         ];

         // Initialize the HorizontalList control by setting its dataProvider
         // property to an ArrayCollection containing the items parameter.
         private function initCatalog(items:Array):void
         {
            catalog = new ArrayCollection(items);
            myList.dataProvider = catalog;
         }
      ]]>   
   </mx:Script>

   <!-- A four-column HorizontalList.
       The itemRenderer is a Flex Image control.
       When the control is created, pass the cat array to the 
       initialization routine. -->
   <mx:HorizontalList id="myList" columnWidth="100" rowHeight="100" 
      columnCount="4" itemRenderer="mx.controls.Image" 
      creationComplete="initCatalog(cat)"/>
</mx:Application>

In this example, you use the creationComplete event to populate the data provider with an ArrayCollection of image files, and the itemRenderer property to specify the Image control as the item renderer. (Note that you use the full package name of the control in the assignment because the code does not import the mx.controls package.) The HorizontalList control then displays the four images specified by the data provider.

The following examples are based on the Flex Explorer application included in Flex 2.

The HorizontalListDemo.mxml example displays a catalog of product images in a HorizontalList control. The item renderer for the HorizontalList control is an MXML component named Thumbnail.

<?xml version="1.0"?>
<!-- dpcontrols/HorizontalListDemo.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
   backgroundAlpha="0" creationComplete="srv.send()">

   <mx:Script>
      <![CDATA[
            private function xmlLoaded():void {
                catalogAC = srv.lastResult.catalog;
            }         
      ]]>   
   </mx:Script>

   <mx:HTTPService id="srv" url="assets/catalog.xml" useProxy="false" result="xmlLoaded();"/>

   <mx:Model id="catalogAC"/>

   <mx:HorizontalList dataProvider="{catalogAC.product}"
      width="100%" itemRenderer="Thumbnail"/>
</mx:Application>

The following example shows the Thumbnail.mxml MXML component that is used as the item renderer in the product catalog application. In this example, you define the item renderer to contain three controls: an Image control and two Label controls. These controls examine the data object passed to the item renderer to determine the content to display. For more information about custom item renderers, see Using Item Renderers and Item Editors.

<?xml version="1.0"?>
<!-- dpcontrols/Thumbnail.mxml -->
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml"
      width="165" height="120" verticalAlign="middle" verticalGap="0"
      verticalScrollPolicy="off">
   <mx:CurrencyFormatter id="cf"/>
   <mx:Image id="img" height="100" width="50" source="../{data.image}"/>
   <mx:VBox width="100%" paddingTop="0" horizontalGap="4">
      <mx:Label text="{data.name}" fontWeight="bold"/>
      <mx:Label text="{cf.format(data.price)}" fontWeight="bold"/>
   </mx:VBox>
</mx:HBox>

HorizontalList control user interaction

The user clicks individual list items to select them, and holds down the Control and Shift keys while clicking to select multiple items.

All mouse or keyboard selections broadcast a change event. For mouse interactions, the HorizontalList control broadcasts this event when the mouse button is released. When the user drags the mouse over the items and then outside the control, the control scrolls up or down.

A HorizontalList control shows the number of records that fit in the display. Paging through a four list shows records 0-4, 5-8, and so on, with no overlap from one page to the next.