A push behavior applies a continuous or instantaneous force to one or more dynamic items, causing those items to change position accordingly.


A dynamic item is any iOS or custom object that conforms to the UIDynamic​Item protocol. The UIView and UICollection​View​Layout​Attributes classes implement this protocol starting in iOS 7.0. You can use a custom object as a dynamic item for such purposes as reacting to rotation or position changes computed by a dynamic animator—an instance of the UIDynamic​Animator class.

The default magnitude of a push behavior’s force vector is nil, equivalent to no force. A continuous force vector with a magnitude of 1.0, applied to a 100 point x 100 point view whose density value is 1.0, results in view acceleration of 100 points / second² in the direction of the vector; this value is also known as the UIKit Newton.

You express a push behavior’s force vector in terms of magnitude (magnitude) and radian angle (angle). Instead of using radian angle, you can equivalently express direction using x and y components by using the push​Direction property. Whichever approach you use, the alternate, equivalent values update automatically.

For each dynamic item that you associate with a push, the force is applied at the item center or at a specified offset from the center in item-relative coordinates.

To use a push behavior with a dynamic item, perform these two steps:

  1. Associate the item with the behavior using the add​Item(_:​) method, or initialize a new push behavior with an array of items using the init(items:​mode:​) method

  2. Enable the behavior by adding it to an animator using the add​Behavior(_:​) method

After enabling a push behavior, you can activate it and deactivate it using the active property.

The coordinate system that pertains to a push behavior, and the types of dynamic items you can use with the behavior, depend on how you initialized the associated animator. For details, read the Overview of UIDynamic​Animator.

You can include a push behavior in a custom, composite behavior by starting with a UIDynamic​Behavior object and adding a push behavior with the add​Child​Behavior(_:​) method. If you want to influence a push behavior at each step of a dynamic animation, implement the inherited action method.


Initializing and Managing a Push Behavior

var active:​ Bool

The state of the push behavior’s force: either active or inactive.

func add​Item(UIDynamic​Item)

Adds a dynamic item to the behavior’s dynamic item array.

init(items:​ [UIDynamic​Item], mode:​ UIPush​Behavior​Mode)

Initializes a push behavior with an array of dynamic items.

func remove​Item(UIDynamic​Item)

Removes a specific dynamic item from the behavior.

var items:​ [UIDynamic​Item]

Returns the set of dynamic items you’ve added to the push behavior.

Configuring a Push Behavior

func set​Angle(CGFloat, magnitude:​ CGFloat)

Sets the angle and magnitude of the force vector for the behavior.

var angle:​ CGFloat

The angle, in radians, of the force vector for the behavior.

var magnitude:​ CGFloat

The magnitude of the force vector for the push behavior.

var mode:​ UIPush​Behavior​Mode

Returns the force mode for the push behavior.

func set​Target​Offset​From​Center(UIOffset, for:​ UIDynamic​Item)

Sets the offset, from the center of a dynamic item, at which to apply the push behavior’s force vector.

func target​Offset​From​Center(for:​ UIDynamic​Item)

Returns the offset, from the center of a dynamic item, at which the push behavior’s force vector is applied.

var push​Direction:​ CGVector

The direction of the force vector for the behavior, expressed as x and y components and using standard UIKit geometry.



The type of force for the push behavior.