Package | fl.data |
Class | public class DataProvider |
Inheritance | DataProvider EventDispatcher Object |
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
A data provider is a linear collection of items that serve as a data source--for
example, an array. Each item in a data provider is an object or XML object that contains one or
more fields of data. You can access the items that are contained in a data provider by index, by
using the DataProvider.getItemAt()
method.
Property | Defined By | ||
---|---|---|---|
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
length : uint [read-only]
The number of items that the data provider contains. | DataProvider | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object |
Method | Defined By | ||
---|---|---|---|
DataProvider(value:Object = null)
Creates a new DataProvider object using a list, XML instance or an array of data objects
as the data source. | DataProvider | ||
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener
receives notification of an event. | EventDispatcher | ||
Appends an item to the end of the data provider. | DataProvider | ||
Adds a new item to the data provider at the specified index. | DataProvider | ||
Appends multiple items to the end of the DataProvider and dispatches
a DataChangeType.ADD event. | DataProvider | ||
Adds several items to the data provider at the specified index and dispatches
a DataChangeType.ADD event. | DataProvider | ||
Creates a copy of the current DataProvider object. | DataProvider | ||
Concatenates the specified items to the end of the current data provider. | DataProvider | ||
Dispatches an event into the event flow. | EventDispatcher | ||
Returns the item at the specified index. | DataProvider | ||
Returns the index of the specified item. | DataProvider | ||
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | ||
Indicates whether an object has a specified property defined. | Object | ||
Invalidates all the data items that the DataProvider contains and dispatches a
DataChangeEvent.INVALIDATE_ALL event. | DataProvider | ||
Invalidates the specified item. | DataProvider | ||
Invalidates the item at the specified index. | DataProvider | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Appends the specified data into the data that the data provider
contains and removes any duplicate items. | DataProvider | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Removes all items from the data provider and dispatches a DataChangeType.REMOVE_ALL
event. | DataProvider | ||
Removes a listener from the EventDispatcher object. | EventDispatcher | ||
Removes the specified item from the data provider and dispatches a DataChangeType.REMOVE
event. | DataProvider | ||
Removes the item at the specified index and dispatches a DataChangeType.REMOVE
event. | DataProvider | ||
Replaces an existing item with a new item and dispatches a DataChangeType.REPLACE
event. | DataProvider | ||
Replaces the item at the specified index and dispatches a DataChangeType.REPLACE
event. | DataProvider | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Sorts the items that the data provider contains and dispatches a DataChangeType.SORT
event. | DataProvider | ||
Sorts the items that the data provider contains by the specified
field and dispatches a DataChangeType.SORT event. | DataProvider | ||
Creates an Array object representation of the data that the data provider contains. | DataProvider | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
[override]
Creates a string representation of the data that the data provider contains. | DataProvider | ||
Returns the primitive value of the specified object. | Object | ||
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher |
Event | Summary | Defined By | ||
---|---|---|---|---|
[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | |||
Dispatched after the data is changed. | DataProvider | |||
[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | |||
Dispatched before the data is changed. | DataProvider |
length | property |
length:uint
[read-only] Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
The number of items that the data provider contains.
Implementation
public function get length():uint
Example ( How to use this example )
import fl.controls.List; import fl.data.DataProvider; var dp:DataProvider = new DataProvider(); dp.addItem({label:"Item 1"}); dp.addItem({label:"Item 2"}); dp.addItem({label:"Item 3"}); dp.addItem({label:"Item 4"}); var myList:List = new List(); myList.dataProvider = dp; myList.rowHeight = 35; myList.rowCount = dp.length; myList.move(10, 10); addChild(myList);
DataProvider | () | Constructor |
public function DataProvider(value:Object = null)
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Creates a new DataProvider object using a list, XML instance or an array of data objects as the data source.
Parametersvalue:Object (default = null ) — The data that is used to create the DataProvider.
|
Example ( How to use this example )
addItem()
method:
import fl.controls.ComboBox; import fl.data.DataProvider; var dp:DataProvider = new DataProvider(); dp.addItem({label:"item 1a"}); dp.addItem({label:"item 2a"}); var myComboBox:ComboBox = new ComboBox() myComboBox.dataProvider = dp; myComboBox.move(10, 10); addChild(myComboBox);
import fl.controls.ComboBox; import fl.data.DataProvider; var arr:Array = new Array(); arr.push({label:"item 1b"}); arr.push({label:"item 2b"}); var dp:DataProvider = new DataProvider(arr); var myComboBox:ComboBox = new ComboBox() myComboBox.dataProvider = dp; myComboBox.move(10, 10); addChild(myComboBox);
import fl.controls.ComboBox; import fl.data.DataProvider; var xml:XML = <items> <item label="item 1c" /> <item label="item 2c" /> </items>; var dp:DataProvider = new DataProvider(xml); var myComboBox:ComboBox = new ComboBox() myComboBox.dataProvider = dp; myComboBox.move(10, 10); addChild(myComboBox);
import fl.controls.ComboBox; import fl.data.DataProvider; var xml:XML = <items> <item> <label>item 1d</label> </item> <item> <label>item 2d</label> </item> </items>; var dp:DataProvider = new DataProvider(xml); var myComboBox:ComboBox = new ComboBox() myComboBox.dataProvider = dp; myComboBox.move(10, 10); addChild(myComboBox);
addItem | () | method |
public function addItem(item:Object):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Appends an item to the end of the data provider.
Parameters
item:Object — The item to be appended to the end of the current data provider.
|
Related API Elements
Example ( How to use this example )
addItem()
method:
import fl.controls.ComboBox; import fl.data.DataProvider; var dp:DataProvider = new DataProvider(); dp.addItem({label:"item 1a"}); dp.addItem({label:"item 2a"}); var myComboBox:ComboBox = new ComboBox() myComboBox.dataProvider = dp; myComboBox.move(10, 10); addChild(myComboBox);
addItemAt | () | method |
public function addItemAt(item:Object, index:uint):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Adds a new item to the data provider at the specified index. If the index that is specified exceeds the length of the data provider, the index is ignored.
Parameters
item:Object — An object that contains the data for the item to be added.
| |
index:uint — The index at which the item is to be added.
|
Throws
RangeError — The specified index is less than 0 or greater than or equal
to the length of the data provider.
|
Related API Elements
addItems | () | method |
public function addItems(items:Object):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Appends multiple items to the end of the DataProvider and dispatches
a DataChangeType.ADD
event. The items are added in the order
in which they are specified.
Parameters
items:Object — The items to be appended to the data provider.
|
Related API Elements
Example ( How to use this example )
addItems()
method to add several items to the data provider:
import fl.controls.DataGrid; import fl.controls.dataGridClasses.DataGridColumn; import fl.data.DataProvider; var arr:Array = [{col1:"1.A", col2:"1.B"}, {col1:"2.A", col2:"2.B"}] var dp:DataProvider = new DataProvider(); dp.addItems(arr); trace(dp.length); // 2 var c1:DataGridColumn = new DataGridColumn("col1"); var c2:DataGridColumn = new DataGridColumn("col2"); var myDataGrid:DataGrid = new DataGrid(); myDataGrid.addColumn(c1); myDataGrid.addColumn(c2); myDataGrid.dataProvider = dp; myDataGrid.setSize(200, 160); myDataGrid.move(10, 10); addChild(myDataGrid);
addItemsAt | () | method |
public function addItemsAt(items:Object, index:uint):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Adds several items to the data provider at the specified index and dispatches
a DataChangeType.ADD
event.
Parameters
items:Object — The items to be added to the data provider.
| |
index:uint — The index at which the items are to be inserted.
|
Throws
RangeError — The specified index is less than 0 or greater than or equal
to the length of the data provider.
|
Related API Elements
clone | () | method |
public function clone():DataProvider
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Creates a copy of the current DataProvider object.
ReturnsDataProvider — A new instance of this DataProvider object.
|
concat | () | method |
public function concat(items:Object):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Concatenates the specified items to the end of the current data provider.
This method dispatches a DataChangeType.ADD
event.
Parameters
items:Object — The items to be added to the data provider.
|
Related API Elements
getItemAt | () | method |
public function getItemAt(index:uint):Object
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Returns the item at the specified index.
Parameters
index:uint — Location of the item to be returned.
|
Object — The item at the specified index.
|
Throws
RangeError — The specified index is less than 0 or greater than
or equal to the length of the data provider.
|
Related API Elements
getItemIndex | () | method |
public function getItemIndex(item:Object):int
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Returns the index of the specified item.
Parameters
item:Object — The item to be located.
|
int — The index of the specified item, or -1 if the specified item is not found.
|
Related API Elements
invalidate | () | method |
public function invalidate():void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Invalidates all the data items that the DataProvider contains and dispatches a
DataChangeEvent.INVALIDATE_ALL
event. Items are invalidated after they
are changed; the DataProvider automatically redraws the invalidated items.
Related API Elements
invalidateItem | () | method |
public function invalidateItem(item:Object):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Invalidates the specified item. An item is invalidated after it is changed; the DataProvider automatically redraws the invalidated item.
Parameters
item:Object — Item to be invalidated.
|
Related API Elements
invalidateItemAt | () | method |
public function invalidateItemAt(index:int):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Invalidates the item at the specified index. An item is invalidated after it is changed; the DataProvider automatically redraws the invalidated item.
Parameters
index:int — Index of the item to be invalidated.
|
Throws
RangeError — The specified index is less than 0 or greater than
or equal to the length of the data provider.
|
Related API Elements
merge | () | method |
public function merge(newData:Object):void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Appends the specified data into the data that the data provider
contains and removes any duplicate items. This method dispatches
a DataChangeType.ADD
event.
Parameters
newData:Object — Data to be merged into the data provider.
|
Related API Elements
removeAll | () | method |
public function removeAll():void
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Removes all items from the data provider and dispatches a DataChangeType.REMOVE_ALL
event.
Related API Elements
removeItem | () | method |
public function removeItem(item:Object):Object
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Removes the specified item from the data provider and dispatches a DataChangeType.REMOVE
event.
Parameters
item:Object — Item to be removed.
|
Object — The item that was removed.
|
Related API Elements
removeItemAt | () | method |
public function removeItemAt(index:uint):Object
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Removes the item at the specified index and dispatches a DataChangeType.REMOVE
event.
Parameters
index:uint — Index of the item to be removed.
|
Object — The item that was removed.
|
Throws
RangeError — The specified index is less than 0 or greater than
or equal to the length of the data provider.
|
Related API Elements
replaceItem | () | method |
public function replaceItem(newItem:Object, oldItem:Object):Object
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Replaces an existing item with a new item and dispatches a DataChangeType.REPLACE
event.
Parameters
newItem:Object — The item to be replaced.
| |
oldItem:Object — The replacement item.
|
Object — The item that was replaced.
|
Throws
RangeError — The item could not be found in the data provider.
|
Related API Elements
replaceItemAt | () | method |
public function replaceItemAt(newItem:Object, index:uint):Object
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Replaces the item at the specified index and dispatches a DataChangeType.REPLACE
event.
Parameters
newItem:Object — The replacement item.
| |
index:uint — The index of the item to be replaced.
|
Object — The item that was replaced.
|
Throws
RangeError — The specified index is less than 0 or greater than
or equal to the length of the data provider.
|
Related API Elements
sort | () | method |
public function sort(... sortArgs):*
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Sorts the items that the data provider contains and dispatches a DataChangeType.SORT
event.
Parameters
... sortArgs — The arguments to use for sorting.
|
* — The return value depends on whether the method receives any arguments.
See the Array.sort() method for more information.
This method returns 0 when the sortOption property
is set to Array.UNIQUESORT .
|
Related API Elements
sortOn | () | method |
public function sortOn(fieldName:Object, options:Object = null):*
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Sorts the items that the data provider contains by the specified
field and dispatches a DataChangeType.SORT
event.
The specified field can be a string, or an array of string values that
designate multiple fields to sort on in order of precedence.
Parameters
fieldName:Object — The item field by which to sort. This value can be a string
or an array of string values.
| |
options:Object (default = null ) — Options for sorting.
|
* — The return value depends on whether the method receives any arguments.
For more information, see the Array.sortOn() method.
If the sortOption property is set to Array.UNIQUESORT ,
this method returns 0.
|
Related API Elements
toArray | () | method |
public function toArray():Array
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Creates an Array object representation of the data that the data provider contains.
ReturnsArray — An Array object representation of the data that the data provider contains.
|
toString | () | method |
override public function toString():String
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Creates a string representation of the data that the data provider contains.
ReturnsString — A string representation of the data that the data provider contains.
|
dataChange | Event |
fl.events.DataChangeEvent
property DataChangeEvent.type =
fl.events.DataChangeEvent.DATA_CHANGE
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Dispatched after the data is changed.
Defines the value of thetype
property of a dataChange
event object.
This event has the following properties:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
changeType | Identifies the type of change that was made. |
currentTarget | The object that is actively processing the event object with an event listener. |
endIndex | Identifies the index of the last changed item. |
items | An array that lists the items that were changed. |
startIndex | Identifies the index of the first changed item. |
target | The object that dispatched the event. The target is
not always the object listening for the event. Use the currentTarget
property to access the object that is listening for the event. |
Related API Elements
preDataChange | Event |
fl.events.DataChangeEvent
property DataChangeEvent.type =
fl.events.DataChangeEvent.PRE_DATA_CHANGE
Language Version: | ActionScript 3.0 |
Product Version: | Flash CS3 |
Runtime Versions: | Flash Player 9.0.28.0, AIR 1.0 |
Dispatched before the data is changed.
Defines the value of thetype
property of a preDataChange
event object. This event object is dispatched before a change is made to component data.
This event has the following properties:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
changeType | Identifies the type of change to be made. |
currentTarget | The object that is actively processing the event object with an event listener. |
endIndex | Identifies the index of the last item to be changed. |
items | An array that lists the items to be changed. |
startIndex | Identifies the index of the first item to be changed. |
target | The object that dispatched the event. The target is
not always the object listening for the event. Use the currentTarget
property to access the object that is listening for the event. |
Related API Elements
To run the example, follow these steps:
- Add the Label, Button, ComboBox, TextInput, and DataGrid components to the library.
- Save this code as DataProviderExample.as in the same directory as your FLA file.
- Set the Document class in the FLA file to DataProviderExample.
package { import fl.controls.Button; import fl.controls.ComboBox; import fl.controls.DataGrid; import fl.controls.Label; import fl.controls.TextInput; import fl.data.DataProvider; import flash.display.Sprite; import flash.events.*; import flash.text.TextFieldAutoSize; public class DataProviderExample extends Sprite { private var southern:DataGrid; private var northern:DataGrid; private var world:DataGrid; private var southernRoster:DataProvider; private var northernRoster:DataProvider; private var leagueCB:ComboBox; private var nameTI:TextInput; private var goalsTI:TextInput; private var submitBtn:Button; public function DataProviderExample() { southernRoster = new DataProvider(); northernRoster = new DataProvider(); createDataGrids(); createUI(); } private function createUI():void { var description:Label = new Label(); description.text = "Enter player's name, goals scored, and hemisphere of origin:"; description.autoSize = TextFieldAutoSize.LEFT; nameTI = new TextInput(); goalsTI = new TextInput(); var submitBtn:Button = new Button(); submitBtn.label = "Submit Player"; submitBtn.addEventListener(MouseEvent.CLICK, submitPlayer); leagueCB = new ComboBox(); leagueCB.addItem( { label:"Northern", data: 0 } ); leagueCB.addItem( { label:"Southern", data: 1 } ); description.move(10,10); nameTI.move(10,40); nameTI.setSize(150,24); goalsTI.move(170,40); goalsTI.setSize(40,24); leagueCB.move(220,40); leagueCB.setSize(120,24); submitBtn.move(350,40); goalsTI.restrict = "0123456789"; addChild(description); addChild(leagueCB); addChild(submitBtn); addChild(nameTI); addChild(goalsTI); } private function submitPlayer(e:MouseEvent):void { if(nameTI.text != "" && goalsTI.text != "") { var targetRoster:DataProvider; if(leagueCB.selectedItem.label == "Southern") { targetRoster = southernRoster; } else { targetRoster = northernRoster; } targetRoster.addItem( { Name: nameTI.text, Goals: goalsTI.text } ); var worldRoster:DataProvider = southernRoster.clone(); worldRoster.merge(northernRoster); worldRoster.sortOn("Goals", Array.NUMERIC | Array.DESCENDING); southernRoster.sortOn("Goals", Array.NUMERIC | Array.DESCENDING); northernRoster.sortOn("Goals", Array.NUMERIC | Array.DESCENDING); world.dataProvider = worldRoster; nameTI.text = ""; goalsTI.text = ""; } } private function createDataGrids():void { southern = new DataGrid(); northern = new DataGrid(); world = new DataGrid(); southern.move(10,100); northern.move(180,100); world.move(350,100); southern.setSize(170, 250); northern.setSize(170, 250); world.setSize(170, 250); southern.columns = northern.columns = world.columns = [ "Name", "Goals" ]; southern.dataProvider = southernRoster; northern.dataProvider = northernRoster; addChild(southern); addChild(northern); addChild(world); var northernLabel:Label = new Label(); northernLabel.autoSize = TextFieldAutoSize.LEFT; northernLabel.text = "Southern Hemisphere"; northernLabel.move(10,75); addChild(northernLabel); var southernLabel:Label = new Label(); southernLabel.autoSize = TextFieldAutoSize.LEFT; southernLabel.text = "Northern Hemisphere"; southernLabel.move(180,75); addChild(southernLabel); var majorLabel:Label = new Label(); majorLabel.autoSize = TextFieldAutoSize.LEFT; majorLabel.text = "World"; majorLabel.move(350,75); addChild(majorLabel); } } }
Mon Nov 28 2011, 06:48 AM -08:00