Packagefeathers.data
Interfacepublic interface IListCollection extends IFeathersEventDispatcher
Implementors ArrayCollection, ListCollection, VectorCollection, XMLListCollection

Product Version : Feathers 3.3.0

Interface for list collections.



Public Properties
 PropertyDefined By
  filterFunction : Function
A function to determine if each item in the collection should be included or excluded from visibility through APIs like length and getItemAt().
IListCollection
  length : int
[read-only] The number of items in the collection.
IListCollection
  sortCompareFunction : Function
A function to compare each item in the collection to determine the order when sorted.
IListCollection
Public Methods
 MethodDefined By
  
addAll(collection:IListCollection):void
Adds all items from another collection.
IListCollection
  
addAllAt(collection:IListCollection, index:int):void
Adds all items from another collection, placing the items at a specific index in this collection.
IListCollection
 Inherited
addEventListener(type:String, listener:Function):void
Adds a listener for an event type.
IFeathersEventDispatcher
  
addItem(item:Object):void
Adds an item to the end of the collection.
IListCollection
  
addItemAt(item:Object, index:int):void
Adds an item to the collection, at the specified index.
IListCollection
  
contains(item:Object):Boolean
Determines if the specified item is in the collection.
IListCollection
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all listeners added for the specified event type.
IFeathersEventDispatcher
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event from the pool with the specified to all listeners for the specified event type.
IFeathersEventDispatcher
  
dispose(disposeItem:Function):void
Calls a function for each item in the collection that may be used to dispose any properties on the item.
IListCollection
  
getItemAt(index:int):Object
Returns the item at the specified index in the collection.
IListCollection
  
getItemIndex(item:Object):int
Determines which index the item appears at within the collection.
IListCollection
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
Checks if a listener has been added for the specified event type.
IFeathersEventDispatcher
  
pop():Object
Removes the item from the end of the collection and returns it.
IListCollection
  
push(item:Object):void
A convenient alias for addItem().
IListCollection
  
refresh():void
Refreshes the collection using the filterFunction or sortCompareFunction without passing in a new values for these properties.
IListCollection
  
removeAll():void
Removes all items from the collection.
IListCollection
 Inherited
removeEventListener(type:String, listener:Function):void
Removes a listener for an event type.
IFeathersEventDispatcher
 Inherited
removeEventListeners(type:String = null):void
Removes all listeners for an event type.
IFeathersEventDispatcher
  
removeItem(item:Object):void
Removes a specific item from the collection.
IListCollection
  
removeItemAt(index:int):Object
Removes the item at the specified index from the collection and returns it.
IListCollection
  
reset(collection:IListCollection):void
Replaces the collection's data with data from another collection.
IListCollection
  
setItemAt(item:Object, index:int):void
Replaces the item at the specified index with a new item.
IListCollection
  
shift():Object
Removes the first item in the collection and returns it.
IListCollection
  
unshift(item:Object):void
Adds an item to the beginning of the collection.
IListCollection
  
updateAll():void
Call updateAll() to manually inform any component rendering the IListCollection that the properties of all, or many, of the collection's items have changed, and that any rendered views should be updated.
IListCollection
  
updateItemAt(index:int):void
Call updateItemAt() to manually inform any component rendering the IListCollection that the properties of a single item in the collection have changed, and that any views associated with the item should be updated.
IListCollection
Events
 Event Summary Defined By
  Dispatched when an item is added to the collection.IListCollection
  Dispatched when the underlying data source changes and components will need to redraw the data.IListCollection
  Dispatched when the filterFunction property changes or the refresh() function is called on the IListCollection.IListCollection
  Dispatched when an item is removed from the collection.IListCollection
  Dispatched when an item is replaced in the collection.IListCollection
  Dispatched when the collection has changed drastically, such as when the underlying data source is replaced completely.IListCollection
  Dispatched when the sortCompareFunction property changes or the refresh() function is called on the IListCollection.IListCollection
  Dispatched when the updateAll() function is called on the IListCollection.IListCollection
  Dispatched when the updateItemAt() function is called on the IListCollection.IListCollection
