/* Copyright (c) 2014-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 #import #import #import #import @class ASCellNode; @protocol ASCollectionViewDataSource; @protocol ASCollectionViewDelegate; /** * Node-based collection view. * * ASCollectionView is a version of UICollectionView that uses nodes -- specifically, ASCellNode subclasses -- with asynchronous * pre-rendering instead of synchronously loading UICollectionViewCells. */ @interface ASCollectionView : UICollectionView @property (nonatomic, weak) id asyncDataSource; @property (nonatomic, weak) id asyncDelegate; // must not be nil /** * Tuning parameters for a range type. * * @param rangeType The range type to get the tuning parameters for. * * @returns A tuning parameter value for the given range type. * * Defaults to the render range having one sceenful both leading and trailing and the preload range having two * screenfuls in both directions. */ - (ASRangeTuningParameters)tuningParametersForRangeType:(ASLayoutRangeType)rangeType; /** * Set the tuning parameters for a range type. * * @param tuningParameters The tuning parameters to store for a range type. * @param rangeType The range type to set the tuning parameters for. */ - (void)setTuningParameters:(ASRangeTuningParameters)tuningParameters forRangeType:(ASLayoutRangeType)rangeType; /** * Initializer. * * @param frame The frame rectangle for the collection view, measured in points. The origin of the frame is relative to the superview * in which you plan to add it. This frame is passed to the superclass during initialization. * * @param layout The layout object to use for organizing items. The collection view stores a strong reference to the specified object. * Must not be nil. * * @param asyncDataFetchingEnabled Enable the data fetching in async mode. * * @discussion If asyncDataFetching is enabled, the `AScollectionView` will fetch data through `collectionView:numberOfRowsInSection:` and * `collectionView:nodeForRowAtIndexPath:` in async mode from background thread. Otherwise, the methods will be invoked synchronically * from calling thread. * Enabling asyncDataFetching could avoid blocking main thread for `ASCellNode` allocation, which is frequently reported issue for * large scale data. On another hand, the application code need take the responsibility to avoid data inconsistence. Specifically, * we will lock the data source through `collectionViewLockDataSource`, and unlock it by `collectionViewUnlockDataSource` after the data fetching. * The application should not update the data source while the data source is locked, to keep data consistence. */ - (instancetype)initWithFrame:(CGRect)frame collectionViewLayout:(UICollectionViewLayout *)layout asyncDataFetching:(BOOL)asyncDataFetchingEnabled; /** * The number of screens left to scroll before the delegate -collectionView:beginBatchFetchingWithContext: is called. * * Defaults to one screenful. */ @property (nonatomic, assign) CGFloat leadingScreensForBatching; /** * Perform a batch of updates asynchronously, optionally disabling all animations in the batch. This method must be called from the main thread. * The asyncDataSource must be updated to reflect the changes before the update block completes. * * @param animated NO to disable animations for this batch * @param updates The block that performs the relevant insert, delete, reload, or move operations. * @param completion A completion handler block to execute when all of the operations are finished. This block takes a single * Boolean parameter that contains the value YES if all of the related animations completed successfully or * NO if they were interrupted. This parameter may be nil. If supplied, the block is run on the main thread. */ - (void)performBatchAnimated:(BOOL)animated updates:(void (^)())updates completion:(void (^)(BOOL))completion; /** * Perform a batch of updates asynchronously. This method must be called from the main thread. * The asyncDataSource must be updated to reflect the changes before update block completes. * * @param updates The block that performs the relevant insert, delete, reload, or move operations. * @param completion A completion handler block to execute when all of the operations are finished. This block takes a single * Boolean parameter that contains the value YES if all of the related animations completed successfully or * NO if they were interrupted. This parameter may be nil. If supplied, the block is run on the main thread. */ - (void)performBatchUpdates:(void (^)())updates completion:(void (^)(BOOL))completion; /** * Reload everything from scratch, destroying the working range and all cached nodes. * * @param completion block to run on completion of asynchronous loading or nil. If supplied, the block is run on * the main thread. * @warning This method is substantially more expensive than UICollectionView's version. */ - (void)reloadDataWithCompletion:(void (^)())completion; /** * Reload everything from scratch, destroying the working range and all cached nodes. * * @warning This method is substantially more expensive than UICollectionView's version. */ - (void)reloadData; /** * Inserts one or more sections. * * @param sections An index set that specifies the sections to insert. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)insertSections:(NSIndexSet *)sections; /** * Deletes one or more sections. * * @param sections An index set that specifies the sections to delete. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)deleteSections:(NSIndexSet *)sections; /** * Reloads the specified sections. * * @param sections An index set that specifies the sections to reload. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)reloadSections:(NSIndexSet *)sections; /** * Moves a section to a new location. * * @param section The index of the section to move. * * @param newSection The index that is the destination of the move for the section. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection; /** * Inserts items at the locations identified by an array of index paths. * * @param indexPaths An array of NSIndexPath objects, each representing an item index and section index that together identify an item. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)insertItemsAtIndexPaths:(NSArray *)indexPaths; /** * Deletes the items specified by an array of index paths. * * @param indexPaths An array of NSIndexPath objects identifying the items to delete. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)deleteItemsAtIndexPaths:(NSArray *)indexPaths; /** * Reloads the specified items. * * @param indexPaths An array of NSIndexPath objects identifying the items to reload. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)reloadItemsAtIndexPaths:(NSArray *)indexPaths; /** * Moves the item at a specified location to a destination location. * * @param indexPath The index path identifying the item to move. * * @param newIndexPath The index path that is the destination of the move for the item. * * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes * before this method is called. */ - (void)moveItemAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath; /** * Similar to -cellForItemAtIndexPath:. * * @param indexPath The index path of the requested node. * * @returns a node for display at this indexpath. */ - (ASCellNode *)nodeForItemAtIndexPath:(NSIndexPath *)indexPath; /** * Similar to -visibleCells. * * @returns an array containing the nodes being displayed on screen. */ - (NSArray *)visibleNodes; /** * Query the sized node at `indexPath` for its calculatedSize. * * @param indexPath The index path for the node of interest. */ - (CGSize)calculatedSizeForNodeAtIndexPath:(NSIndexPath *)indexPath; /** * Determines collection view's current scroll direction. Supports 2-axis collection views. * * @returns a bitmask of ASScrollDirection values. */ - (ASScrollDirection)scrollDirection; /** * Determines collection view's scrollable directions. * * @returns a bitmask of ASScrollDirection values. */ - (ASScrollDirection)scrollableDirections; @end /** * This is a node-based UICollectionViewDataSource. */ @protocol ASCollectionViewDataSource /** * Similar to -collectionView:cellForItemAtIndexPath:. * * @param collectionView The sender. * * @param indexPath The index path of the requested node. * * @returns a node for display at this indexpath. Must be thread-safe (can be called on the main thread or a background * queue) and should not implement reuse (it will be called once per row). Unlike UICollectionView's version, this method * is not called when the row is about to display. */ - (ASCellNode *)collectionView:(ASCollectionView *)collectionView nodeForItemAtIndexPath:(NSIndexPath *)indexPath; @optional /** * Provides the constrained size range for measuring the node at the index path. * * @param collectionView The sender. * * @param indexPath The index path of the node. * * @returns A constrained size range for layout the node at this index path. */ - (ASSizeRange)collectionView:(ASCollectionView *)collectionView constrainedSizeForNodeAtIndexPath:(NSIndexPath *)indexPath; /** * Indicator to lock the data source for data fetching in async mode. * We should not update the data source until the data source has been unlocked. Otherwise, it will incur data inconsistence or exception * due to the data access in async mode. * * @param collectionView The sender. */ - (void)collectionViewLockDataSource:(ASCollectionView *)collectionView; /** * Indicator to unlock the data source for data fetching in async mode. * We should not update the data source until the data source has been unlocked. Otherwise, it will incur data inconsistence or exception * due to the data access in async mode. * * @param collectionView The sender. */ - (void)collectionViewUnlockDataSource:(ASCollectionView *)collectionView; @end /** * This is a node-based UICollectionViewDelegate. */ @protocol ASCollectionViewDelegate @optional - (void)collectionView:(ASCollectionView *)collectionView willDisplayNodeForItemAtIndexPath:(NSIndexPath *)indexPath; - (void)collectionView:(ASCollectionView *)collectionView didEndDisplayingNodeForItemAtIndexPath:(NSIndexPath*)indexPath; /** * Receive a message that the collectionView is near the end of its data set and more data should be fetched if * necessary. * * @param collectionView The sender. * @param context A context object that must be notified when the batch fetch is completed. * * @discussion You must eventually call -completeBatchFetching: with an argument of YES in order to receive future * notifications to do batch fetches. This method is called on a background queue. * * UICollectionView currently only supports batch events for tail loads. If you require a head load, consider * implementing a UIRefreshControl. */ - (void)collectionView:(ASCollectionView *)collectionView willBeginBatchFetchWithContext:(ASBatchContext *)context; /** * Tell the collectionView if batch fetching should begin. * * @param collectionView The sender. * * @discussion Use this method to conditionally fetch batches. Example use cases are: limiting the total number of * objects that can be fetched or no network connection. * * If not implemented, the collectionView assumes that it should notify its asyncDelegate when batch fetching * should occur. */ - (BOOL)shouldBatchFetchForCollectionView:(ASCollectionView *)collectionView; /** * Passthrough support to UICollectionViewDelegateFlowLayout sectionInset behavior. * * @param collectionView The sender. * @param collectionViewLayout The layout object requesting the information. * #param section The index number of the section whose insets are needed. * * @discussion The same rules apply as the UICollectionView implementation, but this can also be used without a UICollectionViewFlowLayout. * https://developer.apple.com/library/ios/documentation/UIKit/Reference/UICollectionViewDelegateFlowLayout_protocol/index.html#//apple_ref/occ/intfm/UICollectionViewDelegateFlowLayout/collectionView:layout:insetForSectionAtIndex: * */ - (UIEdgeInsets)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout insetForSectionAtIndex:(NSInteger)section; @end @interface ASCollectionView (Deprecated) @property (nonatomic, assign) ASRangeTuningParameters rangeTuningParameters ASDISPLAYNODE_DEPRECATED; @end