mirror of
https://github.com/Instagram/IGListKit
synced 2026-05-14 21:08:48 +00:00
68a264d29c
Summary: This reverts commit 871b75eaeb1c9f2a40fe8f3fd81b209661704587 Differential Revision: D4640425 fbshipit-source-id: 4b0e8a9820891062cf7f8d13de13d678adb5df4a
262 lines
8.3 KiB
Objective-C
262 lines
8.3 KiB
Objective-C
/**
|
|
* Copyright (c) 2016-present, Facebook, Inc.
|
|
* All rights reserved.
|
|
*
|
|
* This source code is licensed under the BSD-style license found in the
|
|
* LICENSE file in the root directory of this source tree. An additional grant
|
|
* of patent rights can be found in the PATENTS file in the same directory.
|
|
*/
|
|
|
|
#import <UIKit/UIKit.h>
|
|
|
|
#import <IGListKit/IGListAdapterDataSource.h>
|
|
#import <IGListKit/IGListAdapterDelegate.h>
|
|
#import <IGListKit/IGListCollectionContext.h>
|
|
#import <IGListKit/IGListCollectionView.h>
|
|
#import <IGListKit/IGListExperiments.h>
|
|
#import <IGListKit/IGListSectionType.h>
|
|
#import <IGListKit/IGListMacros.h>
|
|
|
|
@protocol IGListUpdatingDelegate;
|
|
|
|
@class IGListSectionController;
|
|
|
|
NS_ASSUME_NONNULL_BEGIN
|
|
|
|
/**
|
|
A block to execute when list updates completes.
|
|
|
|
@param finished Specifies whether or not the updates finished.
|
|
*/
|
|
typedef void (^IGListUpdaterCompletion)(BOOL finished);
|
|
|
|
/**
|
|
`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 conforming to `IGListSectionType`) 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.
|
|
*/
|
|
IGLK_SUBCLASSING_RESTRICTED
|
|
@interface IGListAdapter : NSObject
|
|
|
|
/**
|
|
The view controller that houses the adapter.
|
|
*/
|
|
@property (nonatomic, nullable, weak) UIViewController *viewController;
|
|
|
|
/**
|
|
The collection view used with the adapter.
|
|
*/
|
|
@property (nonatomic, nullable, weak) IGListCollectionView *collectionView;
|
|
|
|
/**
|
|
The object that acts as the data source for the list adapter.
|
|
*/
|
|
@property (nonatomic, nullable, weak) id <IGListAdapterDataSource> dataSource;
|
|
|
|
/**
|
|
The object that receives top-level events for section controllers.
|
|
*/
|
|
@property (nonatomic, nullable, weak) id <IGListAdapterDelegate> delegate;
|
|
|
|
/**
|
|
The object that receives `UICollectionViewDelegate` events.
|
|
|
|
@note This object *will not* receive `UIScrollViewDelegate` events. Instead use scrollViewDelegate.
|
|
*/
|
|
@property (nonatomic, nullable, weak) id <UICollectionViewDelegate> collectionViewDelegate;
|
|
|
|
/**
|
|
The object that receives `UIScrollViewDelegate` events.
|
|
*/
|
|
@property (nonatomic, nullable, weak) id <UIScrollViewDelegate> scrollViewDelegate;
|
|
|
|
/**
|
|
The updater for this list adapter.
|
|
*/
|
|
@property (nonatomic, strong, readonly) id <IGListUpdatingDelegate> updater;
|
|
|
|
/**
|
|
A bitmask of experiments to conduct on the adapter.
|
|
*/
|
|
@property (nonatomic, assign) IGListExperiment experiments;
|
|
|
|
/**
|
|
Initializes a new `IGListAdapter` object.
|
|
|
|
@param updater An object that manages updates to the collection view.
|
|
@param viewController The view controller that will house the adapter.
|
|
@param workingRangeSize The number of objects before and after the viewport to consider within the working range.
|
|
|
|
@return A new list adapter 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, you can provide a value of `0`.
|
|
*/
|
|
- (instancetype)initWithUpdater:(id <IGListUpdatingDelegate>)updater
|
|
viewController:(nullable UIViewController *)viewController
|
|
workingRangeSize:(NSInteger)workingRangeSize NS_DESIGNATED_INITIALIZER;
|
|
|
|
/**
|
|
Perform an update from the previous state of the data source. This is analagous to calling
|
|
`-[UICollectionView performBatchUpdates:completion:]`.
|
|
|
|
@param animated A flag indicating if the transition should be animated.
|
|
@param completion The block to execute when the update completes.
|
|
*/
|
|
- (void)performUpdatesAnimated:(BOOL)animated completion:(nullable IGListUpdaterCompletion)completion;
|
|
|
|
/**
|
|
Perform an immediate reload of the data in the data source, discarding the old objects.
|
|
|
|
@param completion The block to execute when the reload completes.
|
|
*/
|
|
- (void)reloadDataWithCompletion:(nullable IGListUpdaterCompletion)completion;
|
|
|
|
/**
|
|
Reload the list for only the specified objects.
|
|
|
|
@param objects The objects to reload.
|
|
*/
|
|
- (void)reloadObjects:(NSArray *)objects;
|
|
|
|
/**
|
|
Query the section controller at a given section index. Constant time lookup.
|
|
|
|
@param section A section in the list.
|
|
|
|
@return An section controller or `nil` if the section does not exist.
|
|
*/
|
|
- (nullable IGListSectionController <IGListSectionType> *)sectionControllerForSection:(NSInteger)section;
|
|
|
|
/**
|
|
Query the section index of a list. Constant time lookup.
|
|
|
|
@param sectionController A list object.
|
|
|
|
@return The section index of the list if it exists, otherwise `NSNotFound`.
|
|
*/
|
|
- (NSInteger)sectionForSectionController:(IGListSectionController <IGListSectionType> *)sectionController;
|
|
|
|
/**
|
|
Returns the section controller for the specified object. Constant time lookup.
|
|
|
|
@param object An object from the data source.
|
|
|
|
@return An section controller or `nil` if `object` is not in the list.
|
|
|
|
@see `-[IGListAdapterDataSource listAdapter:sectionControllerForObject:]`
|
|
*/
|
|
- (__kindof IGListSectionController <IGListSectionType> * _Nullable)sectionControllerForObject:(id)object;
|
|
|
|
/**
|
|
Returns the object corresponding to the specified section controller in the list. Constant time lookup.
|
|
|
|
@param sectionController A section controller in the list.
|
|
|
|
@return The object for the specified section controller, or nil if not found.
|
|
*/
|
|
- (nullable id)objectForSectionController:(IGListSectionController <IGListSectionType> *)sectionController;
|
|
|
|
/**
|
|
Returns the object corresponding to a section in the list. Constant time lookup.
|
|
|
|
@param section A section in the list.
|
|
|
|
@return The object for the specified section, or `nil` if the section does not exist.
|
|
*/
|
|
- (nullable id)objectAtSection:(NSInteger)section;
|
|
|
|
/**
|
|
Returns the section corresponding to the specified object in the list. Constant time lookup.
|
|
|
|
@param object An object in the list.
|
|
|
|
@return The section index of `object` if found, otherwise `NSNotFound`.
|
|
*/
|
|
- (NSInteger)sectionForObject:(id)object;
|
|
|
|
/**
|
|
Returns a copy of all the objects currently powering the adapter.
|
|
|
|
@return An array of objects.
|
|
*/
|
|
- (NSArray *)objects;
|
|
|
|
/**
|
|
An unordered array of the currently visible section controllers.
|
|
|
|
@return An array of section controllers.
|
|
*/
|
|
- (NSArray<IGListSectionController<IGListSectionType> *> *)visibleSectionControllers;
|
|
|
|
/**
|
|
An unordered array of the currently visible objects.
|
|
|
|
@return An array of objects
|
|
*/
|
|
- (NSArray *)visibleObjects;
|
|
|
|
/**
|
|
An unordered array of the currently visible cells for a given object.
|
|
|
|
@param object An object in the list
|
|
|
|
@return An array of collection view cells.
|
|
*/
|
|
- (NSArray<UICollectionViewCell *> *)visibleCellsForObject:(id)object;
|
|
|
|
/**
|
|
Scrolls to the sepcified object in the list adapter.
|
|
|
|
@param object The object to which to scroll.
|
|
@param supplementaryKinds The types of supplementary views in the section.
|
|
@param scrollDirection An option indicating the direction to scroll.
|
|
@param scrollPosition An option that specifies where the item should be positioned when scrolling finishes.
|
|
@param animated A flag indicating if the scrolling should be animated.
|
|
*/
|
|
- (void)scrollToObject:(id)object
|
|
supplementaryKinds:(nullable NSArray<NSString *> *)supplementaryKinds
|
|
scrollDirection:(UICollectionViewScrollDirection)scrollDirection
|
|
scrollPosition:(UICollectionViewScrollPosition)scrollPosition
|
|
animated:(BOOL)animated;
|
|
|
|
/**
|
|
Returns the size of a cell at the specified index path.
|
|
|
|
@param indexPath The index path of the cell.
|
|
|
|
@return The size of the cell.
|
|
*/
|
|
- (CGSize)sizeForItemAtIndexPath:(NSIndexPath *)indexPath;
|
|
|
|
/**
|
|
Returns the size of a supplementary view in the list at the specified index path.
|
|
|
|
@param elementKind The kind of supplementary view.
|
|
@param indexPath The index path of the supplementary view.
|
|
|
|
@return The size of the supplementary view.
|
|
*/
|
|
- (CGSize)sizeForSupplementaryViewOfKind:(NSString *)elementKind
|
|
atIndexPath:(NSIndexPath *)indexPath;
|
|
|
|
/**
|
|
:nodoc:
|
|
*/
|
|
- (instancetype)init NS_UNAVAILABLE;
|
|
|
|
/**
|
|
:nodoc:
|
|
*/
|
|
+ (instancetype)new NS_UNAVAILABLE;
|
|
|
|
@end
|
|
|
|
NS_ASSUME_NONNULL_END
|