UICollectionViewLayout Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 6.0 and later.
Declared in
UICollectionViewLayout.h

Overview

The UICollectionViewLayout class is an abstract base class that you subclass and use to generate layout information for a collection view. The job of a layout object is to determine the placement of cells, supplementary views, and decoration views inside the collection view’s bounds and to report that information to the collection view when asked. The collection view then applies the provided layout information to the corresponding views so that they can be presented onscreen.

You must subclass UICollectionViewLayout in order to use it. Before you consider subclassing, though, you should look at the UICollectionViewFlowLayout class to see if it can be adapted to your layout needs.

Subclassing Notes

The main job of a layout object is to provide information about the position and visual state of items in the collection view. The layout object does not create the views for which it provides the layout. Those views are created by the collection view’s data source. Instead, the layout object defines the position and size of visual elements based on the design of the layout.

Collection views have three types of visual elements that need to be laid out:

The collection view asks its layout object to provide layout information for these elements at many different times. Every cell and view that appears on screen is positioned using information from the layout object. Similarly, every time items are inserted into or deleted from the collection view, additional layout occurs for the items being added or removed. However, the collection view always limits layout to the objects that are visible onscreen.

Methods to Override

Every layout object should implement the following methods:

These methods provide the fundamental layout information that the collection view needs to place contents on the screen. Of course, if your layout does not support supplementary or decoration views, do not implement the corresponding methods.

When the data in the collection view changes and items are to be inserted or deleted, the collection view asks its layout object to update the layout information. Specifically, any item that is moved, added, or deleted must have its layout information updated to reflect its new location. For moved items, the collection view uses the standard methods to retrieve the item’s updated layout attributes. For items being inserted or deleted, the collection view calls some different methods, which you should override to provide the appropriate layout information:

In addition to these methods, you can also override the prepareForCollectionViewUpdates: to handle any layout-related preparation. You can also override the finalizeCollectionViewUpdates method and use it to add animations to the overall animation block or to implement any final layout-related tasks.

Optimizing Layout Performance Using Invalidation Contexts

When designing your custom layouts, you can improve performance by invalidating only those parts of your layout that actually changed. When you change items, calling the invalidateLayout method forces the collection view to recompute all of its layout information and reapply it. A better solution is to recompute only the layout information that changed, which is exactly what invalidation contexts allow you to do. An invalidation context lets you specify which parts of the layout changed. The layout object can then use that information to minimize the amount of data it recomputes.

To define a custom invalidation context for your layout, subclass the UICollectionViewLayoutInvalidationContext class. In your subclass, define custom properties that represent the parts of your layout data that can be recomputed independently. When you need to invalidate your layout at runtime, create an instance of your invalidation context subclass, configure the custom properties based on what layout information changed, and pass that object to your layout’s invalidateLayoutWithContext: method. Your custom implementation of that method can use the information in the invalidation context to recompute only the portions of your layout that changed.

If you define a custom invalidation context class for your layout object, you should also override the invalidationContextClass method and return your custom class. The collection view always creates an instance of the class you specify when it needs an invalidation context. Returning your custom subclass from this method ensures that your layout object always has the invalidation context it expects.

Tasks

Getting the Collection View Information

Providing Layout Attributes

Responding to Collection View Updates

Invalidating the Layout

Coordinating Animated Changes

Transitioning Between Layouts

Registering Decoration Views

Properties

collectionView

The collection view object currently using this layout object. (read-only)

@property (nonatomic, readonly) UICollectionView *collectionView
Discussion

The collection view object sets the value of this property when a new layout object is assigned to it.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

Class Methods

invalidationContextClass

Returns the class to use when creating an invalidation context for the layout.

+ (Class)invalidationContextClass
Discussion

If you subclass UICollectionViewLayout and use a custom invalidation context object to improve the performance of your layout updates, override this method and return your UICollectionViewLayoutInvalidationContext subclass. When the collection view needs to invalidate your layout, it uses the class you provide to create an appropriate invalidation context object.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

layoutAttributesClass

Returns the class to use when creating layout attributes objects.

+ (Class)layoutAttributesClass
Return Value

