iOS Developer Library

Developer

UIKit Framework Reference UIDynamicAnimator Class Reference

Options
Deployment Target:

On This Page
Language:

UIDynamicAnimator

A dynamic animator provides physics-related capabilities and animations for its dynamic items, and provides the context for those animations. It does this by intermediating between the underlying iOS physics engine and dynamic items, via behavior objects you add to the animator.

A dynamic item is any iOS or custom object that conforms to the UIDynamicItem protocol. The UIView and UICollectionViewLayoutAttributes classes implement this protocol starting in iOS 7.0. You can implement this protocol to use a dynamic animator with custom objects for such purposes as reacting to rotation or position changes computed by an animator.

To use dynamics, configure one or more dynamic behaviors—including providing each with a set of dynamic items—and then add those behaviors to a dynamic animator.

You specify dynamic behaviors using any of the iOS primitive dynamic behavior classes: UIAttachmentBehavior, UICollisionBehavior, UIDynamicItemBehavior, UIGravityBehavior, UIPushBehavior, and UISnapBehavior. Each of these provides configuration options and lets you associate one or more dynamic items to the behavior. To activate a behavior, add it to an animator.

A dynamic animator interacts with each of its dynamic items as follows:

  1. Before adding an item to a behavior, you specify the item’s starting position, rotation, and bounds (to do so, use properties of the item’s class, such as the center, transform, and bounds properties in the case of a UIView-based item)

  2. After you add the behavior to an animator, the animator takes over: it updates the item’s position and rotation as animation proceeds (see the UIDynamicItem protocol)

  3. You can programmatically update an item’s state in the midst of an animation, after which the animator takes back control of the item’s animation, relative to the state you specified (see the updateItemUsingCurrentState: method)

You can define composite behaviors using the addChildBehavior: method of the UIDynamicBehavior parent behavior class. The set of behaviors you add to an animator constitute a behavior hierarchy. Each behavior instance you associate with an animator can be present only once in the hierarchy.

To employ a dynamic animator, first identify the type of dynamic items you want to animate. This choice determines which initializer to call, and this in turn determines how the coordinate system gets set up. The three ways to initialize an animator, the dynamic items you can then use, and the resulting coordinate system, are as follows:

  • To animate views, create an animator with the initWithReferenceView: method. The coordinate system of the reference view serves as the coordinate system for the animator’s behaviors and items. Each dynamic item you associate with this sort of animator must be a UIView object and must descend from the reference view.

    You can define a boundary, for items participating in a collision behavior, relative to the bounds of the reference view. See the setTranslatesReferenceBoundsIntoBoundaryWithInsets: method.

  • To animate collection views, create an animator with the initWithCollectionViewLayout: method. The resulting animator employs a collection view layout (an object of the UICollectionViewLayout class) for its coordinate system. The dynamic items in this sort of animator must be UICollectionViewLayoutAttributes objects that are part of the layout.

    You can define a boundary, for items participating in a collision behavior, relative to the bounds of the collection view layout. See the setTranslatesReferenceBoundsIntoBoundaryWithInsets: method.

    A collection view animator automatically calls the invalidateLayout method as needed, and automatically pauses and resumes animation, as appropriate, when you change a collection view’s layout.

  • To employ a dynamic animator with other objects that conform to the UIDynamicItem protocol, create an animator with the inherited init method. The resulting animator employs an abstract coordinate system, not tied to the screen or to any view.

    There is no reference boundary to refer to when defining a collision boundary for use with this sort of animator. However, you can still, in a collision behavior, specify custom boundaries as described in UICollisionBehavior Class Reference.

All types of dynamic animators share the following characteristics:

  • Each dynamic animator is independent of other dynamic animators you create

  • You can associate a given dynamic item with multiple behaviors, provided those behaviors belong to the same animator

  • An animator automatically pauses when all its items are at rest, and automatically resumes when a behavior parameter changes or a behavior or item is added or removed

