Packagecom.ghostwire.ui.data
Classpublic class uiModel
InheritanceuiModel Inheritance flash.events.EventDispatcher
SubclassesuiMenuModel

Represents a collection of items used as data source for list-based components. Duplicate items are not allowed in a single model but different models can contain the same item(s).

~ This class is available in Aspire UI Components Lite Edition ~



Public Properties
 PropertyDefined by
  length : uint
[read-only] A non-negative integer specifying the number of items in the model.
uiModel
Public Methods
 MethodDefined by
  
uiModel(items:Object = null)
Constructor - creates a new uiModel object.
uiModel
  
addItem(item:Object):void
Appends an item to the model.
uiModel
  
addItems(... items):void
Appends the specified item(s) to the model and dispatches a uiModelEvent.ADD event.
uiModel
  
addItemsAt(index:int, ... items):void
Adds the specified item(s) to the model at the specified index position and dispatches a uiModelEvent.ADD event.
uiModel
  
Returns a copy of this uiModel object.
uiModel
  
cloneItem(item:Object):Object
[static] Returns a copy of an item.
uiModel
  
getItemAt(index:int):Object
Returns the item at the specified index position.
uiModel
  
getItemById(id:String):Object
Returns the item with the specified id property value.
uiModel
  
getItems(startIndex:int, endIndex:int):Array
Returns an array of items in the model starting from startIndex and to endIndex.
uiModel
  
indexOf(item:Object):int
Returns the index position of the item in the model.
uiModel
  
invalidate():void
Invalidates all the items in this model dispatching a uiModelEvent.CHANGE event.
uiModel
  
invalidateItemAt(index:int):void
Invalidates the item at the specified index position dispatching a uiModelEvent.CHANGE event.
uiModel
  
invalidateItems(... items):void
Invalidates the specified item(s) dispatching a uiModelEvent.CHANGE event.
uiModel
  
loadXML(path:String):URLLoader
Loads an external XML file.
uiModel
  
removeAll():void
Removes all item(s) from the model and dispatches a uiModelEvent.REMOVE event.
uiModel
  
removeItem(item:Object):void
Removes a single item from the model.
uiModel
  
removeItemAt(index:int):Object
Removes the item at the specified index position from the model and dispatches a uiModelEvent.REMOVE event.
uiModel
  
removeItems(... items):void
Removes the specified item(s) from the model and dispatches a uiModelEvent.REMOVE event.
uiModel
  
replaceItem(oldItem:Object, newItem:Object):Object
Replaces an existing item in the model with a new item and dispatches a uiModelEvent.REPLACE event.
uiModel
  
sort(... args):Array
Sorts the items in the model and dispatches a uiModelEvent.SORT event.
uiModel
  
sortOn(fieldName:Object, options:Object = null):Array
Sorts the items in the model according to one or more fields and dispatches a uiModelEvent.SORT event.
uiModel
  
swapItems(item1:Object, item2:Object):void
Swaps the index positions of the two specified items.
uiModel
  
toArray():Array
Returns an Array object containing the items in the model.
uiModel
Events
 EventSummaryDefined by
  
add
Dispatched when one or more items have been added to the model.uiModel
   Dispatched when one or more items in the model have been invalidated (modified).uiModel
   Dispatched when one or more items have been removed from the model.uiModel
   Dispatched when an item in the model has been replaced with another item.uiModel
   Dispatched when sorting has been performed on the items in the model.uiModel
Property detail
lengthproperty
length:uint  [read-only]

A non-negative integer specifying the number of items in the model.

Implementation
    public function get length():uint
Constructor detail
uiModel()constructor
public function uiModel(items:Object = null)

Constructor - creates a new uiModel object.

Parameters
items:Object (default = null) — The list of item(s) to populate the model. You can specify an array of data objects (duplicates will be ignored), an array of strings, or an XML object.
Method detail
addItem()method
public function addItem(item:Object):void

Appends an item to the model. This is the same as calling addItems() passing just a single item as the parameter.

Parameters
item:Object — An Object to add to the model.
addItems()method 
public function addItems(... items):void

Appends the specified item(s) to the model and dispatches a uiModelEvent.ADD event. Items that already exist in the model will be ignored (duplicate items are not allowed). If you need to have multiple items with the same properties, use clones. The uiModel.cloneItem() is a helper method for cloning objects.

Items in the model must be of the same type, usually the Object type.

Note: there is nothing stopping you from using this method to add a single item.

Parameters
... items — The list of item(s) to be added. Note that this parameter is of type ... which means you should specify the items as individual parameters, not within an array. Duplicate items will be ignored.
addItemsAt()method 
public function addItemsAt(index:int, ... items):void