The class to use for layout attributes objects.

Discussion

If you subclass UICollectionViewLayoutAttributes in order to manage additional layout attributes, you should override this method and return your custom subclass. The methods for creating layout attributes use this class when creating new layout attributes objects.

This method is intended for subclassers only and does not need to be called by your code.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

Instance Methods

collectionViewContentSize

Returns the width and height of the collection view’s contents.

- (CGSize)collectionViewContentSize
Return Value

The width and height of the collection view’s contents.

Discussion

Subclasses must override this method and use it to return the width and height of the collection view’s content. These values represent the width and height of all the content, not just the content that is currently visible. The collection view uses this information to configure its own content size for scrolling purposes.

The default implementation of this method returns CGSizeZero.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

finalizeAnimatedBoundsChange

Cleans up after any animated changes to the view’s bounds or after the insertion or deletion of items.

- (void)finalizeAnimatedBoundsChange
Discussion

The collection view calls this method after creating the animations for changing the view’s bounds or after the animated insertion or deletion of items. This method is the layout object’s opportunity to do any cleanup related to those operations.

You can also use this method to perform additional animations. Any animations you create are added to the animation block used to handle the insertions, deletions, and bounds changes.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

finalizeCollectionViewUpdates

Performs any additional animations or clean up needed during a collection view update.

- (void)finalizeCollectionViewUpdates
Discussion

The collection view calls this method as the last step before preceding to animate any changes into place. This method is called within the animation block used to perform all of the insertion, deletion, and move animations so you can create additional animations using this method as needed. Otherwise, you can use it to perform any last minute tasks associated with managing your layout object’s state information.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

finalizeLayoutTransition

Tells the layout object to perform any final steps before the transition animations occur.

- (void)finalizeLayoutTransition
Discussion

The collection view calls this method after it has gathered all of the layout attributes needed to perform a transition from one layout to another. You can use this method to clean up any data structures or caches created by your implementations of the prepareForTransitionFromLayout: or prepareForTransitionToLayout: methods.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

finalLayoutAttributesForDisappearingDecorationElementOfKind:atIndexPath:

Returns the final layout information for a decoration view that is about to be removed from the collection view.

- (UICollectionViewLayoutAttributes *)finalLayoutAttributesForDisappearingDecorationElementOfKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)elementIndexPath
Parameters
elementKind

A string that identifies the type of decoration view.

elementIndexPath

The index path of the view being deleted.

Return Value

A layout attributes object that describes the position of the decoration view to use as the end point for animating its removal.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any decoration views that are about to be deleted. Your implementation should return the layout information that describes the final position and state of the view. The collection view uses this information as the end point for any animations. (The starting point of the animation is the view’s current location.) If you return nil, the layout object uses the same attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

finalLayoutAttributesForDisappearingItemAtIndexPath:

Returns the final layout information for an item that is about to be removed from the collection view.

- (UICollectionViewLayoutAttributes *)finalLayoutAttributesForDisappearingItemAtIndexPath:(NSIndexPath *)itemIndexPath
Parameters
itemIndexPath

The index path of the item being deleted.

Return Value

A layout attributes object that describes the position of the cell to use as the end point for animating its removal.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any items that are about to be deleted. Your implementation should return the layout information that describes the final position and state of the item. The collection view uses this information as the end point for any animations. (The starting point of the animation is the item’s current location.) If you return nil, the layout object uses the same attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

finalLayoutAttributesForDisappearingSupplementaryElementOfKind:atIndexPath:

Returns the final layout information for a supplementary view that is about to be removed from the collection view.

- (UICollectionViewLayoutAttributes *)finalLayoutAttributesForDisappearingSupplementaryElementOfKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)elementIndexPath
Parameters
elementKind

A string that identifies the type of supplementary view.

elementIndexPath

The index path of the view being deleted.

Return Value

A layout attributes object that describes the position of the supplementary view to use as the end point for animating its removal.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any supplementary views that are about to be deleted. Your implementation should return the layout information that describes the final position and state of the view. The collection view uses this information as the end point for any animations. (The starting point of the animation is the view’s current location.) If you return nil, the layout object uses the same attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