Property Detail
filterFunctionproperty
filterFunction:Function

A function to determine if each item in the collection should be included or excluded from visibility through APIs like length and getItemAt().

The function is expected to have the following signature:

function( item:Object ):Boolean

In the following example, the filter function is based on the text of a TextInput component:

var collection:IListCollection; //this would be created from a concrete implementation
var list:List = new List();
list.dataProvider = collection;
this.addChild( list );
var input:TextInput = new TextInput();
input.addEventListener( Event.CHANGE, function():void
{
   if( input.text.length == 0 )
   {
       collection.filterFunction = null;
       return;
   }
   collection.filterFunction = function( item:Object ):Boolean
   {
       var itemText:String = item.label.toLowerCase();
       var filterText:String = input.text.toLowerCase();
       return itemText.indexOf( filterText ) >= 0;
   };
} );
this.addChild( input );

The default value is null.


Implementation
    public function get filterFunction():Function
    public function set filterFunction(value:Function):void
lengthproperty 
length:int  [read-only]

The number of items in the collection.


Implementation
    public function get length():int
sortCompareFunctionproperty 
sortCompareFunction:Function

A function to compare each item in the collection to determine the order when sorted.

The function is expected to have the following signature:

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

The return value should be -1 if the first item should appear before the second item when the collection is sorted. The return value should be 1 if the first item should appear after the second item when the collection in sorted. Finally, the return value should be 0 if both items have the same sort order.

The default value is null.


Implementation
    public function get sortCompareFunction():Function
    public function set sortCompareFunction(value:Function):void
Method Detail
addAll()method
public function addAll(collection:IListCollection):void

Adds all items from another collection.

Parameters

collection:IListCollection

addAllAt()method 
public function addAllAt(collection:IListCollection, index:int):void

Adds all items from another collection, placing the items at a specific index in this collection.

Parameters

collection:IListCollection
 
index:int

addItem()method 
public function addItem(item:Object):void

Adds an item to the end of the collection.

If the collection is filtered, addItem() may add the item to the unfiltered data, but omit it from the filtered data. If the item is omitted from the filtered data, CollectionEventType.ADD_ITEM will not be dispatched.

Parameters

item:Object

addItemAt()method 
public function addItemAt(item:Object, index:int):void

Adds an item to the collection, at the specified index.

If the collection is filtered, the index is the position in the filtered data, rather than position in the unfiltered data.

Parameters

item:Object
 
index:int

contains()method 
public function contains(item:Object):Boolean

Determines if the specified item is in the collection.

If the collection is filtered, contains() will return false for items that are excluded by the filter.

Parameters

item:Object

Returns
Boolean
dispose()method 
public function dispose(disposeItem:Function):void

Calls a function for each item in the collection that may be used to dispose any properties on the item. For example, display objects or textures may need to be disposed.

The function is expected to have the following signature:

function( item:Object ):void

In the following example, the items in the collection are disposed:

