Package | mx.collections |
Interface | public interface ISort |
Implementors | Sort, Sort |
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
ISort
interface defines the interface for classes that
provide the sorting information required to sort the
data of a collection view.
Related API Elements
Property | Defined By | ||
---|---|---|---|
compareFunction : Function
The method used to compare items when sorting. | ISort | ||
fields : Array
An Array of ISortField objects that specifies the fields to compare. | ISort | ||
unique : Boolean
Indicates if the sort should be unique. | ISort |
Method | Defined By | ||
---|---|---|---|
findItem(items:Array, values:Object, mode:String, returnInsertionIndex:Boolean = false, compareFunction:Function = null):int
Finds the specified object within the specified array (or the insertion
point if asked for), returning the index if found or -1 if not. | ISort | ||
Return whether the specified property is used to control the sort. | ISort | ||
Goes through the fields array and calls
reverse() on each of the ISortField objects in
the array. | ISort | ||
Apply the current sort to the specified array (not a copy). | ISort |
compareFunction | property |
compareFunction:Function
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
The method used to compare items when sorting.
If you specify this property, Flex ignores any
compareFunction
properties that you specify in the
ISortField
objects that you use in this class.
The compare function must have the following signature:
function [name](a:Object, b:Object, fields:Array = null):int
This function must return the following value:
- -1, if the
Object a
should appear before theObject b
in the sorted sequence - 0, if the
Object a
equals theObject b
- 1, if the
Object a
should appear after theObject b
in the sorted sequence
To return to the internal comparision function, set this value to
null
.
The fields
array specifies the object fields
to compare.
Typically the algorithm will compare properties until the field list is
exhausted or a non-zero value can be returned.
For example:
function myCompare(a:Object, b:Object, fields:Array = null):int
{
var result:int = 0;
var i:int = 0;
var propList:Array = fields ? fields : internalPropList;
var len:int = propList.length;
var propName:String;
while (result == 0 && (i < len))
{
propName = propList[i];
result = compareValues(a[propName], b[propName]);
i++;
}
return result;
}
function compareValues(a:Object, b:Object):int
{
if (a == null && b == null)
return 0;
if (a == null)
return 1;
if (b == null)
return -1;
if (a < b)
return -1;
if (a > b)
return 1;
return 0;
}
The default value is an internal compare function that can perform a string, numeric, or date comparison in ascending or descending order. Specify your own function only if you need a need a custom comparison algorithm. This is normally only the case if a calculated field is used in a display.
Alternatively you can specify separate compare functions for each
sort field by using the ISortField
class
compareFunction
property; This way you can use the default
comparison for some fields and a custom comparison for others.
Implementation
public function get compareFunction():Function
public function set compareFunction(value:Function):void
fields | property |
fields:Array
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
An Array
of ISortField
objects that specifies the fields to compare.
The order of the ISortField objects in the array determines
field priority order when sorting.
The default sort comparator checks the sort fields in array
order until it determinines a sort order for the two
fields being compared.
The default value is null.
Implementation
public function get fields():Array
public function set fields(value:Array):void
Related API Elements
unique | property |
unique:Boolean
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
Indicates if the sort should be unique.
Unique sorts fail if any value or combined value specified by the
fields listed in the fields property result in an indeterminate or
non-unique sort order; that is, if two or more items have identical
sort field values. An error is thrown if the sort is not unique.
The sorting logic uses this unique
property value only if sort
field(s) are specified explicitly. If no sort fields are specified
explicitly, no error is thrown even when there are identical value
elements.
The default value is false.
Implementation
public function get unique():Boolean
public function set unique(value:Boolean):void
findItem | () | method |
public function findItem(items:Array, values:Object, mode:String, returnInsertionIndex:Boolean = false, compareFunction:Function = null):int
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
Finds the specified object within the specified array (or the insertion
point if asked for), returning the index if found or -1 if not.
The ListCollectionView
class findxxx()
methods use this method to find the requested item; as a general rule,
it is easier to use these functions, and not findItem()
to find data in ListCollectionView
-based objects.
You call the findItem()
method directly when writing a
class that supports sorting, such as a new ICollectionView
implementation.
The input items array need to be sorted before calling this function.
Otherwise this function will not be able to find the specified value
properly.
Parameters
items:Array — the Array within which to search.
| |||||||
values:Object — Object containing the properties to look for (or
the object to search for, itself).
The object must consist of field name/value pairs, where
the field names are names of fields specified by the
fields property, in the same order they
are used in that property.
You do not have to specify all of the fields from the
fields property, but you
cannot skip any in the order.
Therefore, if the fields
properity lists three fields, you can specify its first
and second fields in this parameter, but you cannot
specify only the first and third fields.
| |||||||
mode:String — String containing the type of find to perform.
Valid values are:
| |||||||
returnInsertionIndex:Boolean (default = false ) — If the method does not find an item
identified by the values parameter,
and this parameter is true the
findItem()
method returns the insertion point for the values,
that is the point in the sorted order where you
should insert the item.
| |||||||
compareFunction:Function (default = null ) — a comparator function to use to find the item.
If you do not specify this parameter or , or if you
provide a null value,
findItem() function uses the
compare function determined by the ISort
instance's compareFunction property,
passing in the array of fields determined
by the values object and the current
SortFields .
If you provide a non-null value, findItem()
function uses it as the compare function.
The signature of the function passed as
compareFunction must be as follows:
function myCompareFunction(a:Object, b:Object):int .
Note that there is no third argument unlike the
compare function for ISort.compareFunction()
property.
|
int — int The index in the array of the found item.
If the returnInsertionIndex parameter is
false and the item is not found, returns -1.
If the returnInsertionIndex parameter is
true and the item is not found, returns
the index of the point in the sorted array where the
values would be inserted.
|
Throws
Error — If there are any parameter errors,
the find critieria is not compatible with the sort
or the comparator function for the sort can not be determined.
|
propertyAffectsSort | () | method |
public function propertyAffectsSort(property:String):Boolean
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
Return whether the specified property is used to control the sort.
The function cannot determine a definitive answer if the sort uses a
custom comparator; it always returns true
in this case.
Parameters
property:String — The name of the field that to test.
|
Boolean — Whether the property value might affect the sort outcome.
If the sort uses the default compareFunction, returns
true if the
property parameter specifies a sort field.
If the sort or any ISortField uses a custom comparator,
there's no way to know, so return true .
|
reverse | () | method |
public function reverse():void
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
Goes through the fields
array and calls
reverse()
on each of the ISortField
objects in
the array. If the field was descending now it is ascending,
and vice versa.
Note: an ICollectionView
does not automatically
update when the objects in the fields
array are modified;
call its refresh()
method to update the view.
sort | () | method |
public function sort(items:Array):void
Language Version: | ActionScript 3.0 |
Product Version: | Flex 4.5 |
Runtime Versions: | Flash Player 9, AIR 1.1 |
Apply the current sort to the specified array (not a copy).
To prevent the array from being modified, create a copy
use the copy in the items
parameter.
Flex ICollectionView
implementations call the
sort
method automatically and ensure that the sort is
performed on a copy of the underlying data.
Parameters
items:Array — Array of items to sort.
|
Thu Dec 6 2018, 01:12 PM -08:00