SitedList

A list collection class that can be sited and fires change notifications.

Remarks

SitedList is a subclass of SitedObject that adds array-like collection behavior. When you add or remove items from SitedList it fires change notifications, telling listeners that the list has changed. This is used by the binding engine to update the user interface when the contents of a list changes.

Typically, SitedList contains a list of SitedObjects, though it may contain other kinds of objects, notably strings or numbers.

See Also

DataList

Events

ID_listChangedEvent handler called when the list changes.

Methods

addAdds an item to the list. Notifies listeners of the change.
addEventHandler (inherited from SitedObject)Adds a delegate to be called when the specified eventId occurs on this object.
addOrFlattenItem
containsTests if this list contains the specified object.
equals (inherited from SitedObject)Tests if two objects are equal.
fireEventHandler (inherited from SitedObject)Invokes any user event handlers registered for a particular event using SitedObject.addEventHandler().
flatten Creates a SitedList from the list of arguments, expanding any nested arrays into individual elements, recursively.
getBindingStatus (inherited from SitedObject)Provides debugging information on bindings for this object.
getInternalArrayGets the JavaScript Array object used internally to store the list's items.
getLengthGets the number of items in the list.
getPathValue (inherited from SitedObject)Traverses a binding path and returns the value at the end of it.
getPropertyInfo (inherited from SitedObject)Gets information on a property.
getSite (inherited from SitedObject)Gets this object's site.
getValue(Override) Gets the value of a property on this object.
indexOfGets the index of the specified object.
insertInserts an item in the list at the specified index. Notifies listeners of the change.
onSetValue(Override) Called by SitedObject.setValue() when a property value is set on this object.
onSited (inherited from SitedObject)Called when this object is sited.
onUnsited (inherited from SitedObject)Called when this object is about to lose its site.
onValueSited (inherited from SitedObject)Called when an object is sited within this object.
onValueUnsited (inherited from SitedObject)Called when an object is about to be unsited in this.
removeRemoves the specified object from the list. Notifies listeners of the change.
removeAtRemoves the item at the specified index. Notifies listeners of the change.
removeEventHandler (inherited from SitedObject)Remove an existing delegate from the list of delegates for the specified event.
setInitialValues (inherited from SitedObject)Sets multiple property values on an object (during initialization only)
setItemsWholesale replacement of this lists contents with another list's contents. Fires change notifications.
setPathValue (inherited from SitedObject)Traverses a binding path and sets the value at the end of it.
setValue(Override) Sets the value of a property on this object.
toArrayReturns a copy of this list's items as an array.
toString (inherited from SitedObject)Returns a string representation of this object.

SitedList add method

Adds an item to the list. Notifies listeners of the change.

JavaScript

sitedList.add(newVal)

SitedList addOrFlattenItem static method

JavaScript

SitedList.addOrFlattenItem(list,item,curIndex)

SitedList contains method

Tests if this list contains the specified object.

JavaScript

var boolVal = sitedList.contains(obj)

Returns

true if this list contains obj, false otherwise.

SitedList flatten static method

Creates a SitedList from the list of arguments, expanding any nested arrays into individual elements, recursively.

JavaScript

SitedList.flatten()

SitedList getInternalArray method

Gets the JavaScript Array object used internally to store the list's items.

JavaScript

var array = sitedList.getInternalArray()

Remarks

This method is provided for efficiently iterating over a SitedList. Use this inner array with caution. Modifying internal array values directly does not notify listeners and hence causes trouble with the binding system. Also, the inner array may contain "SitedReference objects, which could catch casual users off-guard.

Returns

A JavaScript Array instance.

SitedList getLength method

Gets the number of items in the list.

JavaScript

var intVal = sitedList.getLength()

Returns

The length of the list.

SitedList getValue method (override)

Gets the value of a property on this object.

JavaScript

var obj = sitedList.getValue(indexOrId)

Remarks

Extends SitedObject.getValue() to support both integer index access.

If passed an integer index, it returns the item at that index, or null if the index is out of bounds.

Otherwise, if passed a propertyId, the ID can be one of the properties associated with the list, e.g. ID_length to return the length of the list.

Returns

The value of the property, or null if the property is not defined.The object at specified index if indexOrId is an integer. Otherwise, if indexOrId is an propertyId, the value of the specified property. Returns null if the property is not defined.

Example

To get the first entry in a list, use:

var mylist = new SitedList('abc');
alert(mylist.getValue(0)); // shows 'abc' in an alert box

Base Implementation

SitedList ID_listChanged event

Event handler called when the list changes.

JavaScript

sitedList.addEventHandler(ID_listChanged, new Delegate(obj, func))

Xml

<j:SitedList listChanged="alert('listChanged happened')" ... >

Remarks

This event is fired when just after an item has beeen added to, removed from, or replaced in the list.

The eventArgs for ID_listChanged is a JavaScript object with the following properties:

PropertyDescription
eventIdThe value ID_listChanged.
reasonEither ID_itemInserted, ID_itemRemoved or ID_itemReplaced.
indexThe index in the list where the change is taking place.
oldValuefor ID_itemRemoved or ID_itemReplaced, the item in the list being removed or replaced.
newValueFor ID_itemInserted and or ID_itemReplaced, the incoming value that is being inserted.

Example

The following JavaScript code:

// define an event handler
function printEvent(sender, eventArgs) {
	Diagnostics.write(eventArgs.reason + " " + eventArgs.index);
}

// create a list
var mylist = new SitedList();

// add an event handler
mylist.addEventHandler(ID_listChanged, new Delegate(null, printEvent));

// change the list
mylist.add("item 1");
mylist.add("item 2");
mylist.removeAt("0");

prints this in the Jitsu inspector pane:

itemInserted 0
itemInserted 1
itemRemoved 0

SitedList indexOf method

Gets the index of the specified object.

JavaScript

var intVal = sitedList.indexOf(obj)

Returns

The index of the specified object, or -1 if the object is not in the list.

SitedList insert method

Inserts an item in the list at the specified index. Notifies listeners of the change.

JavaScript

sitedList.insert(newVal,index)

SitedList onSetValue method (override)

Called by SitedObject.setValue() when a property value is set on this object.

JavaScript

sitedList.onSetValue(propertyId,oldVal,newVal,notificationSource)

Remarks

This extends SitedObject.onSetValue() to detect when an item is set on the list, firing event handlers.

Base Implementation

Overriden In

SitedList remove method

Removes the specified object from the list. Notifies listeners of the change.

JavaScript

var intVal = sitedList.remove(obj)

Returns

The index of the removed object, or -1 if the object is not found.

SitedList removeAt method

Removes the item at the specified index. Notifies listeners of the change.

JavaScript

sitedList.removeAt(index)

SitedList setItems method

Wholesale replacement of this lists contents with another list's contents. Fires change notifications.

JavaScript

sitedList.setItems(items)

Remarks

items must be an array.

SitedList setValue method (override)

Sets the value of a property on this object.

JavaScript

sitedList.setValue(index,value)

Remarks

Extends SitedObject.setValue() to add support for integer index access.

Example

To replace the first entry in a list, use:

var mylist = new SitedList('abc');
mylist.setValue(0, 'def'); // replaces 'abc'

Base Implementation

SitedList toArray method

Returns a copy of this list's items as an array.

JavaScript

sitedList.toArray()