collection.dispose( function( item:Object ):void
{
    var accessory:DisplayObject = DisplayObject(item.accessory);
    accessory.dispose();
}

If the collection has a filterFunction, it will be removed, and it will not be restored.

Parameters

disposeItem:Function

See also

getItemAt()method 
public function getItemAt(index:int):Object

Returns the item at the specified index in the collection.

Parameters

index:int

Returns
Object
getItemIndex()method 
public function getItemIndex(item:Object):int

Determines which index the item appears at within the collection. If the item isn't in the collection, returns -1.

If the collection is filtered, getItemIndex() will return -1 for items that are excluded by the filter.

Parameters

item:Object

Returns
int
pop()method 
public function pop():Object

Removes the item from the end of the collection and returns it.

Returns
Object
push()method 
public function push(item:Object):void

A convenient alias for addItem().

Parameters

item:Object

See also

refresh()method 
public function refresh():void

Refreshes the collection using the filterFunction or sortCompareFunction without passing in a new values for these properties. Useful when either of these functions relies on external variables that have changed.

removeAll()method 
public function removeAll():void

Removes all items from the collection.

removeItem()method 
public function removeItem(item:Object):void

Removes a specific item from the collection.

If the collection is filtered, removeItem() will not remove the item from the unfiltered data if it is not included in the filtered data. If the item is not removed, CollectionEventType.REMOVE_ITEM will not be dispatched.

Parameters

item:Object

removeItemAt()method 
public function removeItemAt(index:int):Object

Removes the item at the specified index from the collection and returns it.

If the collection is filtered, the index is the position in the filtered data, rather than position in the unfiltered data.

Parameters

index:int

Returns
Object
reset()method 
public function reset(collection:IListCollection):void

Replaces the collection's data with data from another collection.

Parameters

collection:IListCollection

setItemAt()method 
public function setItemAt(item:Object, index:int):void

Replaces the item at the specified index with a new item.

Parameters

item:Object
 
index:int

shift()method 
public function shift():Object

Removes the first item in the collection and returns it.

Returns
Object
unshift()method 
public function unshift(item:Object):void

Adds an item to the beginning of the collection.

Parameters

item:Object

updateAll()method 
public function updateAll():void

Call updateAll() to manually inform any component rendering the IListCollection that the properties of all, or many, of the collection's items have changed, and that any rendered views should be updated. The collection will dispatch the CollectionEventType.UPDATE_ALL event.

Alternatively, the item can dispatch an event when one of its properties has changed, and a custom item renderer can listen for that event and update itself automatically.

See also

updateItemAt()method 
public function updateItemAt(index:int):void

Call updateItemAt() to manually inform any component rendering the IListCollection that the properties of a single item in the collection have changed, and that any views associated with the item should be updated. The collection will dispatch the CollectionEventType.UPDATE_ITEM event.

Alternatively, the item can dispatch an event when one of its properties has changed, and a custom item renderer can listen for that event and update itself automatically.

Parameters

index:int

See also

Event Detail
addItem Event
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.ADD_ITEM

Dispatched when an item is added to the collection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
dataThe index of the item that has been added. It is of type int.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when an item is added to the collection.
change Event  
Event Object Type: starling.events.Event
Event.type property = starling.events.Event.CHANGE

Dispatched when the underlying data source changes and components will need to redraw the data.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

filterChange Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.FILTER_CHANGE

Dispatched when the filterFunction property changes or the refresh() function is called on the IListCollection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when a filter has been applied to or removed from the collection. The underlying source remains the same, but zero or more items may have been removed or added.

See also

removeItem Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.REMOVE_ITEM

Dispatched when an item is removed from the collection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
dataThe index of the item that has been removed. It is of type int.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when an item is removed from the collection.
replaceItem Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.REPLACE_ITEM

Dispatched when an item is replaced in the collection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
dataThe index of the item that has been replaced. It is of type int.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when an item is replaced in the collection with a different item.
reset Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.RESET

Dispatched when the collection has changed drastically, such as when the underlying data source is replaced completely.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when the data provider's source is completely replaced.
sortChange Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.SORT_CHANGE

Dispatched when the sortCompareFunction property changes or the refresh() function is called on the IListCollection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when a sort compare function has been applied to or removed from the collection. The underlying source remains the same, but the order may be modified.

See also

updateAll Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.UPDATE_ALL

Dispatched when the updateAll() function is called on the IListCollection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when all existing items in the collection have changed (but they have not been replaced by different items).

See also

updateItem Event  
Event Object Type: starling.events.Event
Event.type property = feathers.events.CollectionEventType.UPDATE_ITEM

Dispatched when the updateItemAt() function is called on the IListCollection.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
dataThe index of the item that has been updated. It is of type int.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Dispatched when an item in the collection has changed.

See also