//////////////////////////////////////////////////////////////////////////////// // // 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: *

*

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.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 4.5 */ function get compareFunction():Function; function set compareFunction(value:Function):void; /** * 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. * * @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_MODEReturn any position that * is valid for the values.
FIRST_INDEX_MODEReturn the position * where the first occurrance of the values is found.
LAST_INDEX_MODEReturn the position where the * last ocurrance of the specified values is found. *
* @param returnInsertionIndex 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. * @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.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 4.5 */ function reverse():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.

* * @param items Array of items to sort. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 4.5 */ function sort(items:Array):void; } }