//////////////////////////////////////////////////////////////////////////////// // // 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:
*a should appear before b in
* the sorted sequence.a equals b.a should appear after b in the
* sorted sequence.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 totrue 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.
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.
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;
}
}