iOS Developer Library

Developer

UIKit Framework Reference UICollectionViewLayout Class Reference

Options
Deployment Target:

On This Page
Language:

UICollectionViewLayout

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 6.0 and later.

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:

  • Cells are the main elements positioned by the layout. Each cell represents a single data item in the collection. A collection view can have a single group of cells or it can divide those cells into multiple sections. The layout object’s main job is to arrange the cells in the collection view’s content area.

  • Supplementary views present data but are different than cells. Unlike cells, supplementary views cannot be selected by the user. Instead, you use supplementary views to implement things like header and footer views for a given section or for the entire collection view. Supplementary views are optional and their use and placement is defined by the layout object.

  • Decoration views are visual adornments that cannot be selected and are not inherently tied to the data of the collection view. Decoration views are another type of supplementary view. Like supplementary views, they are optional and their use and placement is defined by the layout object.

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.

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

    Declaration

    Swift

    var collectionView: UICollectionView? { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func collectionViewContentSize() -> CGSize

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Returns the class to use when creating layout attributes objects.

    Declaration

    Swift

    class func layoutAttributesClass() -> AnyClass

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the layout object to update the current layout.

    Declaration

    Swift

    func prepareLayout()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func layoutAttributesForElementsInRect(_ rect: CGRect) -> [AnyObject]?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func layoutAttributesForItemAtIndexPath(_ indexPath: NSIndexPath) -> UICollectionViewLayoutAttributes!

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Returns the layout attributes for the specified supplementary view.

    Declaration

    Swift

    func layoutAttributesForSupplementaryViewOfKind(_ kind: String, atIndexPath indexPath: NSIndexPath) -> UICollectionViewLayoutAttributes!

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Returns the layout attributes for the specified decoration view.

    Declaration

    Swift

    func layoutAttributesForDecorationViewOfKind(_ decorationViewKind: String, atIndexPath indexPath: NSIndexPath) -> UICollectionViewLayoutAttributes!

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func targetContentOffsetForProposedContentOffset(_ proposedContentOffset: CGPoint) -> CGPoint

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Returns the point at which to stop scrolling.

    Declaration

    Swift

    func targetContentOffsetForProposedContentOffset(_ proposedContentOffset: CGPoint, withScrollingVelocity velocity: CGPoint) -> CGPoint

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func prepareForCollectionViewUpdates(_ updateItems: [AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func finalizeCollectionViewUpdates()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func indexPathsToInsertForSupplementaryViewOfKind(_ kind: String) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func indexPathsToInsertForDecorationViewOfKind(_ kind: String) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func initialLayoutAttributesForAppearingItemAtIndexPath(_ itemIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func initialLayoutAttributesForAppearingSupplementaryElementOfKind(_ elementKind: String, atIndexPath elementIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func initialLayoutAttributesForAppearingDecorationElementOfKind(_ elementKind: String, atIndexPath elementIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func indexPathsToDeleteForSupplementaryViewOfKind(_ kind: String) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func indexPathsToDeleteForDecorationViewOfKind(_ kind: String) -> [AnyObject]

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func finalLayoutAttributesForDisappearingItemAtIndexPath(_ itemIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func finalLayoutAttributesForDisappearingSupplementaryElementOfKind(_ elementKind: String, atIndexPath elementIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func finalLayoutAttributesForDisappearingDecorationElementOfKind(_ elementKind: String, atIndexPath elementIndexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Invalidates the current layout and triggers a layout update.

    Declaration

    Swift

    func invalidateLayout()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func invalidateLayoutWithContext(_ context: UICollectionViewLayoutInvalidationContext)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    class func invalidationContextClass() -> AnyClass

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func shouldInvalidateLayoutForBoundsChange(_ newBounds: CGRect) -> Bool

    Objective-C

    - (BOOL)shouldInvalidateLayoutForBoundsChange:(CGRect)newBounds

    Parameters

    newBounds

    The new bounds of the collection view.

    Return Value

    YEStrue if the collection view requires a layout update or NOfalse if the layout does not need to change.

    Discussion

    The default implementation of this method returns NOfalse. 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 YEStrue, the collection view invalidates the layout by calling the invalidateLayoutWithContext: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func invalidationContextForBoundsChange(_ newBounds: CGRect) -> UICollectionViewLayoutInvalidationContext

    Objective-C

    - (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. Do not return nil.

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Asks the layout object if changes to a self-sizing cell require a layout update.

    Declaration

    Swift

    func shouldInvalidateLayoutForPreferredLayoutAttributes(_ preferredAttributes: UICollectionViewLayoutAttributes, withOriginalAttributes originalAttributes: UICollectionViewLayoutAttributes) -> Bool

    Objective-C

    - (BOOL)shouldInvalidateLayoutForPreferredLayoutAttributes:(UICollectionViewLayoutAttributes *)preferredAttributes withOriginalAttributes:(UICollectionViewLayoutAttributes *)originalAttributes

    Parameters

    preferredAttributes

    The layout attributes returned by the cell’s preferredLayoutAttributesFittingAttributes: method.

    originalAttributes

    The attributes that the layout object originally suggested for the cell.

    Return Value

    YEStrue if the layout should be invalidated or NOfalse if it should not.

    Discussion

    When a collection view includes self-sizing cells, the cells are given the opportunity to modify their own layout attributes before those attributes are applied. A self-sizing cell might do this to specify a different cell size than the one the layout object provides. When the cell provides a different set of attributes, the collection view calls this method to determine if the cell’s change requires a larger layout refresh.

    If you are implementing a custom layout, you can override this method and use it to determine if your layout should be invalidated based on the specified attributes. The default implementation of this method returns NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Returns a context object that defines the portions of the layout that should change in response to dynamic cell changes.

    Declaration

    Swift

    func invalidationContextForPreferredLayoutAttributes(_ preferredAttributes: UICollectionViewLayoutAttributes, withOriginalAttributes originalAttributes: UICollectionViewLayoutAttributes) -> UICollectionViewLayoutInvalidationContext

    Objective-C

    - (UICollectionViewLayoutInvalidationContext *)invalidationContextForPreferredLayoutAttributes:(UICollectionViewLayoutAttributes *)preferredAttributes withOriginalAttributes:(UICollectionViewLayoutAttributes *)originalAttributes

    Parameters

    preferredAttributes

    The layout attributes returned by the cell’s preferredLayoutAttributesFittingAttributes: method.

    originalAttributes

    The attributes that the layout object originally suggested for the cell.

    Return Value

    An invalidation context that includes information about what changes need to be made to the layout.

    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.

    Subclasses can override this method and use it to configure the invalidation context before returning it. In your custom implementation, call super to get the invalidation context object, configure that object, and return it.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    func prepareForAnimatedBoundsChange(_ oldBounds: CGRect)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func finalizeAnimatedBoundsChange()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func prepareForTransitionFromLayout(_ oldLayout: UICollectionViewLayout)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func prepareForTransitionToLayout(_ newLayout: UICollectionViewLayout!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func finalizeLayoutTransition()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func registerClass(_ viewClass: AnyClass?, forDecorationViewOfKind decorationViewKind: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func registerNib(_ nib: UINib?, forDecorationViewOfKind decorationViewKind: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.