UIDynamicItemBehavior Class Reference

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

Overview

A dynamic item behavior represents a base dynamic animation configuration for one or more dynamic items. Each of its properties overrides a corresponding default value.

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 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 UIDynamicAnimator class.

One notable and common use of a dynamic item behavior is to confer a velocity to a dynamic item to match the ending velocity of a user gesture.

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

  1. Associate the item with the behavior using the addItem: method, or initialize a new dynamic item behavior with an array of items using the initWithItems: method

  2. Enable the behavior by adding it to an animator using the addBehavior: method

The coordinate system that pertains to a dynamic item 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 UIDynamicAnimator Class Reference.

You can disable rotation for a dynamic item behavior’s items by returning NO from the allowsRotation property. To configure interaction among the behavior’s items, use the elasticity and friction properties.

You can include a dynamic item behavior in a custom, composite behavior by starting with a UIDynamicBehavior object and adding a dynamic item behavior with the addChildBehavior: method. If you want to influence a dynamic item behavior at each step of a dynamic animation, implement the inherited action method.

If you add more than one dynamic item behavior to an animator, you effectively create a behavior tree. Only one configuration of a given property applies to any given dynamic item. For a property configured in more than one dynamic item behavior, the last one in the behavior tree, starting from the dynamic animator and going depth first toward the dynamic item, wins.

In the case of an animator with exactly one dynamic item behavior, you can restore default values for all dynamic item behavior properties by removing the behavior. In the case of an animator to which you’ve applied multiple dynamic item behaviors, removing one takes its property contribution out of the behavior tree.

Tasks

Initializing and Managing a Dynamic Item Behavior

Configuring a Dynamic Item Behavior

Properties

allowsRotation

Specifies whether rotation is allowed for the behavior’s dynamic items.

@property(readwrite, nonatomic) BOOL allowsRotation
Discussion

Default value is YES. To disable rotation, set this property to NO.

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

angularResistance

The angular resistance for the behavior’s dynamic items.

@property(readwrite, nonatomic) CGFloat angularResistance
Discussion

Valid range is 0 through CGFLOAT_MAX. The greater the value, the greater the angular damping and the faster rotation slows to a stop.

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

density

The relative mass density of the behavior’s dynamic items.

@property(readwrite, nonatomic) CGFloat density
Discussion

A dynamic item’s relative density, along with its size, determines its effective mass when it participates in UIKit Dynamics behaviors—including friction, collisions, pushes, and so on. For example, say you have two dynamic items with the same density but different sizes: item one is 100 x 100 points and item two is 100 x 200 points. In this example, item two has twice the effective mass of item one. In an elastic collision, these items exhibit a natural conservation of momentum according to their relative masses.

A 100 x 100 point dynamic item with a density of 1.0, to which you apply a force (via a push behavior) of magnitude 1.0, accelerates at 100 points per second².

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

elasticity

The amount of elasticity applied to collisions for the behavior’s dynamic items.

@property(readwrite, nonatomic) CGFloat elasticity
Discussion

Default value is 0.0. Valid range is from 0.0 for no bounce upon collision, to 1.0 for completely elastic collisions.

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

friction

The linear resistance for the behavior’s dynamic items when two slide against each other.

@property(readwrite, nonatomic) CGFloat friction
Discussion

Default value is 0.0, which corresponds to no friction. Use a value of 1.0 to apply strong friction. To apply an even stronger friction, you can use higher numbers.

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

items

Returns the set of dynamic items you’ve added to the dynamic item behavior. (read-only)

@property(nonatomic, readonly, copy) NSArray *items
Discussion

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

resistance

The linear resistance for the behavior’s dynamic items, which reduces their linear velocity over time.

@property(readwrite, nonatomic) CGFloat resistance
Discussion

Default value is 0.0. Valid range is from 0.0 for no velocity damping, to CGFLOAT_MAX for complete velocity damping. If you set this property to 1.0, a dynamic item’s motion stops as soon as there is no force applied to it.

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

Instance Methods

addAngularVelocity:forItem:

Adds a specified angular velocity to a dynamic item.

- (void)addAngularVelocity:(CGFloat)velocity forItem:(id<UIDynamicItem>)item
Parameters
velocity

The angular velocity, expressed in radians per second, that you want to add to the specified dynamic item. Default value is 0. Applying a negative value reduces the angular velocity by the specified amount.

item

The dynamic item whose angular velocity you want to increase (or decrease).

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

addItem:

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

- (void)addItem:(id<UIDynamicItem>)item
Parameters
item

The dynamic item to add to the item array.

Discussion

You can add a dynamic item to one or more dynamic item behaviors. For example, you could add a dynamic item to one dynamic item behavior to configure the item’s elasticity and to a second dynamic item behavior to configure its density. This is especially useful when you are defining custom, combined behaviors for your dynamic items.

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

addLinearVelocity:forItem:

Adds a specified linear velocity to a dynamic item.

- (void)addLinearVelocity:(CGPoint)velocity forItem:(id<UIDynamicItem>)item
Parameters
velocity

The linear velocity, expressed in points per second, that you want to add to the specified dynamic item. Default value is 0. Applying a negative value reduces the linear velocity by the specified amount.

item

The dynamic item whose linear velocity you want to increase (or decrease).

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

angularVelocityForItem:

Returns the angular velocity for a specified dynamic item.

- (CGFloat)angularVelocityForItem:(id<UIDynamicItem>)item
Parameters
item

The dynamic item whose angular velocity you want to get.

Return Value

The angular velocity of the specified dynamic item, in radians per second.

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

initWithItems:

Initializes a dynamic item behavior with an array of dynamic items.

- (instancetype)initWithItems:(NSArray *)items
Parameters
items

The dynamic items that you want to be subject to the dynamic item behavior.

Return Value

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

Discussion

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

linearVelocityForItem:

Returns the linear velocity for a specified dynamic item.

- (CGPoint)linearVelocityForItem:(id<UIDynamicItem>)item
Parameters
item

The dynamic item whose linear velocity you want to get.

Return Value

The linear velocity of the specified dynamic item, in points per second.

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

removeItem:

Removes a specific dynamic item from the dynamic item behavior.

- (void)removeItem:(id<UIDynamicItem>)item
Parameters
item

The dynamic item that you want to remove.

Discussion

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