Packagefeathers.data
Classpublic class XMLListCollection
InheritanceXMLListCollection Inheritance starling.events.EventDispatcher
Implements IListCollection

Product Version : Feathers 3.3.0

Wraps an XMLList in the common IListCollection API used by many Feathers UI controls, including List and TabBar.



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().
XMLListCollection
  length : int
[read-only] The number of items in the collection.
XMLListCollection
  sortCompareFunction : Function
A function to compare each item in the collection to determine the order when sorted.
XMLListCollection
  xmlListData : XMLList
The XMLList data source for this collection.
XMLListCollection
Public Methods
 MethodDefined By
  
XMLListCollection(data:XMLList = null)
Constructor.
XMLListCollection
  
addAll(collection:IListCollection):void
Adds all items from another collection.
XMLListCollection
  
addAllAt(collection:IListCollection, index:int):void
Adds all items from another collection, placing the items at a specific index in this collection.
XMLListCollection
  
addItem(item:Object):void
Adds an item to the end of the collection.
XMLListCollection
  
addItemAt(item:Object, index:int):void
Adds an item to the collection, at the specified index.
XMLListCollection
  
contains(item:Object):Boolean
Determines if the specified item is in the collection.
XMLListCollection
  
dispose(disposeItem:Function):void
Calls a function for each item in the collection that may be used to dispose any properties on the item.
XMLListCollection
  
getItemAt(index:int):Object
Returns the item at the specified index in the collection.
XMLListCollection
  
getItemIndex(item:Object):int
Determines which index the item appears at within the collection.
XMLListCollection
  
pop():Object
Removes the item from the end of the collection and returns it.
XMLListCollection
  
push(item:Object):void
A convenient alias for addItem().
XMLListCollection
  
refresh():void
Refreshes the collection using the filterFunction or sortCompareFunction without passing in a new values for these properties.
XMLListCollection
  
removeAll():void
Removes all items from the collection.
XMLListCollection
  
removeItem(item:Object):void
Removes a specific item from the collection.
XMLListCollection
  
removeItemAt(index:int):Object
Removes the item at the specified index from the collection and returns it.
XMLListCollection
  
reset(collection:IListCollection):void
Replaces the collection's data with data from another collection.
XMLListCollection
  
setItemAt(item:Object, index:int):void
Replaces the item at the specified index with a new item.
XMLListCollection
  
shift():Object
Removes the first item in the collection and returns it.
XMLListCollection
  
unshift(item:Object):void
Adds an item to the beginning of the collection.
XMLListCollection
  
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.
XMLListCollection
  
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.
XMLListCollection
Events
 Event Summary Defined By
  Dispatched when an item is added to the collection.XMLListCollection
  Dispatched when the underlying data source changes and components will need to redraw the data.XMLListCollection
  Dispatched when the filterFunction property changes or the refresh() function is called on the IListCollection.XMLListCollection
  Dispatched when an item is removed from the collection.XMLListCollection
  Dispatched when an item is replaced in the collection.XMLListCollection
  Dispatched when the collection has changed drastically, such as when the underlying data source is replaced completely.XMLListCollection
  Dispatched when the sortCompareFunction property changes or the refresh() function is called on the IListCollection.XMLListCollection
  Dispatched when the updateAll() function is called on the ListCollection.XMLListCollection
  Dispatched when the updateItemAt() function is called on the ListCollection.XMLListCollection
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 );


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.


Implementation
    public function get sortCompareFunction():Function
    public function set sortCompareFunction(value:Function):void
xmlListDataproperty 
xmlListData:XMLList

The XMLList data source for this collection.


Implementation
    public function get xmlListData():XMLList
    public function set xmlListData(value:XMLList):void
Constructor Detail
XMLListCollection()Constructor
public function XMLListCollection(data:XMLList = null)

Constructor.

Parameters
data:XMLList (default = null)
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 ListCollection.

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 ListCollection.

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