////////////////////////////////////////////////////////////////////////////////
//
// 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 ISortField
interface defines the interface for classes that
* are used with ISort
classes, to provide the sorting information
* required to sort the specific fields or property in a collection view.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
public interface ISortField
{
//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------
/**
* This helper property is used internally by the findItem()
* and sort()
methods. Other uses of this property are not
* supported.
* Returns -1 if this ISortField shouldn't be used by the Sort
* class to sort the field (there is no compareFunction or no name). Otherwise, returns a bitmask of sort options..
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function get arraySortOnOptions():int;
/**
* The function that compares two items during a sort of items for the
* associated collection. If you specify a compareFunction
* property in an ISort object, Flex ignores any
* compareFunction
properties of the ISort's ISortField
* objects.
*
The compare function must have the following signature:
* *function myCompare(a:Object, b:Object):int
This function returns the following values:
* *a
should appear before b
in
* the sorted sequencea
equals b
a
should appear after b
in the
* sorted sequenceThe default value is false
(ascending).
number/int/uint
) values, or string representations of numeric values,
* the comparator use a numeric comparison.
*
* This property is used by SortField
class in case custom compare
* function is not provided.
*
* If this property is true
, the built-in numeric compare
* function is used. Each of data items is cast to a
* Number()
function before the comparison.
*
* If this property is false
, the built-in string compare
* function is used. Each of data items is cast to a
* String()
function before the comparison.
*
* If this property is null
, the first data item
* is introspected to see if it is a number or string and the sort
* proceeds based on that introspection.
*
ISortField
uses a custom comparator function.
*
* @see @compareFunction
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function get usingCustomCompareFunction():Boolean;
//--------------------------------------------------------------------------
//
// Methods
//
//--------------------------------------------------------------------------
/**
* A helper function called by the Sort
class to set the
* default comparison function to perform a comparison based on
* one of three things: whether or not a custom compare function has
* been set, the data type for the specified field or the the value of the
* numeric property. If the the numeric
property is true,
* then a numeric comparison will be performed when sorting.
*
* @param obj The object that contains the data. If the field name has
* been set with the name property, then the name will be used to access
* the data value from this object. Otherwise the object itself will
* be used as the data value.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 4.5
*/
function initializeDefaultCompareFunction(obj:Object):void;
/**
* Reverse the criteria for this sort field.
* If the field was sorted in descending order, for example, sort it
* in ascending order.
*
* NOTE: An ICollectionView
does not automatically
* update when the ISortFields
are modified; call its
* refresh()
method to update the view.