indexPathsToDeleteForDecorationViewOfKind:

Returns an array of index paths representing the decoration views to remove.

- (NSArray *)indexPathsToDeleteForDecorationViewOfKind:(NSString *)kind
Parameters
kind

The specific type of decoration view.

Return Value

An array of NSIndexPath objects indicating the decoration views you want to remove or an empty array if you do not want to remove any views of the given kind.

Discussion

The collection view calls this method whenever you delete cells or sections to the collection view. Implementing this method gives your layout object an opportunity to remove any decoration views that are no longer needed.

The collection view calls this method between its calls to prepareForCollectionViewUpdates: and finalizeCollectionViewUpdates.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

indexPathsToDeleteForSupplementaryViewOfKind:

Returns an array of index paths representing the supplementary views to remove.

- (NSArray *)indexPathsToDeleteForSupplementaryViewOfKind:(NSString *)kind
Parameters
kind

The specific type of supplementary view.

Return Value

An array of NSIndexPath objects indicating the supplementary views you want to remove or an empty array if you do not want to remove any views of the given kind.

Discussion

The collection view calls this method whenever you delete cells or sections to the collection view. Implementing this method gives your layout object an opportunity to remove any supplementary views that are no longer needed.

The collection view calls this method between its calls to prepareForCollectionViewUpdates: and finalizeCollectionViewUpdates.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

indexPathsToInsertForDecorationViewOfKind:

Returns an array of index paths representing the decoration views to add.

- (NSArray *)indexPathsToInsertForDecorationViewOfKind:(NSString *)kind
Parameters
kind

The specific type of decoration view.

Return Value

An array of NSIndexPath objects indicating the location of the new decoration views or an empty array if you do not want to add any decoration views.

Discussion

The collection view calls this method whenever you add cells or sections to the collection view. Implementing this method gives your layout object an opportunity to add new decoration views to complement the additions.

The collection view calls this method between its calls to prepareForCollectionViewUpdates: and finalizeCollectionViewUpdates.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

indexPathsToInsertForSupplementaryViewOfKind:

Returns an array of index paths for the supplementary views you want to add to the layout.

- (NSArray *)indexPathsToInsertForSupplementaryViewOfKind:(NSString *)kind
Parameters
kind

The specific type of supplementary view.

Return Value

An array of NSIndexPath objects indicating the location of the new supplementary views or an empty array if you do not want to add any supplementary views.

Discussion

The collection view calls this method whenever you add cells or sections to the collection view. Implementing this method gives your layout object an opportunity to add new supplementary views to complement the additions.

The collection view calls this method between its calls to prepareForCollectionViewUpdates: and finalizeCollectionViewUpdates.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

initialLayoutAttributesForAppearingDecorationElementOfKind:atIndexPath:

Returns the starting layout information for a decoration view being inserted into the collection view.

- (UICollectionViewLayoutAttributes *)initialLayoutAttributesForAppearingDecorationElementOfKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)elementIndexPath
Parameters
elementKind

A string that identifies the type of decoration view.

elementIndexPath

The index path of the item being inserted.

Return Value

A layout attributes object that describes the position at which to place the corresponding decoration view.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any decoration views that are about to be inserted. Your implementation should return the layout information that describes the initial position and state of the view. The collection view uses this information as the starting point for any animations. (The end point of the animation is the view’s new location in the collection view.) If you return nil, the layout object uses the item’s final attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

initialLayoutAttributesForAppearingItemAtIndexPath:

Returns the starting layout information for an item being inserted into the collection view.

- (UICollectionViewLayoutAttributes *)initialLayoutAttributesForAppearingItemAtIndexPath:(NSIndexPath *)itemIndexPath
Parameters
itemIndexPath

The index path of the item being inserted. You can use this path to locate the item in the collection view’s data source.

Return Value

A layout attributes object that describes the position at which to place the corresponding cell.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any items that are about to be inserted. Your implementation should return the layout information that describes the initial position and state of the item. The collection view uses this information as the starting point for any animations. (The end point of the animation is the item’s new location in the collection view.) If you return nil, the layout object uses the item’s final attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