Adds the specified item(s) to the model at the specified index position and dispatches a uiModelEvent.ADD event. Items that already exist in the model will be ignored (duplicate items are not allowed). If you need to have multiple items with the same properties, use clones.

Items in the model must be of the same type, usually the Object type.

Note: there is no singular addItemAt() method because there is nothing stopping you from using this method to add a single item.

Parameters
index:int — An integer value indicating the index position in the model. A negative value means counting from the end of the list (-1 being the last item, -2 the last second item, and so on).
 
... items — The list of item(s) to be added. Note that this parameter is of type ... which means you should specify the items as individual parameters, not within an array. Duplicate items will be ignored.
clone()method 
public function clone():uiModel

Returns a copy of this uiModel object.

Returns
uiModel — A copy of this uiModel object.
cloneItem()method 
public static function cloneItem(item:Object):Object

Returns a copy of an item.

Parameters
item:Object

Returns
Object — A copy of the specified item.
getItemAt()method 
public function getItemAt(index:int):Object

Returns the item at the specified index position. Returns null if the model is empty.

Parameters
index:int — An integer value indicating the index position in the model. A negative value means counting from the end of the list (-1 being the last item, -2 the last second item, and so on).

Returns
Object — The item at the specified index position. Returns null if the model is empty.
getItemById()method 
public function getItemById(id:String):Object

Returns the item with the specified id property value. Applicable only if the model is populated using XML where one or more items have an id attribute defined. The id property value should be unique to each item.

Returns null if the model is empty or if an item with matching id property value does not exist.

Parameters
id:String — A String value used to identify the item. This identifer should be unique within the model (should be used by only one item).

Returns
Object — The item with the specified id property value.
getItems()method 
public function getItems(startIndex:int, endIndex:int):Array

Returns an array of items in the model starting from startIndex and to endIndex.

Parameters
startIndex:int
 
endIndex:int

Returns
Array — An array of items within the specified range.
indexOf()method 
public function indexOf(item:Object):int

Returns the index position of the item in the model. A value of -1 means that the item does not exist in this model.

Parameters
item:Object

Returns
int — An integer value indicating the index position of the item in the model.
invalidate()method 
public function invalidate():void

Invalidates all the items in this model dispatching a uiModelEvent.CHANGE event. Technically speaking, this method does nothing except to notify listeners that the items have been modified and renderers should be refreshed.

See also

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

Invalidates the item at the specified index position dispatching a uiModelEvent.CHANGE event. Technically speaking, this method does nothing except to notify listeners that the specified item has been modified.

Parameters
index:int — An integer value indicating the index position in the model. A negative value means counting from the end of the list (-1 being the last item, -2 the last second item, and so on).

See also

invalidateItems()method 
public function invalidateItems(... items):void

Invalidates the specified item(s) dispatching a uiModelEvent.CHANGE event. Technically speaking, this method does nothing except to notify listeners that the specified item(s) have been modified and renderers should be refreshed.

If you modify the contents of an item/object direcly, make sure you use this method to notify listeners of the change.

If you need to invalidate an item at a specific index position, you can do the following:
model.invalidateItems(model.getItemAt(index));

Parameters
... items — The list of item(s) to be invalidated. Note that this parameter is of type ... which means you should specify the items as individual parameters, not within an array.

See also

loadXML()method 
public function loadXML(path:String):URLLoader

Loads an external XML file. When the file has been loaded successfully, it will be parsed into an array of items and the model will be populated with the new items. Any existing items will be removed. A uiModelEvent.REMOVE event will be dispatched, followed by a uiModelEvent.ADD event.

Parameters
path:String — A string value indicating the path to the XML file to load.

Returns
URLLoader — The URLLoader object used to load the XML file.
removeAll()method 
public function removeAll():void

Removes all item(s) from the model and dispatches a uiModelEvent.REMOVE event.

See also

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

Removes a single item from the model. This is the same as calling removeItems() passing just a single item as the parameter.

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

Removes the item at the specified index position from the model and dispatches a uiModelEvent.REMOVE event.

Parameters
index:int — An integer value indicating the index position in the model. A negative value means counting from the end of the list (-1 being the last item, -2 the last second item, and so on).

Returns
Object — The item that is removed. Returns null if the model is empty.

See also

removeItems()method 
public function removeItems(... items):void

Removes the specified item(s) from the model and dispatches a uiModelEvent.REMOVE event.

Note: there is nothing stopping you from using this method to remove a single item.

Parameters
... items — The list of item(s) to be removed. Note that this parameter is of type ... which means you should specify the items as individual parameters, not within an array.

