blob: 896e9bc835213aa29ee7f9c97111f3d07e902485 [file] [log] [blame]
{ "type": "interface",
"qname": "mx.collections.ISort",
"description": "The <code>ISort</code> interface defines the interface for classes that provide the sorting information required to sort the data of a collection view.",
"tags": [
{ "tagName": "see",
"values": ["mx.collections.ICollectionView", "mx.collections.ISortField"]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ],
"members": [
{ "type": "accessor",
"access": "read-write",
"return": "Function",
"qname": "compareFunction",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "The method used to compare items when sorting. If you specify this property, Flex ignores any <code>compareFunction</code> properties that you specify in the <code>ISortField</code> objects that you use in this class. <p>The compare function must have the following signature:</p> <pre><code>\\n \\n function [name](a:Object, b:Object, fields:Array = null):int\\n \\n </code></pre> <p>This function must return the following value: <ul> <li>-1, if the <code>Object a</code> should appear before the <code>Object b</code> in the sorted sequence</li> <li>0, if the <code>Object a</code> equals the <code>Object b</code></li> <li>1, if the <code>Object a</code> should appear after the <code>Object b</code> in the sorted sequence</li> </ul></p> <p>To return to the internal comparision function, set this value to <code>null</code>.</p> <p> The <code>fields</code> 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:</p> <pre><code>\\n function myCompare(a:Object, b:Object, fields:Array = null):int\\n {\\n var result:int = 0;\\n var i:int = 0;\\n var propList:Array = fields ? fields : internalPropList;\\n var len:int = propList.length;\\n var propName:String;\\n while (result == 0 &amp;&amp; (i &lt; len))\\n {\\n propName = propList[i];\\n result = compareValues(a[propName], b[propName]);\\n i++;\\n }\\n return result;\\n }\\n \\n function compareValues(a:Object, b:Object):int\\n {\\n if (a == null &amp;&amp; b == null)\\n return 0;\\n \\n if (a == null)\\n return 1;\\n \\n if (b == null)\\n return -1;\\n \\n if (a &lt; b)\\n return -1;\\n \\n if (a &gt; b)\\n return 1;\\n \\n return 0;\\n }\\n </code></pre> <p>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.</p> <p>Alternatively you can specify separate compare functions for each sort field by using the <code>ISortField</code> class <code>compareFunction</code> property; This way you can use the default comparison for some fields and a custom comparison for others.</p>",
"tags": [
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ]},
{ "type": "accessor",
"access": "read-write",
"return": "Array",
"qname": "fields",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "An <code>Array</code> of <code>ISortField</code> 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.",
"tags": [
{ "tagName": "default",
"values": ["null"]},
{ "tagName": "see",
"values": ["ISortField"]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ]},
{ "type": "accessor",
"access": "read-write",
"return": "Boolean",
"qname": "unique",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "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 <code>unique</code> 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.",
"tags": [
{ "tagName": "default",
"values": ["false"]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ]},
{ "type": "method",
"qname": "findItem",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "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 <code>ListCollectionView</code> class <code>find<i>xxx</i>()</code> methods use this method to find the requested item; as a general rule, it is easier to use these functions, and not <code>findItem()</code> to find data in <code>ListCollectionView</code>-based objects. You call the <code>findItem()</code> method directly when writing a class that supports sorting, such as a new <code>ICollectionView</code> 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. 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 <code>fields</code> property, in the same order they are used in that property. You do not have to specify all of the fields from the <code>fields</code> property, but you cannot skip any in the order. Therefore, if the <code>fields</code> 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. Valid values are: <table> <tr> <th>ANY_INDEX_MODE</th> <th>Return any position that is valid for the values.</th> </tr> <tr> <th>FIRST_INDEX_MODE</th> <th>Return the position where the first occurrance of the values is found.</th> </tr> <tr> <th>LAST_INDEX_MODE</th> <th>Return the position where the last ocurrance of the specified values is found. </th> </tr> </table> identified by the <code>values</code> parameter, and this parameter is <code>true</code> the <code>findItem()</code> method returns the insertion point for the values, that is the point in the sorted order where you should insert the item. If you do not specify this parameter or , or if you provide a <code>null</code> value, <code>findItem()</code> function uses the compare function determined by the <code>ISort</code> instance's <code>compareFunction</code> property, passing in the array of fields determined by the values object and the current <code>SortFields</code>. If you provide a non-null value, <code>findItem()</code> function uses it as the compare function. The signature of the function passed as <code>compareFunction</code> must be as follows: <code>function myCompareFunction(a:Object, b:Object):int</code>. Note that there is no third argument unlike the compare function for <code>ISort.compareFunction()</code> property. If the <code>returnInsertionIndex</code> parameter is <code>false</code> and the item is not found, returns -1. If the <code>returnInsertionIndex</code> parameter is <code>true</code> and the item is not found, returns the index of the point in the sorted array where the values would be inserted. the find critieria is not compatible with the sort or the comparator function for the sort can not be determined.",
"tags": [
{ "tagName": "param",
"values": ["items the Array within which to search.", "values Object containing the properties to look for (or", "mode String containing the type of find to perform.", "returnInsertionIndex If the method does not find an item", "compareFunction a comparator function to use to find the item."]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "throws",
"values": ["SortError If there are any parameter errors,"]},
{ "tagName": "return",
"values": ["int The index in the array of the found item."]},
{ "tagName": "langversion",
"values": ["3.0"]} ],
"return": "int",
"params": [{ "name": "items", "type": "Array"},
{ "name": "values", "type": "Object"},
{ "name": "mode", "type": "String"},
{ "name": "returnInsertionIndex", "type": "Boolean"},
{ "name": "compareFunction", "type": "Function"}]}
,
{ "type": "method",
"qname": "propertyAffectsSort",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "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 <code>true</code> in this case. If the sort uses the default compareFunction, returns <code>true</code> if the <code>property</code> parameter specifies a sort field. If the sort or any <code>ISortField</code> uses a custom comparator, there's no way to know, so return <code>true</code>.",
"tags": [
{ "tagName": "param",
"values": ["property The name of the field to test."]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "return",
"values": ["Whether the property value might affect the sort outcome."]},
{ "tagName": "langversion",
"values": ["3.0"]} ],
"return": "Boolean",
"params": [{ "name": "property", "type": "String"}]}
,
{ "type": "method",
"qname": "reverse",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "Goes through the <code>fields</code> array and calls <code>reverse()</code> on each of the <code>ISortField</code> objects in the array. If the field was descending now it is ascending, and vice versa. <p>Note: an <code>ICollectionView</code> does not automatically update when the objects in the <code>fields</code> array are modified; call its <code>refresh()</code> method to update the view.</p> <p>Note: a future release of Apache Flex SDK will change the signature of this function to return a reversed clone of this Sort instance. See FLEX-34853.</p>",
"tags": [
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ],
"return": "void",
"params": []}
,
{ "type": "method",
"qname": "sort",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "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 <code>items</code> parameter. <p>Flex <code>ICollectionView</code> implementations call the <code>sort</code> method automatically and ensure that the sort is performed on a copy of the underlying data.</p>",
"tags": [
{ "tagName": "param",
"values": ["items Array of items to sort."]},
{ "tagName": "playerversion",
"values": ["Flash 9", "AIR 1.1"]},
{ "tagName": "productversion",
"values": ["Flex 4.5"]},
{ "tagName": "langversion",
"values": ["3.0"]} ],
"return": "void",
"params": [{ "name": "items", "type": "Array"}]}
]
}