initialLayoutAttributesForAppearingSupplementaryElementOfKind:atIndexPath:

Returns the starting layout information for a supplementary view being inserted into the collection view.

- (UICollectionViewLayoutAttributes *)initialLayoutAttributesForAppearingSupplementaryElementOfKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)elementIndexPath
Parameters
elementKind

A string that identifies the type of supplementary view.

elementIndexPath

The index path of the item being inserted.

Return Value

A layout attributes object that describes the position at which to place the corresponding supplementary view.

Discussion

This method is called after the prepareForCollectionViewUpdates: method and before the finalizeCollectionViewUpdates method for any supplementary views that are about to be inserted. Your implementation should return the layout information that describes the initial position and state of the view. The collection view uses this information as the starting point for any animations. (The end point of the animation is the view’s new location in the collection view.) If you return nil, the layout object uses the item’s final attributes for both the start and end points of the animation.

The default implementation of this method returns nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

invalidateLayout

Invalidates the current layout and triggers a layout update.

- (void)invalidateLayout
Discussion

You can call this method at any time to update the layout information. This method invalidates the layout of the collection view itself and returns right away. Thus, you can call this method multiple times from the same block of code without triggering multiple layout updates. The actual layout update occurs during the next view layout update cycle.

If you override this method, you must call super at some point in your implementation.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

invalidateLayoutWithContext:

Invalidates the current layout using the information in the provided context object.

- (void)invalidateLayoutWithContext:(UICollectionViewLayoutInvalidationContext *)context
Parameters
context

The context object indicating which parts of the layout to refresh.

Discussion

The default implementation of this method optimizes the layout process using the base properties of the UICollectionViewLayoutInvalidationContext class. If you define a custom context object for your layout, override this method and apply any custom properties of the context object to your layout computations.

If you override this method, you must call super at some point in your implementation.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

invalidationContextForBoundsChange:

Returns a context object that defines the portions of the layout that should change when a bounds change occurs.

- (UICollectionViewLayoutInvalidationContext *)invalidationContextForBoundsChange:(CGRect)newBounds
Parameters
newBounds

The new bounds for the collection view.

Return Value

An invalidation context that describes the changes that need to be made.

Discussion

The default implementation of this method creates an instance of the class provided by the invalidationContextClass class method and returns it. If you want to use a custom invalidation context object with your layout, always override that method and return your custom class.

You can override this method if you want to create and configure your custom invalidation context in response to a bounds change. If you override this method, you must call super first to get the invalidation context object to return. After getting this object, set any custom properties and return it.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

layoutAttributesForDecorationViewOfKind:atIndexPath:

Returns the layout attributes for the specified decoration view.

- (UICollectionViewLayoutAttributes *)layoutAttributesForDecorationViewOfKind:(NSString*)decorationViewKind atIndexPath:(NSIndexPath *)indexPath
Parameters
decorationViewKind

A string that identifies the type of the decoration view.

indexPath

The index path of the decoration view.

Return Value

A layout attributes object containing the information to apply to the decoration view.

Discussion

If your layout object defines any decoration views, you must override this method and use it to return layout information for those views.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

layoutAttributesForElementsInRect:

Returns the layout attributes for all of the cells and views in the specified rectangle.

- (NSArray *)layoutAttributesForElementsInRect:(CGRect)rect
Parameters
rect

The rectangle (specified in the collection view’s coordinate system) containing the target views.

Return Value

An array of UICollectionViewLayoutAttributes objects representing the layout information for the cells and views. The default implementation returns nil.

Discussion

Subclasses must override this method and use it to return layout information for all items whose view intersects the specified rectangle. Your implementation should return attributes for all visual elements, including cells, supplementary views, and decoration views.

When creating the layout attributes, always create an attributes object that represents the correct element type (cell, supplementary, or decoration). The collection view differentiates between attributes for each type and uses that information to make decisions about which views to create and how to manage them.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

layoutAttributesForItemAtIndexPath:

Returns the layout attributes for the item at the specified index path.

- (UICollectionViewLayoutAttributes *)layoutAttributesForItemAtIndexPath:(NSIndexPath *)indexPath
Parameters
indexPath