See also

replaceItem()method 
public function replaceItem(oldItem:Object, newItem:Object):Object

Replaces an existing item in the model with a new item and dispatches a uiModelEvent.REPLACE event.

Note: there is no replaceItemAt() method because you are allowed to specify the index position for the oldItem parameter instead of the item itself (thereby achieving the same result as a replaceItemAt() method).

Parameters
oldItem:Object — The existing item to be replaced. Must exist in the model otherwise the method fails silently and returns null. You can also specify the index position of the item instead.
 
newItem:Object — The new item. Must be of the same type as the item it is replacing and must also not already exist in the model, otherwise the method fails silently and returns null.

Returns
Object — The item that was replaced (removed) or null if no replacement was done.
sort()method 
public function sort(... args):Array

Sorts the items in the model and dispatches a uiModelEvent.SORT event. It is recommended that you use the sortOn() method to sort the items in the model. The sort() method is useful only if you wish to specify a custom compareFunction parameter.

Note: it is not efficient to track and pick up items that were actually affected by sorting, or if the items were reordered at all, so a uiModelEvent.SORT event will be dispatched regardless of the result and we assume that all the items in the model have been affected.

This method has the same signature as the sort() method in the Array class - please reference Adobe documentation for the Array class.

Parameters
... args — Please reference Adobe documentation for the Array class.

Returns
Array — Please reference Adobe documentation for the Array class.

See also

sortOn()method 
public function sortOn(fieldName:Object, options:Object = null):Array

Sorts the items in the model according to one or more fields and dispatches a uiModelEvent.SORT event.

Note: it is not efficient to track and pick up items that were actually affected by sorting, or if the items were reordered at all, so a uiModelEvent.SORT event will be dispatched regardless of the result and we assume that all the items in the model have been affected.

This method has the same signature as the sort() method in the Array class - please reference Adobe documentation for the Array class.

Parameters
fieldName:Object — Please reference Adobe documentation for the Array class.
 
options:Object (default = null) — Please reference Adobe documentation for the Array class.

Returns
Array — Please reference Adobe documentation for the Array class.
swapItems()method 
public function swapItems(item1:Object, item2:Object):void

Swaps the index positions of the two specified items. A uiModelEvent.SORT event will be dispatched if a swap actually occurs (if two specified items are the same, no swap occurs, of course).

Parameters
item1:Object — The first item. This can be the object itself or the index position of the item.
 
item2:Object — The second item. This can be the object itself or the index position of the item.
toArray()method 
public function toArray():Array

Returns an Array object containing the items in the model.

Returns
Array — An Array object containing the items in the model.
Event detail
addevent 
Event object type: com.ghostwire.ui.events.uiModelEvent
uiModelEvent.type property = com.ghostwire.ui.events.uiModelEvent.ADD

Dispatched when one or more items have been added to the model.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener.
targetThe 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.
changeListAn array that lists the items that were added.
changeevent  
Event object type: com.ghostwire.ui.events.uiModelEvent
uiModelEvent.type property = com.ghostwire.ui.events.uiModelEvent.CHANGE

Dispatched when one or more items in the model have been invalidated (modified). Do remember that if you modify the contents of an item directly, you have to call invalidateItem() to ensure that the item is invalidated (and this event dispatched).

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener.
targetThe 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.
changeListAn array that lists the items that were modified.
removeevent  
Event object type: com.ghostwire.ui.events.uiModelEvent
uiModelEvent.type property = com.ghostwire.ui.events.uiModelEvent.REMOVE

Dispatched when one or more items have been removed from the model.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener.
targetThe 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.
changeListAn array that lists the items that were removed.
replaceevent  
Event object type: com.ghostwire.ui.events.uiModelEvent
uiModelEvent.type property = com.ghostwire.ui.events.uiModelEvent.REPLACE

Dispatched when an item in the model has been replaced with another item.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener.
targetThe 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.
changeListAn array containing two elements - the first is the replaced item, the second is the new item.
sortevent  
Event object type: com.ghostwire.ui.events.uiModelEvent
uiModelEvent.type property = com.ghostwire.ui.events.uiModelEvent.SORT

Dispatched when sorting has been performed on the items in the model. This event is also dispatched if two items in the model have swapped positions as a result of the swapItems() method.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener.
targetThe 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.
changeListAn array that lists all the items affected by the sort function. In the case where this event is dispatched as a result of sort() or sortOn(), the array contains all the items in the model (we assume all items have been affected). In the case where this event is dispatched as a result of swapItems(), the array contains the two items that have swapped positions.