This document provides a comprehensive overview of creating a custom waterfall layout for UICollectionView in iOS. It details the structure of UICollectionView, the importance of UICollectionViewLayout and its related classes, and various functionalities such as drag-and-drop and autoscroll. The document also includes practical code snippets and layout design considerations to implement an effective and dynamic layout experience in iOS applications.

1. Collection view custom
layout
Waterfall layout case study
iOS Practice Leaders
Anatoly Tukhtarov

2. Introduction
UICollectionView is available since iOS 6
Allows present collections of data with custom
layout
Still in development

3. Agenda
• UICollectionView and its views
• UICollectionViewLayout and its friends
• Waterfall collection view layout

4. UICollectionView views
Managed by collection view’s data source (i.e. represent
some data)
• Cells — UICollectionViewCell
• Supplementary views (section’s or collection view’s headers, footers, etc.) —
UICollectionReusableView
Managed by collection view’s layout
• Decoration views (items separators, shadows, borders, etc.) —
UICollectionReusableView
Only cells are selectable

5. How does collection view
know how to place its
views?
UICollectionViewLayout

6. UICollectionViewLayout
A kind of data source to provide visual information,
not data
Responsible for locations and sizes of all the cells,
supplementary and decoration views
Does not apply data to views

7. UICollectionViewLayout
Classes
UICollectionViewLayoutAttributes
• view’s layout attributes like frame, alpha,
transform, etc.
• created and configured by layout
• must adopt NSCopying protocol
• must override equality methods
(-hash, -isEqual:)
• applied by collection view

8. UICollectionViewLayout
Classes
UICollectionViewLayoutInvalidationContext
• available since iOS 7
• declares which parts of layout need to be updated
on layout invalidation
• capital update for iOS 8

9. Waterfall layout
Documents list application

10. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1
Source code: https://github.com/swordfishyou/documents-app

11. Designing layout
• Number of columns in section
• Column width
• Cell size
• Cell frame
• Intercolumn and interline
spacings, etc.
• Cache all the possible values
layout delegate
data source
layout

12. Building layout
- (void)buildLayout {
if (self.isPreparingLayout) {
return;
}
self.preparingLayout = YES;
/// Calculate items sizes and columns metrics
if (!self.isLayoutDataValid) {
[self buildLayoutFromDataSource];
self.layoutDataValid = YES;
}
self.layoutSize = CGSizeZero;
[self.layoutAttributes removeAllObjects];
/// Calculate (reuse) layout attributes
[self calculateLayoutAttributes];
self.preparingLayout = NO;
}

13. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1

14. Cell size (self-sizing cells)
- (CGSize)collectionView:(UICollectionView *)collectionView
sizeFittingSize:(CGSize)fittingSize
forItemAtIndexPath:(NSIndexPath *)indexPath {
FLSCollectionViewCell *cell = [self collectionView:collectionView
cellForItemAtIndexPath:indexPath];
CGRect frame = cell.frame;
frame.size = fittingSize;
cell.frame = frame;
CGSize size;
[cell layoutIfNeeded];
size = [cell.contentView
systemLayoutSizeFittingSize:UILayoutFittingCompressedSize];
[cell removeFromSuperview];
return size;
}
Auto layouts case

15. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1

16. Layout metrics
• Items’ sizes and attributes by index path
• Column metrics by section
• index
• section
• size
• items’ indexes in column

17. Cell frame
- (CGRect)itemFrameAtIndexPath:(NSIndexPath *)indexPath {
CGRect frame;
frame.size = ...; /// use cached value
CGFloat topOffset = 0.0;
for (NSInteger section = 0; section < indexPath.section; ++section) {
/// Shift vertically by sections above
}
NSInteger numberOfColumnsInSection = ...;
NSInteger itemColumn = indexPath.item % numberOfColumnsInSection;
FLSColumnLayoutMetrics *columnMetrics = ...;
for (NSInteger item = 0; item < indexPath.item; ++item) {
if ([columnMetrics.itemIndexes containsIndex:item]) {
/// Shift vertically by items in column
}
}
frame.origin.y = topOffset;
CGFloat leftOffset = itemColumn * self.minimumItercolumnSpacing;
for (NSInteger column = 0; column < itemColumn; ++column) {
/// Shift horizontally by columns left
}
/// Centre cell in item’s column
return frame;
}

18. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1

19. Layout invalidation
@interface FLSCollectionViewLayoutInvalidationContext :
UICollectionViewLayoutInvalidationContext
@property (nonatomic, assign) BOOL invalidateLayoutMetrics;
@end
+ (Class)invalidationContextClass;
- (BOOL)shouldInvalidateLayoutForBoundsChange:(CGRect)newBounds;
- (UICollectionViewLayoutInvalidationContext *)
invalidationContextForBoundsChange:(CGRect)newBounds;
- (void)invalidateLayoutWithContext:
(FLSCollectionViewLayoutInvalidationContext *)context;

20. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1

21. Drag and drop
• Consider to use gestures controller or state
machine
• Layout is responsible for changing frame of a
dragging item
• Data source is responsible for handling motion
actions (like reorder array, etc.)
General ideas

22. Drag and drop
- (void)beginDraggingItemAtIndexPath:(NSIndexPath *)indexPath {
/// Snapshot cell and index path
self.draggingIndexPath = indexPath;
UICollectionViewCell *cell = ...;
UIView *snapshot = [cell snapshotViewAfterScreenUpdates:NO];
self.draggingView = snapshot;
[self.collectionView addSubview:self.draggingView];
/// Calculate drag bounds if needed
[UIView animateWithDuration:animationDuration
animations:^{
/// Indicate dragging item with animation
} completion:^(BOOL finished) {
/// Invalidate layout
}];
}
Begin dragging

23. Drag and drop
- (void)handlePanGesture:(UIPanGestureRecognizer *)gesture {
switch (gesture.state) {
case UIGestureRecognizerStateChanged:{
[self scheduleDraggingHoldTimer];
/// Calculate new centre of the dragging view
CGPoint translation = [gesture translationInView:self.collectionView];
CGPoint diff = ...;
self.lastTranslation = translation;
CGPoint center = ...;
[self constrainPointToDragBounds:&center];
self.draggingView.center = center;
/// Trigger autoscroll
break;
}
case UIGestureRecognizerStateEnded:
/// Invalidate timers
break;
}
}
Handle pan gesture

24. Drag and drop
- (void)handleDraggindHold:(NSTimer *)timer {
FLSDataSource *dataSource = self.collectionView.dataSource;
NSIndexPath *newIndexPath = [self.collectionView
indexPathForItemAtPoint:self.draggingView.center];
if (newIndexPath != nil &&
![newIndexPath isEqual:self.draggingIndexPath]) {
BOOL canMove = ...; /// Use data source
if (canMove) {
self.draggingIndexPath = newIndexPath;
[dataSource collectionView:self.collectionView
moveItemAtIndexPath:self.lastSourceIndexPath
toIndexPath:newIndexPath isHeld:YES];
self.lastSourceIndexPath = newIndexPath;
/// Invalidate layout
}
}
}
Handle hold

25. Documents application
• Landscape and portrait items A4 scale
• Multiple waterfall columns for iPad and iPhone
• Number of columns must be changed on device
rotation
• Drag and drop items like on home screen
• Autoscroll while dragging
v 0.1

26. Autoscroll
• Consider to use CADisplayLink instead of
NSTimer
• Invalidate dragging hold timer while autoscrolling
• Calculate autoscroll direction and velocity while
dragging
• Calculate dragging view’s frame and collection
view’s contentOffset

27. Autoscroll
CGRect autoscrollFrame = UIEdgeInsetsInsetRect(self.collectionView.bounds,
self.autoscrollTriggerInsets);
CGPoint location = [gesture locationInView:self.collectionView];
CGFloat top = CGRectGetMinY(autoscrollFrame);
CGFloat bottom = CGRectGetMaxY(autoscrollFrame);
if (location.y < top) {
self.autosctollVelocity = 10 * (top - location.y);
[self scheduleAutoscrollTimerWithDirection:FLSAutoscrollDirectionUp];
} else if (location.y > bottom) {
self.autosctollVelocity = 10 * (location.y - bottom);
[self scheduleAutoscrollTimerWithDirection:FLSAutoscrollDirectionDown];
} else {
[self invalidateAutoscrollTimer];
}
Trigger autoscroll

28. Autoscroll
CGFloat distance = rintf(self.autosctollVelocity / 60.0);
switch (self.autoscrollDirection) {
/// Visually stop autoscroll if bottom of the content was
reached
case FLSAutoscrollDirectionDown: {
break;
}
/// Visually stop autoscroll if top of the content was reached
default:
break;
}
CGPoint translation = CGPointMake(0, distance);
CGPoint newCenter = ...;
[self constrainPointToDragBounds:&newCenter];
self.draggingView.center = newCenter;
self.collectionView.contentOffset = ...;
Handle autoscroll

29. Recap
• Cache all the possible values: calculate once and
reuse
• Auto layout is your friend
• Invalidate layout rationally
• Measure, measure and… measure

30. More information
WWDC 2014 — Session 232
Advanced User Interfaces with Collection View
Source code: https://developer.apple.com/wwdc/resources/sample-code/
WWDC 2014 — Session 226
What's New in Table and Collection Views
Collection View Programming Guide for iOS
Creating Custom Layout
Yalantis
Excel Page Layout for Collection View
http://yalantis.com/blog/data-grid-with-freeze-columns-play-by-your-rules/
WWDC 2012 — Session 219
Advanced Collection Views and Building Custom Layout
7th iOS Practice Leaders
Introduction to Auto Layout
Presentation