You can implement a delegate to respond to changes in animator pause/resumption status, using the dynamicAnimatorDidPause: and dynamicAnimatorWillResume: methods of the UIDynamicAnimatorDelegate protocol.

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 7.0 and later.
  • Initializes a dynamic animator with a specified view as its reference view.

    Declaration

    Swift

    init(referenceView view: UIView)

    Objective-C

    - (instancetype)initWithReferenceView:(UIView *)view

    Parameters

    view

    The view for the dynamic animator, called the reference view.

    Return Value

    The initialized dynamic animator, or nil if there was a problem initializing the object.

    Discussion

    When you initialize a dynamic animator with this method, the behaviors (and their dynamic items) that you add to the animator employ the reference view’s coordinate system.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Initializes a dynamic animator with a specified collection view layout.

    Declaration

    Swift

    init(collectionViewLayout layout: UICollectionViewLayout)

    Objective-C

    - (instancetype)initWithCollectionViewLayout:(UICollectionViewLayout *)layout

    Parameters

    layout

    The collection view layout for the dynamic animator, serving as the reference view for a dynamic animator in collection-view mode.

    Return Value

    The initialized dynamic animator, or nil if there was a problem initializing the object.

    Discussion

    When you initialize a dynamic animator with this method, the behaviors (and their dynamic items) that you add to the animator employ the collection view layout’s coordinate system.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Returns the dynamic items, from the animator’s behaviors, that intersect a specified rectangle.

    Declaration

    Swift

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

    Objective-C

    - (NSArray *)itemsInRect:(CGRect)rect

    Parameters

    rect

    The rectangle you are interested in.

    Return Value

    The dynamic items, from the animator’s behaviors, that intersect the specified rectangle.

    Discussion

    The coordinate system that pertains to the rect parameter depends on how you initialized the animator, as described in the Overview in this document.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Adds a dynamic behavior to a dynamic animator.

    Declaration

    Swift

    func addBehavior(_ behavior: UIDynamicBehavior!)

    Objective-C

    - (void)addBehavior:(UIDynamicBehavior *)behavior

    Parameters

    behavior

    The dynamic behavior instance you are adding.

    The dynamic animator ignores your use of this method if you:

    • Provide a nil value

    • Provide a behavior instance that you’ve already added to the animator at the same level in the behavior hierarchy

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Removes a specified dynamic behavior from a dynamic animator.

    Declaration

    Swift

    func removeBehavior(_ behavior: UIDynamicBehavior!)

    Objective-C

    - (void)removeBehavior:(UIDynamicBehavior *)behavior

    Parameters

    behavior

    The dynamic behavior instance that you want to remove from the animator.

    The dynamic animator ignores your use of this method if you:

    • Provide a nil value

    • Provide a dynamic behavior instance that is not part of the animator’s behavior hierarchy

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Removes all of the dynamic behaviors from a dynamic animator.

    Declaration

    Swift

    func removeAllBehaviors()

    Objective-C

    - (void)removeAllBehaviors

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Returns the time interval since the dynamic animator started running.

    Declaration

    Swift

    func elapsedTime() -> NSTimeInterval

    Objective-C

    - (NSTimeInterval)elapsedTime

    Return Value

    The elapsed time since the dynamic animator started running.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • running running Property

    Returns YEStrue if the dynamic animator is running. (read-only)

    Declaration

    Swift

    var running: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isRunning) BOOL running

    Discussion

    The views associated with an animator’s behaviors can change position or change transform only when the animator is running. For optimization purposes, iOS can pause and then restart an animator. Use this method if you need to check whether or not your views are currently subject to changes in position or transform.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • behaviors behaviors Property

    The dynamic behaviors managed by a dynamic animator. (read-only)

    Declaration

    Swift

    var behaviors: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSArray *behaviors

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The view that a dynamic animator was initialized with. (read-only)

    Declaration

    Swift

    var referenceView: UIView? { get }

    Objective-C

    @property(nonatomic, readonly) UIView *referenceView

    Discussion

    This property has a value only for a dynamic animator initialized using the initWithReferenceView: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • delegate delegate Property

    The delegate for responding to pausing or resumption of animation.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIDynamicAnimatorDelegate?

    Objective-C

    @property(nonatomic, assign) id< UIDynamicAnimatorDelegate > delegate

    Discussion

    The methods for a dynamic animator delegate are described in UIDynamicAnimatorDelegate Protocol Reference.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Asks a dynamic animator to read the current state of a dynamic item, replacing the animator’s internal representation of the item’s state.

    Declaration

    Swift

    func updateItemUsingCurrentState(_ item: UIDynamicItem)

    Objective-C

    - (void)updateItemUsingCurrentState:(id<UIDynamicItem>)item

    Parameters

    item

    The dynamic item whose state was changed by your app.

    Discussion

    A dynamic animator automatically reads the initial state (position and rotation) of each dynamic item you add to it, and then takes responsibility for updating the item’s state. If you actively change the state of a dynamic item after you’ve added it to a dynamic animator, call this method to ask the animator to read and incorporate the new state.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.