The GridColumn class defines a column of a Spark grid control,
such as the Spark DataGrid or Grid control.
Each data provider item for the control corresponds to one row of the grid.
The GridColumn class specifies the field of the data provider item
whose value is to be displayed in the column.
It also specifies the item renderer used to display that value, the item editor
used to change the value, and other properties of the column.

dataField

The name of the field or property in the data provider item associated
with the column.
Each GridColumn requires this property or
the labelFunction property to be set
to calculate the displayable text for the item renderer.
If the dataField
and labelFunction properties are set,
the data is displayed using the labelFunction and sorted
using the dataField.

This value of this property is not necessarily the String that
is displayed in the column header. This property is
used only to access the data in the data provider.
For more information, see the headerText property.

If the column or its grid specifies a labelFunction,
then the dataField is not used.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the dataFieldChanged event.

Implementation public function get dataField():String public function set dataField(value:String):void

dataTipField

The name of the field in the data provider to display as the datatip.
By default, if showDataTips is true,
the associated grid control looks for a property named
label on each data provider item and displays it.
However, if the data provider does not contain a label
property, you can set the dataTipField property to
specify a different property name.
For example, you could set the value to "FullName" when a user views a
set of people's names included from a database.

GridColumn.dataTipField takes precedence over this property.

If this column or its grid specifies a value for the
dataTipFunction property, then the
dataTipField property is ignored.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the dataTipFieldChanged event.

Implementation public function get dataTipField():String public function set dataTipField(value:String):void

dataTipFunction

Specifies a callback function to run on each item of the data provider
to determine its data tip.
This property is used by the itemToDataTip method.

By default, if showDataTips is true,
the column looks for a property named label
on each data provider item and displays it as its data tip.
However, some data providers do not have a label property
nor do they have another property that you can use for displaying data
in the rows.

For example, you have a data provider that contains a lastName
and firstName fields, but you want to display full names as the data tip.
You can specify a function to the dataTipFunction property
that returns a single String containing the value of both fields. You
can also use the dataTipFunction property for handling
formatting and localization.

The signature of the dataTipFunction function must match the following:

dataTipFunction(item:Object, column:GridColumn):String

The item parameter is the data provider item for an entire row.
The second parameter is this column object.

A typical function might concatenate an item's firstName and
lastName properties, or do some custom formatting on a Date value
property.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the dataTipFunctionChanged event.

Implementation public function get dataTipFunction():Function public function set dataTipFunction(value:Function):void

editable

Indicates whether the items in the column are editable.
If true, and the associated grid's editable
property is also true, the items in a column are
editable and can be individually edited
by clicking on a selected item, or by navigating to the item and
pressing the F2 key.

The default value is true.

This property can be used as the source for data binding. When this property is modified, it dispatches the editableChanged event.

Implementation public function get editable():Boolean public function set editable(value:Boolean):void

imeMode

Specifies the IME (Input Method Editor) mode.
The IME enables users to enter text in Chinese, Japanese, and Korean.
Flex sets the specified IME mode when the control gets the focus,
and sets it back to the previous value when the control loses the focus.

The flash.system.IMEConversionMode class defines constants for the
valid values for this property.
You can also specify null to specify no IME.

The default value is null.

Implementation public function get imeMode():String public function set imeMode(value:String):void

itemEditor

A class factory for IGridItemEditor class used to edit individual
grid cells in this column.
If this property is null, and the column grid's owner is a DataGrid control,
then the value of the DataGrid control's itemEditor property is used.
If no item editor is specified by the DataGrid control,
then use the DefaultGridItemEditor class.

The default item editor is the DefaultGridItemEditor class,
which lets you edit a simple text field.
You can create custom item renderers by creating a subclass of the GridItemEditor class.
Your custom item editor can write data to the entire row of the grid
to define more complex editor.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the itemEditorChanged event.

Implementation public function get itemEditor():IFactory public function set itemEditor(value:IFactory):void

itemRenderer

The class factory for the IGridItemRenderer class used to
render individual grid cells.
If not specified, use the value of the itemRenderer
property from the associated grid control.

The default item renderer is the DefaultGridItemRenderer class,
which displays the data item as text.
You can create custom item renderers by creating a subclass of the GridItemRenderer class.
Your custom item renderer can access the data from the entire row of the grid
to define more complex visual representation of the cell.

The default value is the value of the itemRenderer
property from the associated grid control, or null.

This property can be used as the source for data binding. When this property is modified, it dispatches the itemRendererChanged event.

Implementation public function get itemRenderer():IFactory public function set itemRenderer(value:IFactory):void

itemRendererFunction

If specified, the value of this property must be an idempotent function
that returns an item renderer IFactory based on its data provider item
and column parameters.
Specifying a value to the itemRendererFunction property
makes it possible to use more than one item renderer in this column.

The function specified to the itemRendererFunction property
must have the following signature:

itemRendererFunction(item:Object, column:GridColumn):IFactory

The item parameter is the data provider item for an entire row.
The second parameter is this column object.

labelFunction

An idempotent function that converts a data provider item into a column-specific string
that's used to initialize the item renderer's label property.

You can use a label function to combine the values of several data provider items
into a single string.
If specified, this property is used by the
itemToLabel() method, which computes the value of each item
renderer's label property in this column.

The function specified to the labelFunction property
must have the following signature:

labelFunction(item:Object, column:GridColumn):String

The item parameter is the data provider item for an entire row.
The second parameter is this column object.

A typical label function could concatenate the firstName and
lastName properties of the data provider item ,
or do some custom formatting on a Date value property.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the labelFunctionChanged event.

Implementation public function get labelFunction():Function public function set labelFunction(value:Function):void

