List.sortItemsBy()

Availability

Flash Player 6 (6.0.79.0).

Edition

Flash MX 2004.

Usage

listInstance.sortItemsBy(fieldName, optionsFlag)
listInstance.sortItemsBy(fieldName, order)

Parameters

fieldName A string that specifies the name of the field to use for sorting. This value is usually "label" or "data".

order A string that specifies whether to sort the items in ascending order ("ASC") or descending order ("DESC").

optionsFlag Lets you perform multiple sorts of different types on a single array without having to replicate the entire array or resort it repeatedly.

The following are possible values for optionsFlag:

Array.DESCENDING, which sorts from highest to lowest.
Array.CASEINSENSITIVE, which sorts without regard to case.
Array.NUMERIC, which sorts numerically if the two elements being compared are numbers. If they aren't numbers, use a string comparison (which can be case-insensitive if that flag is specified).
Array.UNIQUESORT, which returns an error code (0) instead of a sorted array if two objects in the array are identical or have identical sort fields.
Array.RETURNINDEXEDARRAY, which returns an integer index array that is the result of the sort. For example, the following array would return the second line of code and the array would remain unchanged:
```
["a", "d", "c", "b"]
[0, 3, 2, 1]
```

You can combine these options into one value. For example, the following code combines options 3 and 1:

my_array.sort (Array.NUMERIC | Array.DESCENDING)

Returns

Nothing.

Description

Method; sorts the items in the list in the specified order, using the specified field name. If the fieldName items are a combination of text strings and integers, the integer items are listed first. The fieldName parameter is usually "label" or "data", but you can specify any primitive data value.

This is the fastest way to sort data in a component. It also maintains the component's selection state. The sortItemsBy() method is fast because it doesn't run any ActionScript while sorting. The sortItems() method needs to run an ActionScript compare function, and is therefore slower.

Example

The following code sorts the items in the list in ascending order using the labels of the list items:

var my_list:mx.controls.List;

my_list.setSize(200, 100);
my_list.addItem({data:"flash", label:"Flash"});
my_list.addItem({data:"dreamweaver", label:"Dreamweaver"});
my_list.addItem({data:"coldfusion", label:"ColdFusion"});

my_list.sortItemsBy("label", "ASC");