mx.collections.Sort

Package	mx.collections
Class	public class Sort
Inheritance	Sort flash.events.EventDispatcher

Provides the sorting information required to establish a sort on an existing view (ICollectionView interface or class that implements the interface). After you assign a Sort instance to the view's sort property, you must call the view's refresh() method to apply the sort criteria. Typically the sort is defined for collections of complex items, that is collections in which the sort is performed on one or more properties of the objects in the collection. The following example shows this use:


     var col:ICollectionView = new ArrayCollection();
     // In the real world, the collection would have more than one item.
     col.addItem({first:"Anders", last:"Dickerson"});
     // Create the Sort instance.
     var sort:Sort = new Sort();
     // Set the sort field; sort on the last name first, first name second.
     // Both fields are case-insensitive.
     sort.fields = [new SortField("last",true), new SortField("first",true)];
       // Assign the Sort object to the view.
     col.sort = sort;
     // Apply the sort to the collection.
       col.refresh();

There are situations in which the collection contains simple items, like String, Date, Boolean, etc. In this case, apply the sort to the simple type directly. When constructing a sort for simple items, use a single sort field, and specify a null name (first) parameter in the SortField object constructor. For example:


     var col:ICollectionView = new ArrayCollection();
     col.addItem("California");
     col.addItem("Arizona");
     var sort:Sort = new Sort();
     // There is only one sort field, so use a null first parameter.
     sort.fields = [new SortField(null, true)];
     col.sort = sort;
       col.refresh();

The Flex implementations of the ICollectionView interface retrieve all items from a remote location before executing a sort. If you use paging with a sorted list, apply the sort to the remote collection before you retrieve the data.

MXML Syntax expanded

Hide MXML Syntax

The <mx:Sort> tag has the following attributes:

  <mx:Sort
  Properties
  compareFunction="Internal compare function"
  fields="null"
  unique="false | true"
  />

Default MXML Propertyfields

See also

mx.collections.ICollectionView

	Property	Defined by
		compareFunction : Function The method used to compare items when sorting.	Sort
		fields : Array An Array of SortField objects that specifies the fields to compare.	Sort
		unique : Boolean Indicates if the sort should be unique.	Sort

	Method	Defined by
		Sort() Constructor.	Sort
		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.	Sort
		propertyAffectsSort(property:String):Boolean Return whether the specified property is used to control the sort.	Sort
		reverse():void Goes through all SortFields and calls reverse() on them.	Sort
		sort(items:Array):void Apply the current sort to the specified array (not a copy).	Sort

	Constant	Defined by
		ANY_INDEX_MODE : String = "any" [static] When executing a find return the index any matching item.	Sort
		FIRST_INDEX_MODE : String = "first" [static] When executing a find return the index for the first matching item.	Sort
		LAST_INDEX_MODE : String = "last" [static] When executing a find return the index for the last matching item.	Sort

Property detail

compareFunction

property

compareFunction:Function [read-write]

The method used to compare items when sorting. If you specify this property, Flex ignores any compareFunction properties that you specify in the SortField 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

-1, if a should appear before b in the sorted sequence
0, if a equals b
1, if a should appear after b in the sorted sequence

To return to the internal comparision function set this value to null.

The fields array specified 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, with case-sensitive or case-insensitive string comparisons. 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 SortField class compare 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 [read-write]

An Array of SortField objects that specifies the fields to compare. The order of the SortField 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.

This property can be used as the source for data binding.

Implementation
public function get fields():Array
public function set fields(value:Array):void

See also

SortField

unique

property

unique:Boolean [read-write]

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.

The default value is false.

Implementation
public function get unique():Boolean
public function set unique(value:Boolean):void

Constructor detail

Sort

()

constructor

public function Sort()

Constructor.

Creates a new Sort with no fields set and no custom comparator.

Method detail

findItem

()

method

public function 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. 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.

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 `SortFields` property, in the same order they are used in that property. You do not have to specify all of the fields from the `SortFields` property, but you cannot skip any in the order. Therefore, if the `SortFields` 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 ANY_INDEX_MODE Return any position that is valid for the values. FIRST_INDEX_MODE Return the position where the first occurrance of the values is found. LAST_INDEX_MODE Return the position where the last ocurrance of the specified values is found.

	`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, the function uses the function determined by the Sort instance's `compareFunction` property, passing in the array of fields determined by the values object and the current SortFields.

Returns

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.

propertyAffectsSort

()

method

public function propertyAffectsSort(property:String):Boolean

Return whether the specified property is used to control the sort. The function cannot determine a definitive answer if the sort uses a custom comparitor; it always returns true in this case.

Parameters

property:String — The name of the field that to test.

Returns

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 SortField uses a custom comparator, there's no way to know, so return true.

reverse

()

method

public function reverse():void

Goes through all SortFields and calls reverse() on them. If the field was descending now it is ascending, and vice versa.

Note: an ICollectionView does not automatically update when the SortFields are modified; call its refresh() method to update the view.

sort

()

method

public function sort(items:Array):void

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.

Constant detail

ANY_INDEX_MODE

constant

public static const ANY_INDEX_MODE:String = "any"

When executing a find return the index any matching item.

FIRST_INDEX_MODE

constant

public static const FIRST_INDEX_MODE:String = "first"

When executing a find return the index for the first matching item.

LAST_INDEX_MODE

constant

public static const LAST_INDEX_MODE:String = "last"

When executing a find return the index for the last matching item.

XML Flash Slideshow v4 - Class Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class Sort	Properties \| Methods \| Constants