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:
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:
layoutAttributesForSupplementaryViewOfKind:atIndexPath:(if your layout supports supplementary views)layoutAttributesForDecorationViewOfKind:atIndexPath:(if your layout supports decoration views)
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:
initialLayoutAttributesForAppearingSupplementaryElementOfKind:atIndexPath:initialLayoutAttributesForAppearingDecorationElementOfKind:atIndexPath:finalLayoutAttributesForDisappearingSupplementaryElementOfKind:atIndexPath:finalLayoutAttributesForDisappearingDecorationElementOfKind:atIndexPath:
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.
Tasks
Getting the Collection View Information
Providing Layout Attributes
-
+ layoutAttributesClass -
– prepareLayout -
– layoutAttributesForElementsInRect: -
– layoutAttributesForItemAtIndexPath: -
– layoutAttributesForSupplementaryViewOfKind:atIndexPath: -
– layoutAttributesForDecorationViewOfKind:atIndexPath: -
– targetContentOffsetForProposedContentOffset:withScrollingVelocity:
Responding to Collection View Updates
-
– prepareForCollectionViewUpdates: -
– finalizeCollectionViewUpdates -
– initialLayoutAttributesForAppearingItemAtIndexPath: -
– initialLayoutAttributesForAppearingSupplementaryElementOfKind:atIndexPath: -
– initialLayoutAttributesForAppearingDecorationElementOfKind:atIndexPath: -
– finalLayoutAttributesForDisappearingItemAtIndexPath: -
– finalLayoutAttributesForDisappearingSupplementaryElementOfKind:atIndexPath: -
– finalLayoutAttributesForDisappearingDecorationElementOfKind:atIndexPath:
Invalidating the Layout
Coordinating Animated Changes
Registering Decoration Views
Properties
collectionView
The collection view object currently using this layout object. (read-only)
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.hClass Methods
layoutAttributesClass
Returns the class to use when creating layout attributes objects.
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.
See Also
Declared In
UICollectionViewLayout.hInstance Methods
collectionViewContentSize
Returns the width and height of the collection view’s contents.
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.hfinalizeAnimatedBoundsChange
Cleans up after any animated changes to the view’s bounds or after the insertion or deletion of items.
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.hfinalizeCollectionViewUpdates
Performs any additional animations or clean up needed during a collection view update.
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.hfinalLayoutAttributesForDisappearingDecorationElementOfKind:atIndexPath:
Returns the final layout information for a decoration view that is about to be removed from the collection view.
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.hfinalLayoutAttributesForDisappearingItemAtIndexPath:
Returns the final layout information for an item that is about to be removed from the collection view.
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.hfinalLayoutAttributesForDisappearingSupplementaryElementOfKind:atIndexPath:
Returns the final layout information for a supplementary view that is about to be removed from the collection view.
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.hinitialLayoutAttributesForAppearingDecorationElementOfKind:atIndexPath:
Returns the starting layout information for a decoration view being inserted into the collection view.
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.hinitialLayoutAttributesForAppearingItemAtIndexPath:
Returns the starting layout information for an item being inserted into the collection view.
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.hinitialLayoutAttributesForAppearingSupplementaryElementOfKind:atIndexPath:
Returns the starting layout information for a supplementary view being inserted into the collection view.
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.hinvalidateLayout
Invalidates the current layout and triggers a layout update.
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.
Availability
- Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.hlayoutAttributesForDecorationViewOfKind:atIndexPath:
Returns the layout attributes for the specified decoration view.
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.
See Also
Declared In
UICollectionViewLayout.hlayoutAttributesForElementsInRect:
Returns the layout attributes for all of the cells and views in the specified rectangle.
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.hlayoutAttributesForItemAtIndexPath:
Returns the layout attributes for the item at the specified index path.
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.
See Also
Declared In
UICollectionViewLayout.hlayoutAttributesForSupplementaryViewOfKind:atIndexPath:
Returns the layout attributes for the specified supplementary view.
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.
See Also
Declared In
UICollectionViewLayout.hprepareForAnimatedBoundsChange:
Prepares the layout object for animated changes to the view’s bounds or the insertion or deletion of items.
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.hprepareForCollectionViewUpdates:
Prepares the layout object to receive changes to the contents of the collection view.
Parameters
- updateItems
An array of
UICollectionViewUpdateItemobjects 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.hprepareLayout
Tells the layout object to update the current layout.
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.hregisterClass:forDecorationViewOfKind:
Registers a class for use in creating decoration views for a collection view.
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
niland 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.hregisterNib:forDecorationViewOfKind:
Registers a nib file for use in creating decoration views for a collection view.
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
niland 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.hshouldInvalidateLayoutForBoundsChange:
Asks the layout object if the new bounds require a layout update.
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 should 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.
Availability
- Available in iOS 6.0 and later.
Declared In
UICollectionViewLayout.htargetContentOffsetForProposedContentOffset:withScrollingVelocity:
Returns the point at which to stop scrolling.
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© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)