IGListAdapter

Objective-C


@interface IGListAdapter : NSObject

Swift

class ListAdapter : NSObject

IGListAdapter objects provide an abstraction for feeds of objects in a UICollectionView by breaking each object into individual sections, called “section controllers”. These controllers (objects subclassing to IGListSectionController) act as a data source and delegate for each section.

Feed implementations must act as the data source for an IGListAdapter in order to drive the objects and section controllers in a collection view.

  • The view controller that houses the adapter.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) UIViewController *viewController;

    Swift

    weak var viewController: UIViewController? { get set }

  • The collection view used with the adapter.

    Note

    Setting this property will automatically set isPrefetchingEnabled to NO for performance reasons.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) UICollectionView *collectionView;

    Swift

    weak var collectionView: UICollectionView? { get set }

  • The object that acts as the data source for the adapter.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IGListAdapterDataSource> dataSource;

    Swift

    weak var dataSource: (any ListAdapterDataSource)? { get set }

  • The object that receives top-level events for section controllers.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IGListAdapterDelegate> delegate;

    Swift

    weak var delegate: (any ListAdapterDelegate)? { get set }

  • The object that receives UICollectionViewDelegate events.

    Note

    This object will not receive UIScrollViewDelegate events. Instead use scrollViewDelegate.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<UICollectionViewDelegate> collectionViewDelegate;

    Swift

    weak var collectionViewDelegate: (any UICollectionViewDelegate)? { get set }

  • The object that receives UIScrollViewDelegate events.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<UIScrollViewDelegate> scrollViewDelegate;

    Swift

    weak var scrollViewDelegate: (any UIScrollViewDelegate)? { get set }

  • The object that receives IGListAdapterMoveDelegate events resulting from interactive reordering of sections.

    Note

    This works with UICollectionView interactive reordering available on iOS 9.0+

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IGListAdapterMoveDelegate> moveDelegate;

    Swift

    weak var moveDelegate: (any ListAdapterMoveDelegate)? { get set }

  • The object that receives IGListAdapterPerformanceDelegate events to measure performance.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IGListAdapterPerformanceDelegate> performanceDelegate;

    Swift

    weak var performanceDelegate: (any ListAdapterPerformanceDelegate)? { get set }

  • The updater for the adapter.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) id<IGListUpdatingDelegate> _Nonnull updater;

    Swift

    var updater: any IGListUpdatingDelegate { get }

  • A bitmask of experiments to conduct on the adapter.

    Declaration

    Objective-C

    @property (nonatomic) IGListExperiment experiments;

    Swift

    var experiments: IGListExperiment { get set }

  • Initializes a new IGListAdapter object.

    Note

    The working range is the number of objects beyond the visible objects (plus and minus) that should be notified when they are close to being visible. For instance, if you have 3 objects on screen and a working range of 2, the previous and succeeding 2 objects will be notified that they are within the working range. As you scroll the list the range is updated as objects enter and exit the working range.

    To opt out of using the working range, use initWithUpdater:viewController: or provide a working range of 0.

    Declaration

    Objective-C

    - (nonnull instancetype)
     initWithUpdater:(nonnull id<IGListUpdatingDelegate>)updater
      viewController:(nullable UIViewController *)viewController
    workingRangeSize:(NSInteger)workingRangeSize;

    Swift

    init(updater: any IGListUpdatingDelegate, viewController: UIViewController?, workingRangeSize: Int)

    Parameters

    updater

    An object that manages updates to the collection view.
    viewController

    The view controller that will house the adapter.
    workingRangeSize

    The number of objects before and after the viewport to consider within the working range.

    Return Value

    A new list adapter object.

  • Initializes a new IGListAdapter object with a working range of 0.

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithUpdater:(nonnull id<IGListUpdatingDelegate>)updater
     viewController:(nullable UIViewController *)viewController;

    Swift

    convenience init(updater: any IGListUpdatingDelegate, viewController: UIViewController?)

    Parameters

    updater

    An object that manages updates to the collection view.
    viewController

    The view controller that will house the adapter.

    Return Value

    A new list adapter object.

  • Perform an update from the previous state of the data source. This is analogous to calling -[UICollectionView performBatchUpdates:completion:].

    Declaration

    Objective-C

    - (void)performUpdatesAnimated:(BOOL)animated
                    completion:(nullable IGListUpdaterCompletion)completion;

    Swift

    func performUpdates(animated: Bool) async -> Bool

    Parameters

    animated

    A flag indicating if the transition should be animated.
    completion

    The block to execute when the updates complete.

  • Perform an immediate reload of the data in the data source, discarding the old objects.

    Warning

    Do not use this method to update without animations as it can be very expensive to teardown and rebuild all section controllers. Use -[IGListAdapter performUpdatesAnimated:completion] instead.

    Declaration

    Objective-C

    - (void)reloadDataWithCompletion:(nullable IGListUpdaterCompletion)completion;

    Swift

    func reloadData() async -> Bool

    Parameters

    completion

    The block to execute when the reload completes.

  • Reload the list for only the specified objects.

    Declaration

    Objective-C

    - (void)reloadObjects:(nonnull NSArray *)objects;

    Swift

    func reloadObjects(_ objects: [Any])

    Parameters

    objects

    The objects to reload.

  • Query the section controller at a given section index. Constant time lookup.

    Declaration

    Objective-C

    - (nullable IGListSectionController *)sectionControllerForSection:
    (NSInteger)section;

    Swift

    func sectionController(forSection section: Int) -> IGListSectionController?

    Parameters

    section

    A section in the list.

    Return Value

    A section controller or nil if the section does not exist.

  • Query the section index of a list. Constant time lookup.

    Declaration

    Objective-C

    - (NSInteger)sectionForSectionController:
    (nonnull IGListSectionController *)sectionController;

    Swift

    func section(for sectionController: IGListSectionController) -> Int

    Parameters

    sectionController

    A list object.

    Return Value

    The section index of the list if it exists, otherwise NSNotFound.

  • Returns the section controller for the specified object. Constant time lookup.

    See

    -[IGListAdapterDataSource listAdapter:sectionControllerForObject:]

    Declaration

    Objective-C

    - (__kindof IGListSectionController *_Nullable)sectionControllerForObject:
    (nonnull id)object;

    Swift

    func sectionController(for object: Any) -> IGListSectionController?

    Parameters

    object

    An object from the data source.

    Return Value

    A section controller or nil if object is not in the list.

  • Returns the object corresponding to the specified section controller in the list. Constant time lookup.

    Declaration

    Objective-C

    - (nullable id)objectForSectionController:
    (nonnull IGListSectionController *)sectionController;

    Swift

    func object(for sectionController: IGListSectionController) -> Any?

    Parameters

    sectionController

    A section controller in the list.

    Return Value

    The object for the specified section controller, or nil if not found.

  • Returns the object corresponding to a section in the list. Constant time lookup.

    Declaration

    Objective-C

    - (nullable id)objectAtSection:(NSInteger)section;

    Swift

    func object(atSection section: Int) -> Any?

    Parameters

    section

    A section in the list.

    Return Value

    The object for the specified section, or nil if the section does not exist.

  • Returns the section corresponding to the specified object in the list. Constant time lookup.

    Declaration

    Objective-C

    - (NSInteger)sectionForObject:(nonnull id)object;

    Swift

    func section(for object: Any) -> Int

    Parameters

    object

    An object in the list.

    Return Value

    The section index of object if found, otherwise NSNotFound.

  • Returns a copy of all the objects currently driving the adapter.

    Declaration

    Objective-C

    - (nonnull NSArray *)objects;

    Swift

    func objects() -> [Any]

    Return Value

    An array of objects.

  • An unordered array of the currently visible section controllers.

    Declaration

    Objective-C

    - (nonnull NSArray<IGListSectionController *> *)visibleSectionControllers;

    Swift

    func visibleSectionControllers() -> [IGListSectionController]

    Return Value

    An array of section controllers.

  • An unordered array of the currently visible objects.

    Declaration

    Objective-C

    - (nonnull NSArray *)visibleObjects;

    Swift

    func visibleObjects() -> [Any]

    Return Value

    An array of objects

  • An unordered array of the currently visible cells for a given object.

    Declaration

    Objective-C

    - (nonnull NSArray<UICollectionViewCell *> *)visibleCellsForObject:
    (nonnull id)object;

    Swift

    func visibleCells(for object: Any) -> [UICollectionViewCell]

    Parameters

    object

    An object in the list

    Return Value

    An array of collection view cells.

  • Scrolls to the specified object in the list adapter.

    Note

    The additional offset amount is to shift the final scroll position by some horizontal or vertical amount depending on the scroll direction. This is necessary when scrolling to an object on a view with sticky headers, since the sticky header would otherwise cover the top portion of the object.

    Declaration

    Objective-C

    - (void)scrollToObject:(nonnull id)object
    supplementaryKinds:(nullable NSArray<NSString *> *)supplementaryKinds
       scrollDirection:(UICollectionViewScrollDirection)scrollDirection
        scrollPosition:(UICollectionViewScrollPosition)scrollPosition
      additionalOffset:(CGFloat)additionalOffset
              animated:(BOOL)animated;

    Swift

    func scroll(to object: Any, supplementaryKinds: [String]?, scrollDirection: UICollectionView.ScrollDirection, scrollPosition: UICollectionView.ScrollPosition, additionalOffset: CGFloat, animated: Bool)

    Parameters

    object

    The object to which to scroll.
    supplementaryKinds

    The types of supplementary views in the section.
    scrollDirection

    An option indicating the direction to scroll.
    scrollPosition

    An option that specifies where the item should be positioned when scrolling finishes.
    additionalOffset

    Additional offset amount from the scroll position.
    animated

    A flag indicating if the scrolling should be animated.

  • Returns the index path for the first visible cell that has been scrolled to. This refers to the cell currently at the top/left (0, 0) of the collection view’s frame, inset by the collection view’s contentInset top or left value if defined.

    Declaration

    Objective-C

    - (nullable NSIndexPath *)indexPathForFirstVisibleItem;

    Swift

    func indexPathForFirstVisibleItem() -> IndexPath?

    Return Value

    The index path of the cell or nil if not found.

  • Gets the scroll offset of the first visible cell scrolled into in the collection view. This refers to the cell currently at the top/left (0, 0) of the collection view’s frame, inset by the collection view’s contentInset top or left value if defined.

    Declaration

    Objective-C

    - (CGFloat)offsetForFirstVisibleItemWithScrollDirection:
    (UICollectionViewScrollDirection)scrollDirection;

    Swift

    func offsetForFirstVisibleItem(with scrollDirection: UICollectionView.ScrollDirection) -> CGFloat

    Parameters

    scrollDirection

    An option indicating the direction to scroll.

    Return Value

    additionalOffset is the offset amount the first visible cell is shifted from the start of the cell, the amount it has been scrolled into in the coordinates of the cell’s bounds.

  • Returns the size of a cell at the specified index path.

    Declaration

    Objective-C

    - (CGSize)sizeForItemAtIndexPath:(nonnull NSIndexPath *)indexPath;

    Swift

    func sizeForItem(at indexPath: IndexPath) -> CGSize

    Parameters

    indexPath

    The index path of the cell. å

    Return Value

    The size of the cell.

  • Returns the size of a supplementary view in the list at the specified index path.

    Declaration

    Objective-C

    - (CGSize)sizeForSupplementaryViewOfKind:(nonnull NSString *)elementKind
                             atIndexPath:(nonnull NSIndexPath *)indexPath;

    Swift

    func sizeForSupplementaryView(ofKind elementKind: String, at indexPath: IndexPath) -> CGSize

    Parameters

    elementKind

    The kind of supplementary view.
    indexPath

    The index path of the supplementary view.

    Return Value

    The size of the supplementary view.

  • Adds a listener to the list adapter.

    Note

    Listeners are held weakly so there is no need to call -[IGListAdapter removeUpdateListener:] on dealloc.

    Declaration

    Objective-C

    - (void)addUpdateListener:
    (nonnull id<IGListAdapterUpdateListener>)updateListener;

    Swift

    func add(_ updateListener: any ListAdapterUpdateListener)

    Parameters

    updateListener

    The object conforming to the IGListAdapterUpdateListener protocol.

  • Removes a listener from the list adapter.

    Declaration

    Objective-C

    - (void)removeUpdateListener:
    (nonnull id<IGListAdapterUpdateListener>)updateListener;

    Swift

    func remove(_ updateListener: any ListAdapterUpdateListener)

    Parameters

    updateListener

    The object conforming to the IGListAdapterUpdateListener protocol.