UIDynamicAnimator Class Reference

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

Overview

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:

All types of dynamic animators share the following characteristics:

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

Tasks

Initializing and Managing a Dynamic Animator

Accessing a Dynamic Animator’s State

Collection View Additions

Properties

behaviors

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

@property(nonatomic, readonly, copy) NSArray *behaviors
Availability
  • Available in iOS 7.0 and later.
Declared In
UIDynamicAnimator.h

delegate

The delegate for responding to pausing or resumption of animation.

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

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

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

referenceView

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

@property(nonatomic, readonly) UIView *referenceView
Discussion

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

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

running

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

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

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

Instance Methods

addBehavior:

Adds a dynamic behavior to a dynamic animator.

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

Important: The dynamic animator raises an exception if you provide a behavior instance that you’ve already added to the animator at a different level in the behavior hierarchy.

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

elapsedTime

Returns the time interval since the dynamic animator started running.

- (NSTimeInterval)elapsedTime
Return Value

The elapsed time since the dynamic animator started running.

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

initWithCollectionViewLayout:

Initializes a dynamic animator with a specified collection view layout.

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

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

initWithReferenceView:

Initializes a dynamic animator with a specified view as its reference view.

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

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

itemsInRect:

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

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

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

layoutAttributesForCellAtIndexPath:

A convenience method for returning the layout attributes for a collection view cell.

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

The index path for the cell whose layout attributes you want.

Return Value

The collection view layout attributes for the specified collection view cell.

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

layoutAttributesForDecorationViewOfKind:atIndexPath:

A convenience method for returning the layout attributes for a collection view decoration view.

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

The kind identifier for the specified decoration view.

indexPath

The index path for the cell whose decoration view layout attributes you want.

Return Value

The collection view layout attributes for the specified decoration view.

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

layoutAttributesForSupplementaryViewOfKind:atIndexPath:

A convenience method for returning the layout attributes for a collection view supplementary view.

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

A string that identifies the type of supplementary view whose layout attributes you want.

indexPath

The index path for the cell whose supplementary view layout attributes you want.

Return Value

The collection view layout attributes for the specified supplementary view.

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

removeAllBehaviors

Removes all of the dynamic behaviors from a dynamic animator.

- (void)removeAllBehaviors
Availability
  • Available in iOS 7.0 and later.
Declared In
UIDynamicAnimator.h

removeBehavior:

Removes a specified dynamic behavior from a dynamic animator.

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

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

updateItemUsingCurrentState:

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

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

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