Basic collection protocol that all collections must support. EtoileFoundation extends Foundation classes such as NSArray, NSDictionary, NSSet and NSIndexSet to adopt this protocol. EtoileUI extends NSView in the same way.
With this protocol, the collection content can be accessed and queried in various ways but cannot be mutated.
When you write a new class that includes a to-many relationship, it should conform to ETCollection. If several to-many relationships exist, you should pick the dominant relationship that best represents the main content. A good hint is to pick the most recurrent way to browse the content with a UI, and the relationship traversed in such a case.
EtoileUI can automatically present collection-like content and support navigation into it when represented objects bound to ETLayoutItemGroup conform to ETCollection.
Note: In future, we will provide a viewpoint mechanism to view or traverse objects through their non-dominant to-many relationships.
- - (BOOL) isKeyed
Returns whether the receiveir stores the elements by key.
If the receivers returns YES, it must implement -arrayRepresentation .
-arrayRepresentation must return the content as a key-value pair array.
- - (id) content
Returns the underlying data structure object holding the content or self when the protocol is adopted by a class which is a content data structure by itself (like NSArray, NSDictionary, NSSet etc.).
Content by its very nature is always a collection of other objects. As such, content may hold one or no objects (empty collection).
When adopted, this method must never return nil.
- - (NSArray *) contentArray
Returns the content as a new NSArray-based collection of objects.
When adopted, this method must never return nil, you should generally return an empty NSArray instead.
- - (NSEnumerator *) objectEnumerator
Returns an enumerator which can be used as a conveniency to iterate over the elements of the content one-by-one.
- - (NSUInteger) countByEnumeratingWithState: (NSFastEnumerationState *)state objects: (id*)objects count: (NSUInteger)count
Returns a C array through objects which can be used to iterate over the content in several quick passes until 0 is returned.
Each time the method is called, the C array contains a new content portion to be iterated over.
The method returns the number of objects in the C array.
The count argument must be used to indicate the maximum number of objects allowed in the C array to be returned.
See NSFastEnumeration protocol.
- - (BOOL) containsCollection: (id <ETCollection>)objects
Returns whether every element in the given collection are included in the receiver.