The index path of the item.

Return Value

A layout attributes object containing the information to apply to the item’s cell.

Discussion

Subclasses must override this method and use it to return layout information for items in the collection view. You use this method to provide layout information only for items that have a corresponding cell. Do not use it for supplementary views or decoration views.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

layoutAttributesForSupplementaryViewOfKind:atIndexPath:

Returns the layout attributes for the specified supplementary view.

- (UICollectionViewLayoutAttributes *)layoutAttributesForSupplementaryViewOfKind:(NSString *)kind atIndexPath:(NSIndexPath *)indexPath
Parameters
kind

A string that identifies the type of the supplementary view.

indexPath

The index path of the view.

Return Value

A layout attributes object containing the information to apply to the supplementary view.

Discussion

If your layout object defines any supplementary views, you must override this method and use it to return layout information for those views.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

prepareForAnimatedBoundsChange:

Prepares the layout object for animated changes to the view’s bounds or the insertion or deletion of items.

- (void)prepareForAnimatedBoundsChange:(CGRect)oldBounds
Parameters
oldBounds

The current bounds of the collection view.

Discussion

The collection view calls this method before performing any animated changes to the view’s bounds or before the animated insertion or deletion of items. This method is the layout object’s opportunity to perform any calculations needed to prepare for those animated changes. Specifically, you might use this method to calculate the initial or final positions of inserted or deleted items so that you can return those values when asked for them.

You can also use this method to perform additional animations. Any animations you create are added to the animation block used to handle the insertions, deletions, and bounds changes.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

prepareForCollectionViewUpdates:

Notifies the layout object that the contents of the collection view are about to change.

- (void)prepareForCollectionViewUpdates:(NSArray *)updateItems
Parameters
updateItems

An array of UICollectionViewUpdateItem objects that identify the changes being made.

Discussion

When items are inserted or deleted, the collection view notifies its layout object so that it can adjust the layout as needed. The first step in that process is to call this method to let the layout object know what changes to expect. After that, additional calls are made to gather layout information for inserted, deleted, and moved items that are going to be animated around the collection view.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

prepareForTransitionFromLayout:

Tells the layout object to prepare to be installed as the layout for the collection view.

- (void)prepareForTransitionFromLayout:(UICollectionViewLayout*)oldLayout
Parameters
oldLayout

The layout object installed in the collection view at the beginning of the transition. You might use this object to provide different ending attributes based on the starting layout object.

Discussion

Prior to performing a layout transition, the collection view calls this method so that your layout object can perform any initial calculations needed to generate layout attributes.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

prepareForTransitionToLayout:

Tells the layout object that it is about to be removed as the layout for the collection view.

- (void)prepareForTransitionToLayout:(UICollectionViewLayout*)newLayout
Parameters
newLayout

The layout object to be installed in the collection view at the end of the transition. You might use this object to provide different starting attributes depending on the final layout object.

Discussion

Prior to performing a layout transition, the collection view calls this method so that your layout object can perform any initial calculations needed to generate layout attributes.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

prepareLayout

Tells the layout object to update the current layout.

- (void)prepareLayout
Discussion

Layout updates occur the first time the collection view presents its content and whenever the layout is invalidated explicitly or implicitly because of a change to the view. During each layout update, the collection view calls this method first to give your layout object a chance to prepare for the upcoming layout operation.

The default implementation of this method does nothing. Subclasses can override it and use it to set up data structures or perform any initial computations needed to perform the layout later.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

registerClass:forDecorationViewOfKind:

Registers a class for use in creating decoration views for a collection view.

- (void)registerClass:(Class)viewClass forDecorationViewOfKind:(NSString *)decorationViewKind
Parameters
viewClass

The class to use for the supplementary view.

decorationViewKind

The element kind of the decoration view. You can use this string to distinguish between decoration views with different purposes in the layout. This parameter must not be nil and must not be an empty string.

Discussion

This method gives the layout object a chance to register a decoration view for use in the collection view. Decoration views provide visual adornments to a section or to the entire collection view but are not otherwise tied to the data provided by the collection view’s data source.

