////////////////////////////////////////////////////////////////////////////////
//
// 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.controls.listClasses
{
/**
* The interface for "drop-in" item renderers. Most IListItemRenderers
* are not "drop-ins". They are expecting to use a particular field of
* the data provider item. For example, they may assign the "lastName"
* property of the item to a Label's text
property. This
* is easy to write using data-binding, but has the negative
* consequence that the renderer cannot be re-used in another column
* of a DataGrid or another List with different fields.
* IDropInListItemRenderer allows a renderer to be re-used. The list
* classes will pass more information to the renderer so that it
* can determine which field to use at run-time.
*
*
Components that you want to use as drop-in item renderers or drop-in * item editors must implement the IDropInListItemRenderer interface. * Many Flex component implement this interface, and therefore are usable * as drop-in item renderers and drop-in item editors in any column or * list.
* *Drop-in item renderers or drop-in item editors also must implement
* the IDataRenderer interface to define the data
property.
When a component is used as a drop-in item renderer or drop-in
* item editor, Flex initializes the listData
property
* of the component with the appropriate data from the list control.
* The component can then use the listData
property
* to initialize the data
property of the drop-in
* item renderer or drop-in item editor.
The listData
property is of type BaseListData,
* where the BaseListData class has four subclasses:
* DataGridListData, ListData, TreeListData, and MenuListData.
* The actual data type of the value of the listData
property
* depends on the control using the drop-in item renderer or item editor.
* For a DataGrid control, the value is of type DataGridListData,
* for a List control the value is of type ListData,
* for a Tree control, the value is of type TreeListData,
* and for a Menu control, the value is of type MenuListData..
The following example shows the setter method for the
* data
property for the NumericStepper control
* that initializes NumericStepper's value
property
* based on the value of the listData
property:
* public function set data(value:Object):void * { * _data = value; * * this.value = _listData ? parseFloat(_listData.label) : Number(_data); * * dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE)); * } ** *
In the example above, the NumericStepper control ignores the
* data
property when setting NumericStepper's
* value
property, and uses the listData
* property instead.
To implement the IDropInListItemRenderer interface,
* you define a setter and getter method to implement
* the listData
property.
* Typically, the setter method writes the value of the
* listData
property to an internal variable.
* The list class always assigns this property then sets
* the data provider item in the data
property.
Notice that the setter method for the listData
property
* does not dispatch an event.
* This is because the list classes always set listData
,
* then set the data
property.
* Setting the data
property also dispatches the dataChange
event.
* You never set listData
on its own,
* so it does not need to dispatch its own event.
The data
setter method could call the invalidateProperties()
method
* if it did something that required the control to update itself.
* It would then be up to the component developer to write a commitProperties()
method
* to determine that listData
was modified, and handle it accordingly.
The getter method returns the current value * of the internal variable, as the following example shows:
* ** // Internal variable for the property value. * private var _listData:BaseListData; * * // Make the listData property bindable. * [Bindable("dataChange")] * * // Define the getter method. * public function get listData():BaseListData * { * return _listData; * } * * // Define the setter method, * public function set listData(value:BaseListData):void * { * _listData = value; * } ** * @see mx.controls.listClasses.BaseListData * @see mx.core.IDataRenderer * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public interface IDropInListItemRenderer { //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // listData //---------------------------------- /** * Implements the
listData
property
* using setter and getter methods.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function get listData():BaseListData;
/**
* @private
*/
function set listData(value:BaseListData):void;
}
}