IGListCollectionContext

@protocol IGListCollectionContext <NSObject>

The collection context provides limited access to the collection-related information that section controllers need for operations like sizing, dequeuing cells, inserting, deleting, reloading, etc.

  • The size of the collection view. You can use this for sizing cells.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CGSize containerSize;

    Swift

    var containerSize: CGSize { get }
  • The content insets of the collection view. You can use this for sizing cells.

    Declaration

    Objective-C

    @property (readonly, nonatomic) UIEdgeInsets containerInset;

    Swift

    var containerInset: UIEdgeInsets { get }
  • The adjusted content insets of the collection view. Equivalent to containerInset under iOS 11.

    Declaration

    Objective-C

    @property (readonly, nonatomic) UIEdgeInsets adjustedContainerInset;

    Swift

    var adjustedContainerInset: UIEdgeInsets { get }
  • The size of the collection view with content insets applied.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CGSize insetContainerSize;

    Swift

    var insetContainerSize: CGSize { get }
  • The current scrolling traits of the underlying collection view.

    Declaration

    Objective-C

    @property (readonly, nonatomic) IGListCollectionScrollingTraits scrollingTraits;

    Swift

    var scrollingTraits: IGListCollectionScrollingTraits { get }
  • A bitmask of experiments to conduct on the section controller.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) IGListExperiment experiments;

    Swift

    var experiments: IGListExperiment { get set }
  • Returns size of the collection view relative to the section controller.

    Declaration

    Objective-C

    - (CGSize)containerSizeForSectionController:
        (nonnull IGListSectionController *)sectionController;

    Swift

    func containerSize(for sectionController: IGListSectionController) -> CGSize

    Parameters

    sectionController

    The section controller requesting this information.

    Return Value

    The size of the collection view minus the given section controller’s insets.

  • Returns the index of the specified cell in the collection relative to the section controller.

    Declaration

    Objective-C

    - (NSInteger)indexForCell:(nonnull UICollectionViewCell *)cell
            sectionController:(nonnull IGListSectionController *)sectionController;

    Swift

    func index(for cell: UICollectionViewCell, sectionController: IGListSectionController) -> Int

    Parameters

    cell

    An existing cell in the collection.

    sectionController

    The section controller requesting this information.

    Return Value

    The index of the cell or NSNotFound if it does not exist in the collection.

  • Returns the cell in the collection at the specified index for the section controller.

    Warning

    This method may return nil if the cell is offscreen.

    Declaration

    Objective-C

    - (nullable __kindof UICollectionViewCell *)
        cellForItemAtIndex:(NSInteger)index
         sectionController:(nonnull IGListSectionController *)sectionController;

    Swift

    func cellForItem(at index: Int, sectionController: IGListSectionController) -> UICollectionViewCell?

    Parameters

    index

    The index of the desired cell.

    sectionController

    The section controller requesting this information.

    Return Value

    The collection view cell, or nil if not found.

  • Returns the visible cells for the given section controller.

    Declaration

    Objective-C

    - (nonnull NSArray<UICollectionViewCell *> *)visibleCellsForSectionController:
        (nonnull IGListSectionController *)sectionController;

    Swift

    func visibleCells(for sectionController: IGListSectionController) -> [UICollectionViewCell]

    Parameters

    sectionController

    The section controller requesting this information.

    Return Value

    An array of visible cells, or an empty array if none are found.

  • Returns the visible paths for the given section controller.

    Declaration

    Objective-C

    - (nonnull NSArray<NSIndexPath *> *)visibleIndexPathsForSectionController:
        (nonnull IGListSectionController *)sectionController;

    Swift

    func visibleIndexPaths(for sectionController: IGListSectionController) -> [IndexPath]

    Parameters

    sectionController

    The section controller requesting this information.

    Return Value

    An array of visible index paths, or an empty array if none are found.

  • Deselects a cell in the collection.

    Declaration

    Objective-C

    - (void)deselectItemAtIndex:(NSInteger)index
              sectionController:(nonnull IGListSectionController *)sectionController
                       animated:(BOOL)animated;

    Swift

    func deselectItem(at index: Int, sectionController: IGListSectionController, animated: Bool)

    Parameters

    index

    The index of the item to deselect.

    sectionController

    The section controller requesting this information.

    animated

    Pass YES to animate the change, NO otherwise.

  • Selects a cell in the collection.

    Declaration

    Objective-C

    - (void)selectItemAtIndex:(NSInteger)index
            sectionController:(nonnull IGListSectionController *)sectionController
                     animated:(BOOL)animated
               scrollPosition:(UICollectionViewScrollPosition)scrollPosition;

    Swift

    func selectItem(at index: Int, sectionController: IGListSectionController, animated: Bool, scrollPosition: UICollectionView.ScrollPosition)

    Parameters

    index

    The index of the item to select.

    sectionController

    The section controller requesting this information.

    animated

    Pass YES to animate the change, NO otherwise.

    scrollPosition

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

  • Dequeues a cell from the collection view reuse pool.

    Note

    This method uses a string representation of the cell class as the identifier.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionViewCell *)
        dequeueReusableCellOfClass:(nonnull Class)cellClass
               withReuseIdentifier:(nullable NSString *)reuseIdentifier
              forSectionController:
                  (nonnull IGListSectionController *)sectionController
                           atIndex:(NSInteger)index;

    Swift

    func dequeueReusableCell(of cellClass: AnyClass, withReuseIdentifier reuseIdentifier: String?, for sectionController: IGListSectionController, at index: Int) -> UICollectionViewCell

    Parameters

    cellClass

    The class of the cell you want to dequeue.

    reuseIdentifier

    A reuse identifier for the specified cell. This parameter may be nil.

    sectionController

    The section controller requesting this information.

    index

    The index of the cell.

    Return Value

    A cell dequeued from the reuse pool or a newly created one.

  • Dequeues a cell from the collection view reuse pool.

    Note

    This method uses a string representation of the cell class as the identifier.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionViewCell *)
        dequeueReusableCellOfClass:(nonnull Class)cellClass
              forSectionController:
                  (nonnull IGListSectionController *)sectionController
                           atIndex:(NSInteger)index;

    Swift

    func dequeueReusableCell(of cellClass: AnyClass, for sectionController: IGListSectionController, at index: Int) -> UICollectionViewCell

    Parameters

    cellClass

    The class of the cell you want to dequeue.

    sectionController

    The section controller requesting this information.

    index

    The index of the cell.

    Return Value

    A cell dequeued from the reuse pool or a newly created one.

  • Dequeues a cell from the collection view reuse pool.

    Note

    This method uses a string representation of the cell class as the identifier.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionViewCell *)
        dequeueReusableCellWithNibName:(nonnull NSString *)nibName
                                bundle:(nullable NSBundle *)bundle
                  forSectionController:
                      (nonnull IGListSectionController *)sectionController
                               atIndex:(NSInteger)index;

    Swift

    func dequeueReusableCell(withNibName nibName: String, bundle: Bundle?, for sectionController: IGListSectionController, at index: Int) -> UICollectionViewCell

    Parameters

    nibName

    The name of the nib file.

    bundle

    The bundle in which to search for the nib file. If nil, this method searches the main bundle.

    sectionController

    The section controller requesting this information.

    index

    The index of the cell.

    Return Value

    A cell dequeued from the reuse pool or a newly created one.

  • Dequeues a storyboard prototype cell from the collection view reuse pool.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionViewCell *)
        dequeueReusableCellFromStoryboardWithIdentifier:
            (nonnull NSString *)identifier
                                   forSectionController:
                                       (nonnull IGListSectionController *)
                                           sectionController
                                                atIndex:(NSInteger)index;

    Swift

    func dequeueReusableCellFromStoryboard(withIdentifier identifier: String, for sectionController: IGListSectionController, at index: Int) -> UICollectionViewCell

    Parameters

    identifier

    The identifier of the cell prototype in storyboard.

    sectionController

    The section controller requesting this information.

    index

    The index of the cell.

    Return Value

    A cell dequeued from the reuse pool or a newly created one.

  • Dequeues a supplementary view from the collection view reuse pool.

    Note

    This method uses a string representation of the view class as the identifier.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionReusableView *)
        dequeueReusableSupplementaryViewOfKind:(nonnull NSString *)elementKind
                          forSectionController:
                              (nonnull IGListSectionController *)sectionController
                                         class:(nonnull Class)viewClass
                                       atIndex:(NSInteger)index;

    Swift

    func dequeueReusableSupplementaryView(ofKind elementKind: String, for sectionController: IGListSectionController, class viewClass: AnyClass, at index: Int) -> UICollectionReusableView

    Parameters

    elementKind

    The kind of supplementary view.

    sectionController

    The section controller requesting this information.

    viewClass

    The class of the supplementary view.

    index

    The index of the supplementary view.

    Return Value

    A supplementary view dequeued from the reuse pool or a newly created one.

  • Dequeues a supplementary view from the collection view reuse pool.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionReusableView *)
        dequeueReusableSupplementaryViewFromStoryboardOfKind:
            (nonnull NSString *)elementKind
                                              withIdentifier:
                                                  (nonnull NSString *)identifier
                                        forSectionController:
                                            (nonnull IGListSectionController *)
                                                sectionController
                                                     atIndex:(NSInteger)index;

    Swift

    func dequeueReusableSupplementaryView(fromStoryboardOfKind elementKind: String, withIdentifier identifier: String, for sectionController: IGListSectionController, at index: Int) -> UICollectionReusableView

    Parameters

    elementKind

    The kind of supplementary view.

    identifier

    The identifier of the supplementary view in storyboard.

    sectionController

    The section controller requesting this information.

    index

    The index of the supplementary view.

    Return Value

    A supplementary view dequeued from the reuse pool or a newly created one.

  • Dequeues a supplementary view from the collection view reuse pool.

    Note

    This method uses a string representation of the view class as the identifier.

    Declaration

    Objective-C

    - (nonnull __kindof UICollectionReusableView *)
        dequeueReusableSupplementaryViewOfKind:(nonnull NSString *)elementKind
                          forSectionController:
                              (nonnull IGListSectionController *)sectionController
                                       nibName:(nonnull NSString *)nibName
                                        bundle:(nullable NSBundle *)bundle
                                       atIndex:(NSInteger)index;

    Swift

    func dequeueReusableSupplementaryView(ofKind elementKind: String, for sectionController: IGListSectionController, nibName: String, bundle: Bundle?, at index: Int) -> UICollectionReusableView

    Parameters

    elementKind

    The kind of supplementary view.

    sectionController

    The section controller requesting this information.

    nibName

    The name of the nib file.

    bundle

    The bundle in which to search for the nib file. If nil, this method searches the main bundle.

    index

    The index of the supplementary view.

    Return Value

    A supplementary view dequeued from the reuse pool or a newly created one.

  • Invalidate the backing UICollectionViewLayout for all items in the section controller.

    Note

    This method can be wrapped in UIView animation APIs to control the duration or perform without animations. This will end up calling -[UICollectionView performBatchUpdates:completion:] internally, so invalidated changes may not be reflected in the cells immediately.

    Declaration

    Objective-C

    - (void)invalidateLayoutForSectionController:
                (nonnull IGListSectionController *)sectionController
                                      completion:
                                          (nullable void (^)(BOOL))completion;

    Swift

    func invalidateLayout(for sectionController: IGListSectionController, completion: ((Bool) -> Void)? = nil)

    Parameters

    sectionController

    The section controller that needs invalidating.

    completion

    An optional completion block to execute when the updates are finished.

  • Batches and performs many cell-level updates in a single transaction.

    Note

    You should make state changes that impact the number of items in your section controller within the updates block alongside changes on the context object.

    For example, inside your section controllers, you may want to delete and insert into the data source that backs your section controller. For example:

    [self.collectionContext performBatchItemUpdates:^ (id<IGListBatchContext> batchContext>){
      // perform data source changes inside the update block
      [self.items addObject:newItem];
      [self.items removeObjectAtIndex:0];
    
      NSIndexSet *inserts = [NSIndexSet indexSetWithIndex:[self.items count] - 1];
      [batchContext insertInSectionController:self atIndexes:inserts];
    
      NSIndexSet *deletes = [NSIndexSet indexSetWithIndex:0];
      [batchContext deleteInSectionController:self atIndexes:deletes];
    } completion:nil];
    

    Warning

    You must perform data modifications inside the update block. Updates will not be performed synchronously, so you should make sure that your data source changes only when necessary.

    Declaration

    Objective-C

    - (void)performBatchAnimated:(BOOL)animated
                         updates:(nonnull void (^)(id<IGListBatchContext> _Nonnull))
                                     updates
                      completion:(nullable void (^)(BOOL))completion;

    Swift

    func performBatch(animated: Bool, updates: @escaping (ListBatchContext) -> Void, completion: ((Bool) -> Void)? = nil)

    Parameters

    animated

    A flag indicating if the transition should be animated.

    updates

    A block with a context parameter to make mutations.

    completion

    An optional completion block to execute when the updates are finished.

  • Scrolls to the specified section controller in the list.

    Declaration

    Objective-C

    - (void)scrollToSectionController:
                (nonnull IGListSectionController *)sectionController
                              atIndex:(NSInteger)index
                       scrollPosition:(UICollectionViewScrollPosition)scrollPosition
                             animated:(BOOL)animated;

    Swift

    func scroll(to sectionController: IGListSectionController, at index: Int, scrollPosition: UICollectionView.ScrollPosition, animated: Bool)

    Parameters

    sectionController

    The section controller.

    index

    The index of the item in the section controller to which to scroll.

    scrollPosition

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

    animated

    A flag indicating if the scrolling should be animated.