////////////////////////////////////////////////////////////////////////////////
//
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////
package mx.collections
{
/**
* The ISort
interface defines the interface for classes that
* provide the sorting information required to sort the
* data of a collection view.
*
* @see mx.collections.ICollectionView
* @see mx.collections.ISortField
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
public interface ISort
{
//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------
/**
* 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: *
Object a
should appear before the
* Object b
in the sorted sequenceObject a
equals the
* Object b
Object a
should appear after the
* Object b
in the sorted sequenceTo 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.
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.
*
* @default null
*
* @see ISortField
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function get fields():Array;
function set fields(value:Array):void;
/**
* 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.
*
* @default false
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function get unique():Boolean;
function set unique(value:Boolean):void;
//--------------------------------------------------------------------------
//
// Methods
//
//--------------------------------------------------------------------------
/**
* 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.
*
* @param items the Array within which to search.
* @param values 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.
* @param mode 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. * | *
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.
* @param compareFunction 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.
* @return 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 SortError 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.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function findItem(
items:Array,
values:Object,
mode:String,
returnInsertionIndex:Boolean = false,
compareFunction:Function = null):int;
/**
* 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.
*
* @param property The name of the field that to test.
* @return 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
.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function propertyAffectsSort(property:String):Boolean;
/**
* 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.
items
parameter.
*
* Flex ICollectionView
implementations call the
* sort
method automatically and ensure that the sort is
* performed on a copy of the underlying data.