maxWidth

The maximum width of this column in pixels.
If specified, the grid's layout makes the column's layout width the
smaller of the width of the typicalItem and the maxWidth.
If this column is resizable, this property limits how wide the user can make this column.
Setting this property does not change the width
or minWidth properties.

The default value is NaN.

This property can be used as the source for data binding. When this property is modified, it dispatches the maxWidthChanged event.

Implementation public function get maxWidth():Number public function set maxWidth(value:Number):void

minWidth

The minimum width of this column in pixels.
If specified, the grid's layout makes the column's layout
width the larger of the width of the typicalItem and
the minWidth.
If this column is resizable, this property limits how small
the user can make this column.
Setting this property does not change the width
or maxWidth properties.

The default value is 20.

This property can be used as the source for data binding. When this property is modified, it dispatches the minWidthChanged event.

Implementation public function get minWidth():Number public function set minWidth(value:Number):void

rendererIsEditable

Determines whether any of the item renderer's controls are editable.
If the column is editable, the focusable controls in the item renderer
are given keyboard focus when the user starts editing the item
renderer.

When you set this property to true, the cell becomes
editable when the user clicks inside of it.
Because the cell is editable, the DataGrid displays the editorIndicator
skin part, which appears on top of the selectionIndicator skin part.
Therefore, the user does not see an indicator for cell selection until the
edit session is complete.
You can create a custom skin to remove or modify the editorIndicator
skin part so that the selectionIndicator skin part appears.
For example, you can set alpha property of the editorIndicator
to allow the selectionIndicator to show through, or change
the size of the editorIndicator so that it is smaller than the cell.

By setting this property to true, you take responsibility for
validating and saving input collected by the item renderer.
If the item renderer contains an override of the IGridItemRenderer.prepare() method,
then you must ensure that unsaved input field changes are not overwritten.
For example, rendererIsEditable is true
and the renderer contains a single TextInput element that displays
the value of data.myDataField.
If the renderer's prepare() method sets the TextInput control's
text property, then the prepare() method must
not set the text property when there are pending changes.

The default value is false.

This property can be used as the source for data binding. When this property is modified, it dispatches the rendererIsEditableChanged event.

Implementation public function get rendererIsEditable():Boolean public function set rendererIsEditable(value:Boolean):void

resizable

Indicates whether the user is allowed to resize
the width of the column.
If true, and the resizableColumns property of
the associated grid is also true, the user can drag
the grid lines between the column headers to resize the column.

The default value is true.

This property can be used as the source for data binding. When this property is modified, it dispatches the resizableChanged event.

Implementation public function get resizable():Boolean public function set resizable(value:Boolean):void

showDataTips

Indicates whether the datatips are shown in the column.
If true, datatips are displayed for text in the rows.
Datatips are tooltips designed to show the text that is too long for the row.

If this property's value is undefined, the default, then the associated
grid's showDataTips property determines if datatips are shown.
If this property is set, the grid's showDataTips property is ignored.

The default value is undefined.

This property can be used as the source for data binding. When this property is modified, it dispatches the showDataTipsChanged event.

Implementation public function get showDataTips():* public function set showDataTips(value:any):void

sortable

If true, and if the grid's data provider is an ICollectionView,
and if the associated grid's sortableColumns property is true,
then this column supports interactive sorting.
Typically the column's header handles mouse clicks by setting the data provider's
sort property to a Sort object whose SortField is this column's dataField.

If the data provider is not an ICollectionView, then this property has no effect.

The default value is true.

This property can be used as the source for data binding. When this property is modified, it dispatches the sortableChanged event.

Implementation public function get sortable():Boolean public function set sortable(value:Boolean):void

sortField

Returns a SortField that can be used to sort a collection by this
column's dataField.

If the sortCompareFunction property is defined,
then the SortField's compareFunction is automatically set.

If the sortCompareFunction property is not defined
and the dataField is complex, then the SortField's
compare function is assigned to a closure around a default compare
function that handles the complex dataField.

If the sortCompareFunction and
dataField properties are not defined, but the
labelFunction property is defined, then it assigns the
compareFunction to a closure that does a basic string compare
on the labelFunction applied to the data objects.

This method uses the values dataTipField
and dataTipFunction.
If those properties are null, it uses the corresponding properties
from the associated grid control.
If dataTipField properties is also null in the grid control,
then use the dataField property.

If dataTipFunction and dataTipFormatter are
null, then this method's value is the same as:
item[dataTipField].toString(). If dataTipFormatter is
specified then this method's value is the same as:
dataTipFormatter.format(item[dataTipField])
If resolving the item's dataField
causes an error to be thrown, ERROR_TEXT is returned.

If item and dataTipFunction
are not null, then this method returns
dataTipFunction(item, this), where the second argument is
this GridColumn.

itemToLabel

Convert the specified data provider item to a column-specific String.
This method is used to initialize item renderers' label property.

If labelFunction is null, and dataField
is a string that does not contain "." field name separator characters,
and formatter is null, then this method is equivalent to:

item[dataField].toString()

If the formatter was specified, then this method's value is:

formatter.format(item[dataField])

If dataField is a "." separated
path, then this method looks up each successive path element.
For example if ="foo.bar.baz", then this method returns
a string based on the value of item.foo.bar.baz.
If resolving the item's dataField
causes an error to be thrown, ERROR_TEXT is returned.

If item and labelFunction are not null,
then this method returns labelFunction(item, this),
where the second argument is this GridColumn.

itemToRenderer

Convert the specified data provider item to a column-specific item renderer factory.
By default this method calls the itemRendererFunction if it's
non-null, otherwise it just returns the value of the column's itemRenderer
property.