Documentation

ETCollection

ETCollection <NSObject>

Unified protocol to interact with collections.

AuthorsGenerated by qmathe
Declared inETCollection.h

Overview

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.

Given most protocol method implementations remains the same accross collection classes, we provide ETCollectionTrait as a reusable ETCollection implementation.

The two primitives methods are -content and -contentArray . These methods must be implemented in the collection class in all cases. See ETCollectionTrait.

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.

Default

- (BOOL) isOrdered

Returns whether the receiveir stores the elements in a sorted order or not.

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

      - (BOOL) isEmpty

      Returns YES when the collection contains no elements, otherwise returns NO.

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

            - (NSUInteger) count

            Returns the number of elements hold by the receiver.

              - (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) containsObject: (id)anObject

                  Returns whether the element is included in the collection.

                    - (BOOL) containsCollection: (id <ETCollection>)objects

                    Returns whether every element in the given collection are included in the receiver.

                      - (NSArray *) viewpointArray

                      Returns the collection represented as viewpoints on the collection elements.