//////////////////////////////////////////////////////////////////////////////// // // 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("summaries")] /** * The GroupingField class represents individual data fields * that you use to group flat data for display by the AdvancedDataGrid control. * *

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.GroupingField> inherits all the tag attributes of its superclass, * and defines the following tag attributes:

* * 
 *  <mx:GroupingField
 *  Properties 
 *    caseInsensitive="false|true"
 *    compareFunction="No default"
 *    descending="false|true"
 *    groupingFunction="No default"
 *    groupingObjectFunction="No default"
 *    name="null"
 *    numeric="false|true"
 *    summaries="No default"
 *  />
 *
* * @see mx.controls.AdvancedDataGrid * @see mx.collections.GroupingCollection * @see mx.collections.Grouping * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public class GroupingField { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. * * @param name The name of the property that this field uses for * comparison. * If the object is a simple type, pass null. * @param caseInsensitive When sorting strings, tells the comparitor * whether to ignore the case of the values. * @param descending Tells the comparator whether to arrange items in * descending order. * @param numeric Tells the comparitor whether to compare sort items as * numbers, instead of alphabetically. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function GroupingField(name:String=null, caseInsensitive:Boolean=false, descending:Boolean=false, numeric:Boolean=false) { super(); _name = name; _caseInsensitive = caseInsensitive; _descending = descending; _numeric = numeric; } //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //--------------------------------- // caseInsensitive //--------------------------------- /** * @private * Storage for the caseInsensitive property. */ private var _caseInsensitive:Boolean; [Inspectable(category="General")] /** * Set to true if the sort for this field should be case-insensitive. * * @default false * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get caseInsensitive():Boolean { return _caseInsensitive; } /** * @private */ public function set caseInsensitive(value:Boolean):void { if (value != _caseInsensitive) { _caseInsensitive = value; } } //--------------------------------- // compareFunction //--------------------------------- /** * @private * Storage for the compareFunction property. */ private var _compareFunction:Function; [Inspectable(category="General")] /** * The function that compares two items during a sort of items for the * associated collection. If you specify a compareFunction * property in a Grouping object, Flex ignores any compareFunction * properties of the GroupingField objects. * *

The compare function must have the following signature:

* * 
function myCompare(a:Object, b:Object):int
* *

This function must return the following values:

* * *

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.

* * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get compareFunction():Function { return _compareFunction; } /** * @private */ public function set compareFunction(c:Function):void { _compareFunction = c; } //--------------------------------- // descending //--------------------------------- /** * @private * Storage for the descending property. */ private var _descending:Boolean; [Inspectable(category="General")] /** * Set to true if the sort for this field should be * in descending order. * * @default false * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get descending():Boolean { return _descending; } /** * @private */ public function set descending(value:Boolean):void { if (_descending != value) { _descending = value; } } //--------------------------------- // name //--------------------------------- /** * @private * Storage for the name property. */ private var _name:String; [Inspectable(category="General")] /** * The name of the field to be sorted. * * @default null * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get name():String { return _name; } /** * @private */ public function set name(n:String):void { _name = n; } //--------------------------------- // numeric //--------------------------------- /** * @private * Storage for the numeric property. */ private var _numeric:Boolean; [Inspectable(category="General")] /** * Specifies that if the field being sorted contains numeric * (Number/int/uint) values, or String representations of numeric values, * the comparitor uses a numeric comparison. * If this property is false, fields with String representations * of numbers are sorted using String comparison, so 100 precedes 99, * because "1" is a lower string value than "9". * * @default false * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get numeric():Boolean { return _numeric; } /** * @private */ public function set numeric(value:Boolean):void { if (_numeric != value) { _numeric = value; } } //--------------------------------- // groupingFunction //--------------------------------- /** * A function that determines the label for this group. * By default, * the group displays the text for the field in the data that matches the * filed specified by the name property. * However, sometimes you want to group the items based on * more than one field in the data, or group based on something that is * not a simple String field. * In such a case, you specify a callback function by using * the groupingFunction property. * *

A callback function might convert a number for the month into * the String for the month, or group multiple items into a single group * based on some criteria other than the actual value of the field.

* *

For the GroupField, the method signature has the following form:

* * 
groupingFunction(item:Object, field:GroupField):String
* *

Where item contains the data item object, and * field contains the GroupField object.

* * For example, a groupingFunction which returns the * first character as the group name can be written as - * 
     *  private function groupFunc(item:Object, field:GroupingField):String
     *  {
     *      return item[field.name].toString().substr(0, 1);
     *  }
     *
* * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var groupingFunction:Function; //--------------------------------- // groupingObjectFunction //--------------------------------- /** * A callback function to run on each group node to determine the * grouping object. * By default, a new Object will be created for group nodes. * *

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 that will be used for group nodes.

* * For example, a 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; //--------------------------------- // summaries //--------------------------------- /** * Array of SummaryRow instances that define the group-level summaries. * Specify one or more SummaryRow instances to define the data summaries, * as the following example shows: * * 
     *  <mx:AdvancedDataGrid id="myADG" 
     *     width="100%" height="100%" 
     *     initialize="gc.refresh();">        
     *     <mx:dataProvider>
     *         <mx:GroupingCollection id="gc" source="{dpFlat}">
     *             <mx:Grouping>
     *                 <mx:GroupingField name="Region">
     *                   <mx:summaries>
     *                       <mx:SummaryRow summaryPlacement="group">
     *                         <mx:fields>
     *                             <mx:SummaryField dataField="Actual" 
     *                                 label="Min Actual" operation="MIN"/>
     *                             <mx:SummaryField dataField="Actual" 
     *                                 label="Max Actual" operation="MAX"/>
     *                         </mx:fields>
     *                       </mx:SummaryRow>
     *                     </mx:summaries>
     *                 </mx:GroupingField>
     *             </mx:Grouping>
     *         </mx:GroupingCollection>
     *     </mx:dataProvider>        
     *     
     *     <mx:columns>
     *         <mx:AdvancedDataGridColumn dataField="Region"/>
     *         <mx:AdvancedDataGridColumn dataField="Territory_Rep"
     *             headerText="Territory Rep"/>
     *         <mx:AdvancedDataGridColumn dataField="Actual"/>
     *         <mx:AdvancedDataGridColumn dataField="Estimate"/>
     *         <mx:AdvancedDataGridColumn dataField="Min Actual"/>
     *         <mx:AdvancedDataGridColumn dataField="Max Actual"/>
     *     </mx:columns>
     *  </mx:AdvancedDataGrid>  
     *
* * @see mx.collections.SummaryRow * @see mx.collections.SummaryField * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var summaries:Array; } }