iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UICollectionViewTransitionLayout Class Reference

Options
Deployment Target:

On This Page
Language:

UICollectionViewTransitionLayout

The UICollectionViewTransitionLayout class is a special type of layout object that lets you implement behaviors when changing from one layout to another in your collection view. You can use this class as-is or subclass it to provide specialized behavior for your app. A common use for transition layouts is to create interactive transitions, such as those that are driven by gesture recognizers or touch events.

During a layout change, the collection view installs this layout object temporarily to manage the changeover. This layout object determines the layout of each item by interpolating between the layout values in the current and new layout objects. The interpolation is driven by the value in the transitionProgress property, which you update periodically from your code to drive the transition. For example, if you use this class in conjunction with a gesture recognizer, the handler for your gesture recognizer would update that property and invalidate the layout.

If you want to provide more than just a linear transition from the old to new layout over time, you need to subclass and provide the layout attributes for items yourself. Subclassing requires you to override all of the same methods you would override when subclassing UICollectionViewLayout. The difference is that your custom methods can work with your gesture recognizers or touch event code to change the layout based on input from the user. For example, you could use a custom layout object in conjunction with a gesture recognizer to make items track the location of the user’s finger on the screen. You also need to implement the collectionView:transitionLayoutForOldLayout:newLayout: method of your collection view delegate and return your custom layout object when asked for it.

  • Initializes and returns a transition layout object.

    Declaration

    Swift

    init(currentLayout currentLayout: UICollectionViewLayout, nextLayout newLayout: UICollectionViewLayout)

    Objective-C

    - (instancetype _Nonnull)initWithCurrentLayout:(UICollectionViewLayout * _Nonnull)currentLayout nextLayout:(UICollectionViewLayout * _Nonnull)newLayout

    Parameters

    currentLayout

    The layout object currently in use by the collection view.

    newLayout

    The new layout object that is being installed into the collection view.

    Return Value

    An initialized transition layout object or nil if the object could not be created.

    Discussion

    This method initializes the transition layout object and saves references to the current and new layout objects so that you can access them later. If you subclass and implement your own initialization method, you must call this method to initialize the superclass.

    Availability

    Available in iOS 7.0 and later.

  • The completion percentage of the transition.

    Declaration

    Swift

    var transitionProgress: CGFloat

    Objective-C

    @property(assign, nonatomic) CGFloat transitionProgress

    Discussion

    During the transition, you should set the value of this property periodically and call invalidateLayout to force the collection view to update item positions. If you are driving the transition with a gesture recognizer, you would likely set this property from the handler method of your gesture recognizer.

    Availability

    Available in iOS 7.0 and later.

  • Sets the value for an animatable key.

    Declaration

    Swift

    func updateValue(_ value: CGFloat, forAnimatedKey key: String)

    Objective-C

    - (void)updateValue:(CGFloat)value forAnimatedKey:(NSString * _Nonnull)key

    Parameters

    value

    The value you want to store for the specified key.

    key

    A key that you define for your custom transition layout.

    Discussion

    Use this method to store a floating-point value with a specific key that you define for your transition layout object. The name of the key should be one that has meaning to your layout object. For example, if you track the position of the user’s finger over time, you might define the keys "PositionX” and "PositionY” to track those changes. Each time you update the value of a key, the layout object records the change along with a timestamp value. When the layout is finalized or canceled, those values can then be used to determine the speed with which to perform the remaining animations.

    For any keys you set using this method, you should get that value as part of the normal process of generating layout attribute information. Getting the value using the valueForAnimatedKey: method (as opposed to getting the value from a class variable) means that when the collection view performs its final animations, your layout methods provide the correct values.

    Availability

    Available in iOS 7.0 and later.

  • Returns the most recently set value for the specified key.

    Declaration

    Swift

    func valueForAnimatedKey(_ key: String) -> CGFloat

    Objective-C

    - (CGFloat)valueForAnimatedKey:(NSString * _Nonnull)key

    Parameters

    key

    A key whose value you set using the updateValue:forAnimatedKey: method.

    Return Value

    The last value set for the key.

    Discussion

    Use this method to retrieve floating-point values that are useful when laying out the contents of your collection view. The key you specify is a string that you define and that has some meaning to your implementation. At points during an interactive transition, you can assign new values to that key using the updateValue:forAnimatedKey: method.

    Availability

    Available in iOS 7.0 and later.

  • The collection view’s current layout object. (read-only)

    Declaration

    Swift

    var currentLayout: UICollectionViewLayout { get }

    Objective-C

    @property(readonly, nonatomic, nonnull) UICollectionViewLayout *currentLayout

    Discussion

    This object provides the layout attributes representing the initial position of items in the collection view. If you ultimately cancel the transition, the collection view animates its items back to the positions provided by this object.

    Availability

    Available in iOS 7.0 and later.

  • The collection view’s new layout object. (read-only)

    Declaration

    Swift

    var nextLayout: UICollectionViewLayout { get }

    Objective-C

    @property(readonly, nonatomic, nonnull) UICollectionViewLayout *nextLayout

    Discussion

    This object provides the layout attributes representing the new position of items in the collection view. If the transition completes as expected, the collection view animates its items to the positions provided by this object.

    Availability

    Available in iOS 7.0 and later.