ETCollection
ETCollectionMutationOverview
Additional collection protocol that all mutable collections must support. EtoileFoundation extends Foundation classes such as NSMutableArray, NSMutableDictionary, NSMutableSet, NSCountedSet and NSMutableIndexSet to adopt this protocol. EtoileUI extends NSView in the same way.
Given most protocol method implementations remains the same accross collection classes, we provide ETMutableCollectionTrait as a reusable ETCollectionMutation implementation.
The two primitive methods are -insertObject:atIndex:hint: and -removeObject:atIndex:hint: . These methods must be implemented in the collection class in all cases. See ETMutableCollectionTrait.
When you write a new class that includes a mutable to-many relationship, it should conform to ETCollectionMutation, based on the rules presented in ETCollection documentation.
EtoileUI can automatically mutate collection-like content and support turning user actions (e.g. drag an drop) into collection operations, when represented objects bound to ETLayoutItemGroup conform to ETCollectionMutation in addition to ETCollection.
Default
- - (void) addObject: (id)object
Adds the element to the collection.
A collection can raise an exception on a nil object.
When the collection is ordered, the element is inserted as the last element.
- - (void) insertObject: (id)object atIndex: (NSUInteger)index
Inserts the element at the given index in the collection.
A collection can raise an exception on a nil object.
An ordered collection can raise an exception on an invalid index such as ETUndeterminedIndex (this is not the same behavior than -insertObject:atIndex:hint:).When the collection is not ordered, the index is ignored and the behavior is the same than -addObject: .
- - (void) removeObject: (id)object
Removes the element from the collection.
A collection can raise an exception on a nil object.
- - (void) removeObjectAtIndex: (NSUInteger)index
Removes the element at the given index from the collection.
An ordered collection can raise an exception on an invalid index such as ETUndeterminedIndex.
When the collection is not ordered, an exception should be raised.
- - (void) insertObject: (id)object atIndex: (NSUInteger)index hint: (id)hint
Inserts the element at the given index in the collection, by making adjustments based on the hint if needed.
The element to be inserted must never be nil. The collection can raise an exception in such case.
If the collection is not ordered, the index can be ignored (the insertion becomes an addition), but otherwise it must not.
If the index is ETUndeterminedIndex, the insertion must be treated as an addition and the object inserted in last position if the collection is ordered e.g. NSMutableArray. See also -addObject: .
If the hint is not nil, the collection can test the hint type. If the hint matches its expectation, it's up to the collection to choose another index and/or another element to insert. Both the custom index and element can be provided by the hint.
The collection must continue to behave in a predictable way (as detailed above) when no hint is provided.
- - (void) removeObject: (id)object atIndex: (NSUInteger)index hint: (id)hint
Removes the element at the given index from the collection, by making adjustments based on the hint if needed.
The element can be nil, but then the index must not be ETUndeterminedIndex. Otherwise the collection can raise an exception.
If the collection is not ordered, the index can be ignored, but otherwise it must not.
If the index is ETUndeterminedIndex, all occurences of the element must be removed from the collection.
If both the element and index are valid, the element should be ignored and priority must be given to the index to locate the objects to remove (this rule is subject to change a bit).
If the hint is not nil, the collection can test the hint type. If the hint matches its expectation, it's up to the collection to choose another index and/or another element to remove. Both the custom index and element can be provided by the hint.
The collection must continue to behave in a predictable way (as detailed above) when no hint is provided.
If the hint can provide both a custom element and index, as stated previously, priority must be given to the index to locate the objects to remove.
- - (void) insertObjects: (NSArray *)objects atIndexes: (NSIndexSet *)indexes hints: (NSArray *)hints
- Description forthcoming.
