The List control
displays a vertical list of items. Its functionality is very similar
to that of the SELECT form element in HTML. It
often contains a vertical scroll bar that lets users access the
items in the list. An optional horizontal scroll bar lets users
view items when the full width of the list items is unlikely to
fit. The user can select one or more items from the list.
Flex also includes the Spark List control. When possible, Adobe
recommends that you use the Spark List control. For more information,
see Spark List control.
Note: The HorizontalList, TileList, DataGrid, Menu, and Tree controls
are derived from the MX List control or its immediate parent, the
MX ListBase class.
As a result, much of the information for the List control applies
to these controls.
If you specify horizontalScrollPolicy="on",
the default width of a List control does not change; it is still
large enough to display the widest visible label. If you set horizontalScrollPolicy="on",
and specify a List control pixel width, you can use the measureWidthOfItems() method
to ensure that the scroll bar rightmost position corresponds to
the right edge of the content, as the following example shows. Notice
that the additional 5 pixels ensures that the rightmost character
of the text displays properly.
The preceding line ensures that the rightmost position of the
scroll bar puts the end of the longest measured list item near the
right edge of the List control. Using this technique, however, can
reduce application efficiency, so you might consider using explicit
sizes instead.
Lists, and all subclasses of the ListBase class,
determine their sizes when a style changes or the data provider
changes.
If you set a width property that is less than
the width of the longest label and specify the horizontalScrollPolicy="off",
labels that exceed the control width are clipped.
Creating a List control
You
use the <mx:List> tag to define a List 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.
You specify the data for the List control by using the dataProvider property of
the control. However, because dataProvider is the
List control’s default property, you do not have to specify a dataProvider child
tag of the <mx:List> tag. In the simplest
case for creating a static List control, you need only put <fx:String> tags
in the control body, because Flex also automatically interprets
the multiple tags as an Array of Strings, as the following example shows:
The executing SWF file for the previous example is shown below:
Because the data in this example is inline static data, it is
not necessary to explicitly wrap it in an ArrayList or ArrayCollection
object. However, when working with data that could change, it is
always best to specify a list or collection explicitly; for more
information, see Data providers and collections.
The index
of items in the List control is zero-based, which means that values
are 0, 1, 2, ... , n - 1, where n is the total number
of items. The value of the item is its label text.
You typically use events to handle user interaction with a List
control. The following example code adds a handler for a change event
to the List control. Flex broadcasts a mx.ListEvent.CHANGE event
when the value of the control changes due to user interaction.
The executing SWF file for the previous example is shown below:
In this example,
you use two properties of the List control, selectedItem and selectedIndex,
in the event handler. Every change event updates
the TextArea control with the label of the selected item and the
item’s index in the control.
The target property of the object passed to
the event handler contains a reference to the List control. You
can reference any control property by using the event’s currentTarget property.
The currentTarget.selectedItem field contains a
copy of the selected item. If you populate the List control with
an Array of Strings, the currentTarget.selectedItem field
contains a String. If you populate it with an Array of Objects,
the currentTarget.selectedItem field contains the
Object that corresponds to the selected item, so, in this case, currentTarget.selectedItem.label refers
to the selected item’s label field.
Using a label function
You can pass a label function to the List control to provide
logic that determines the text that appears in the control. The
label function must have the following signature:
labelFunction(item:Object):String
The item parameter passed in by the Label
control contains the list item object. The function must return
the string to display in the List control.
Note: Most subclasses of ListBase also
take a labelFunction property with the signature
described above. For the DataGrid and DataGridColumn controls,
the method signature is labelFunction(item:Object, dataField:DataGridColumn):String,
where item contains the DataGrid item object, and dataField specifies
the DataGrid column.
The following example uses a function
to combine the values of the label and data fields
for each item for display in the List control:
The executing SWF file for the previous example is shown below:
Note: This example uses anArrayList object
as the data provider. You should always use a list or collection
as the data provider when the data can change at run time. For more
information, see Data providers and collections.
Displaying DataTips
DataTips are similar
to ToolTips, but display text when the mouse pointer hovers over
a row in a List control. Text in a List control that is longer than
the control width is clipped on the right side (or requires scrolling,
if the control has scroll bars). DataTips can solve that problem
by displaying all of the text, including the clipped text, when
the mouse pointer hovers over a cell. If you enable data tips, they
only appear for fields where the data is clipped. To display DataTips,
set the showDataTips property of a List control
to true.
Note: To use DataTips with a DataGrid control, you
must set the showDataTips property on the individual
DataGridColumns of the DataGrid.
The default behavior of the showDataTips property
is to display the label text. However, you can use the dataTipField and dataTipFunction properties
to determine what is displayed in the DataTip. The dataTipField property
behaves like the labelField property; it specifies
the name of the field in the data provider to use as the DataTip
for cells in the column. The dataTipFunction property
behaves like the labelFunction property; it specifies
the DataTip string to display for list items.
The
following example sets the showDataTips property
for a List control:
You
use ScrollTips to give users context about where they are in a list
as they scroll through the list. The tips appear only when you scroll;
they don’t appear if you only hover the mouse over the scroll bar.
ScrollTips are useful when live scrolling is disabled (the liveScrolling property
is false) so scrolling does not occur until you release the scroll
thumb. The default value of the showScrollTips property
is false.
The default behavior of the showScrollTips property
is to display the index number of the top visible item. You can
use the scrollTipFunction property to determine
what is displayed in the ScrollTip. The scrollTipFunction property
behaves like the labelFunction property; it specifies
the ScrollTip string to display for list items. You should avoid
going to the server to fill in a ScrollTip.
The
following example sets the showScrollTips and scrollTipFunction properties
of a HorizontalList control, which shares many of the same properties
and methods as the standard List control; for more information about
the HorizontalList control, see MX HorizontalList control. The scrollTipFunction property
specifies a function that gets the value of the description property
of the current list item.
This code produces the following HorizontalList control:
Vertically aligning text in List control rows
You can use the verticalAlign style to
vertically align text at the top, middle, or bottom of a List row.
The default value is top. You can also specify
a value of middle or bottom.
The following
example sets the verticalAlign property for a List
control to bottom:
Setting variable row height and wrapping List text
You can use the variableRowHeight property
to make the height of List control rows variable based on their
content. The default value is false. If you set
the variableRowHeight property to true,
the rowHeight property is ignored and the rowCount property
is read-only.
The following
example sets the variableRowHeight property for
a List control to true:
You can use the wordWrap property in combination
with the variableRowHeight property to wrap text
to multiple lines when it exceeds the width of a List row.
The following
example sets the wordWrap and variableRowHeight properties
to true:
You
can use the alternatingItemColors style property
to specify an Array that defines the color of each row in the List
control. The Array must contain two or more colors. After using
all the entries in the Array, the List control repeats the color
scheme.
The following example defines an Array with two entries, #66FFFF
for light blue and #33CCCC for a blue-gray. Therefore, the rows
of the List control alternate between these two colors. If you specify
a three-color array, the rows alternate among the three colors,
and so on.
An item renderer is the object that displays a List control’s
data items. The simplest way to use a custom item renderer is to
specify an MXML component as the value of the itemRenderer property.
When you use an MXML component as a item renderer, it can contain
multiple levels of containers and controls. You can also use an
ActionScript class as a custom item renderer. For detailed information
on custom item renderers, see MX item renderers and item editors
The following
example sets the itemRenderer property to an MXML component
named FancyCellRenderer. It also sets the variableRowHeight property
to true because the MXML component exceeds the
default row height:
The executing SWF file for the previous example is shown below:
In this
example, you use the iconField property to specify
the field of each item containing the icon. You use the Embed metadata
to import the icons, and then reference them in the List control
definition.
You can also use the iconFunction property to
specify a function that determines the icon, similar to the way
that you can use the labelFunction property to
specify a function that determines the label text. The icon function must
have the following signature:
iconFunction(item:Object):Class
The item parameter passed in by the List
control contains the list item object. The function must return
the icon class to display in the List control.
The following example shows a List control that uses the iconFunction property
to determine the icon to display for each item in the list:
<?xml version="1.0"?>
<!-- dpcontrols/ListIconFunction.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx">
<fx:Script>
<![CDATA[
// Embed icons.
[Embed(source="assets/radioIcon.jpg")]
public var pavementSymbol:Class;
[Embed(source="assets/topIcon.jpg")]
public var normalSymbol:Class;
// Define data provider.
private var myDP: Array;
private function initList():void {
myDP = [
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavarotti', Album:'Twilight', Price:11.99},
{Artist:'Other', Album:'Other', Price:5.99}];
list1.dataProvider = myDP;
}
// Determine icon based on artist. Pavement gets a special icon.
private function myiconfunction(item:Object):Class {
var type:String = item.Artist;
if (type == "Pavement") {
return pavementSymbol;
}
return normalSymbol;
}
]]>
</fx:Script>
<mx:VBox >
<mx:List id="list1"
initialize="initList();"
labelField="Artist"
iconFunction="myiconfunction" />
</mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:
List 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.
(You must set the allowMultipleSelection property
to true to allow multiple selection.)
All mouse or keyboard selections broadcast a change event.
For mouse interactions, the List control broadcasts this event when
the mouse button is released.
If you set the allowDragSelection property to true,
the control scrolls up or down when the user presses the mouse button
over the one or more rows, holds the mouse button down, drags the
mouse outside the control, and then moves the mouse up and down.
A List control shows the number of records that fit in the display.
Paging down through the data displayed by a 10-line List control
shows records 0-10, 9-18, 18-27, and so on, with one line overlapping
from one page to the next.
The
List control has the following keyboard navigation features:
Key
Action
Up Arrow
Moves selection up one item.
Down Arrow
Moves selection down one item.
Page Up
Moves selection up one page.
Page Down
Moves selection down one page.
Home
Moves selection to the top of the list.
End
Moves selection to the bottom of the list.
Alphanumeric keys
Jumps to the next item with a label that
begins with the character typed.
Control
Toggle key. Allows for multiple (noncontiguous)
selection and deselection. Works with key presses, click selection,
and drag selection.
Shift
Contiguous selection key. Allows for contiguous
selections. Works with key presses, click selection, and drag selection.
