//////////////////////////////////////////////////////////////////////////////// // // 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 { //-------------------------------------- // Other metadata //-------------------------------------- [DefaultProperty("fields")] /** * The Grouping class defines the fields in the data provider of * the AdvancedDataGrid control used to group data. You use this * class to create groups when the input data to the AdvancedDataGrid control * has a flat structure. * *
To populate the AdvancedDataGrid control with grouped data,
* you create an instance of the GroupingCollection class from your flat data,
* and then pass that GroupingCollection instance to the data provider
* of the AdvancedDataGrid control.
* To specify the grouping fields of your flat data,
* you pass a Grouping instance to
* the GroupingCollection.grouping property.
* The Grouping instance contains an Array of GroupingField instances,
* one per grouping field.
The following example uses the Grouping class to define * two grouping fields: Region and Territory.
* *
* <mx:AdvancedDataGrid id="myADG"
* <mx:dataProvider>
* <mx:GroupingCollection id="gc" source="{dpFlat}">
* <mx:grouping>
* <mx:Grouping>
* <mx:GroupingField name="Region"/>
* <mx:GroupingField name="Territory"/>
* </mx:Grouping>
* </mx:grouping>
* </mx:GroupingCollection>
* </mx:dataProvider>
*
* <mx:columns>
* <mx:AdvancedDataGridColumn dataField="Region"/>
* <mx:AdvancedDataGridColumn dataField="Territory"/>
* <mx:AdvancedDataGridColumn dataField="Territory_Rep"/>
* <mx:AdvancedDataGridColumn dataField="Actual"/>
* <mx:AdvancedDataGridColumn dataField="Estimate"/>
* </mx:columns>
* </mx:AdvancedDataGrid>
*
*
* @mxml
*
* The <mx.Grouping> tag defines the following tag attributes:
*
* * <mx:Grouping * Properties * compareFunction="No default" * fields="null" * groupingObjectFunction="No default" * label="GroupLabel" * /> ** * @see mx.controls.AdvancedDataGrid * @see mx.collections.GroupingCollection * @see mx.collections.GroupingField * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public class Grouping { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function Grouping():void { super(); } //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //--------------------------------- // label //--------------------------------- /** * The name of the field added to the flat data * to create the hierarchy. * The value of the top nodes (nodes representing the group fields) * in every group will be represented * by this property. * Use this property to specify a different name. * * @default GroupLabel * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var label:String = "GroupLabel"; //--------------------------------- // compareFunction //--------------------------------- /** * @private * Storage for the compareFunction property. */ private var _compareFunction:Function; [Inspectable(category="General")] /** * 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:
*a should appear before b in
* the sorted sequence.a equals b.a should appear after b in the
* sorted sequence.To return to the internal comparison 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, * with case-sensitive or case-insensitive string comparisons. * Specify your own function only if you 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.
You can supply a groupingObjectFunction that provides the
* appropriate Object for group nodes.
The method signature is:
*
* myGroupObjectFunction(label:String):Object
*
* Where label contains the value that will be
* shown for that group node.
* The function returns an Object which will be used for group nodes.
groupingObjectFunction which returns an Object
* containing a "name" property with value as "Bob" can be written as -
*
* private function groupObjFunction(label:String):Object
* {
* var obj:Object = {};
* obj.name = "Bob";
*
* return obj;
* }
*
*
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public var groupingObjectFunction:Function;
}
}