You do not need to create decoration views explicitly. After registering one, it is up to the layout object to decide when a decoration view is needed and return the corresponding layout attributes from its layoutAttributesForElementsInRect: method. For layout attributes that specify a decoration view, the collection view creates (or reuses) a view and displays it automatically based on the registered information.

If you previously registered a class or nib file with the same kind string, the class you specify in the viewClass parameter replaces the old entry. You may specify nil for viewClass if you want to unregister the decoration view.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

registerNib:forDecorationViewOfKind:

Registers a nib file for use in creating decoration views for a collection view.

- (void)registerNib:(UINib *)nib forDecorationViewOfKind:(NSString *)decorationViewKind
Parameters
nib

The nib object containing the cell definition. The nib file must contain only one top-level object and that object must be of the type UICollectionReusableView.

decorationViewKind

The element kind of the decoration view. You can use this string to distinguish between decoration views with different purposes in the layout. This parameter must not be nil and must not be an empty string.

Discussion

This method gives the layout object a chance to register a decoration view for use in the collection view. Decoration views provide visual adornments to a section or to the entire collection view but are not otherwise tied to the data provided by the collection view’s data source.

You do not need to create decoration views explicitly. After registering one, it is up to the layout object to decide when a decoration view is needed and return the corresponding layout attributes from its layoutAttributesForElementsInRect: method. For layout attributes that specify a decoration view, the collection view creates (or reuses) a view and displays it automatically based on the registered information.

If you previously registered a class or nib file with the same kind string, the class you specify in the viewClass parameter replaces the old entry. You may specify nil for viewClass if you want to unregister the decoration view.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

shouldInvalidateLayoutForBoundsChange:

Asks the layout object if the new bounds require a layout update.

- (BOOL)shouldInvalidateLayoutForBoundsChange:(CGRect)newBounds
Parameters
newBounds

The new bounds of the collection view.

Return Value

YES if the collection view requires a layout update or NO if the layout does not need to change.

Discussion

The default implementation of this method returns NO. Subclasses can override it and return an appropriate value based on whether changes in the bounds of the collection view require changes to the layout of cells and supplementary views.

If the bounds of the collection view change and this method returns YES, the collection view invalidates the layout by calling the invalidateLayoutWithContext: method.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h

targetContentOffsetForProposedContentOffset:

Returns the content offset to use after an animated layout update or change.

- (CGPoint)targetContentOffsetForProposedContentOffset:(CGPoint)proposedContentOffset
Parameters
proposedContentOffset

The proposed point (in the coordinate space of the collection view’s content view) for the upper-left corner of the visible content. This represents the point that the collection view has calculated as the most likely value to use at the end of the animation.

Return Value

The content offset that you want to use instead. The default implementation of this method returns the value in the proposedContentOffset parameter.

Discussion

During layout updates, or when transitioning between layouts, the collection view calls this method to give you the opportunity to change the proposed content offset to use at the end of the animation. You might override this method if the animations or transition might cause items to be positioned in a way that is not optimal for your design.

The collection view calls this method after calling the prepareLayout and collectionViewContentSize methods.

Availability
  • Available in iOS 7.0 and later.
Declared In
UICollectionViewLayout.h

targetContentOffsetForProposedContentOffset:withScrollingVelocity:

Returns the point at which to stop scrolling.

- (CGPoint)targetContentOffsetForProposedContentOffset:(CGPoint)proposedContentOffset withScrollingVelocity:(CGPoint)velocity
Parameters
proposedContentOffset

The proposed point (in the collection view’s content view) at which to stop scrolling. This is the value at which scrolling would naturally stop if no adjustments were made. The point reflects the upper-left corner of the visible content.

velocity

The current scrolling velocity along both the horizontal and vertical axes. This value is measured in points per second.

Return Value

The content offset that you want to use instead. This value reflects the adjusted upper-left corner of the visible area. The default implementation of this method returns the value in the proposedContentOffset parameter.

Discussion

If you want the scrolling behavior to snap to specific boundaries, you can override this method and use it to change the point at which to stop. For example, you might use this method to always stop scrolling on a boundary between items, as opposed to stopping in the middle of an item.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.h