UIPushBehavior Class Reference

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

Overview

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

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 pushDirection 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 addItem: method, or initialize a new push behavior with an array of items using the initWithItems:mode: method

  2. Enable the behavior by adding it to an animator using the addBehavior: 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 UIDynamicAnimator Class Reference.

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

Tasks

Initializing and Managing a Push Behavior

Configuring a Push Behavior

Properties

active

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

@property(nonatomic, readwrite) BOOL active
Discussion

After you’ve added a push behavior to a dynamic animator, use this property to activate or deactivate the behavior’s force (rather than removing and then re-adding the behavior to the animator).

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

angle

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

@property(readwrite, nonatomic) CGFloat angle
Discussion

The default angle is 0 radians, using standard UIKit geometry. To configure the force vector for a push behavior, set the magnitude property as well as the angle property.

Alternatively, you can express the direction of force by using x and y components with the pushDirection property. Whichever approach you use, the alternate, equivalent values update automatically.

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

items

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

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

magnitude

The magnitude of the force vector for the push behavior.

@property(readwrite, nonatomic) CGFloat magnitude
Discussion

The default magnitude 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 indicated by the angle or pushDirection property.

Setting the magnitude parameter to a negative value reverses the direction of the force.

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

mode

Returns the force mode for the push behavior. (read-only)

@property(nonatomic, readonly) UIPushBehaviorMode mode
Discussion

The mode is one of the values available in the “UIPushBehaviorMode” enumeration. Set the mode when you call the initWithItems:mode: method.

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

pushDirection

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

@property(readwrite, nonatomic) CGVector pushDirection
Discussion

The default x and y values of the push direction vector are each 0.0. A value for either component 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 positive direction for the component.

Setting either direction component to a negative value reverses the direction of force for the component.

Whether you express a push behavior’s push direction in terms of x, y components or with an angle (by using the angle property), the alternate, equivalent value updates automatically.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
UIPushBehavior.h

Instance Methods

addItem:

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

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

The dynamic item to add to the item array.

Discussion

All the dynamic items added to a push behavior are subject to the same force vector.

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

initWithItems:mode:

Initializes a push behavior with an array of dynamic items.

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

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

mode

The mode for the new push behavior; one of the values defined in the “UIPushBehaviorMode” enumeration. You must supply a value.

Return Value

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

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

removeItem:

Removes a specific dynamic item from the behavior.

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

The dynamic item that you want to remove.

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

setAngle:magnitude:

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

- (void)setAngle:(CGFloat)angle magnitude:(CGFloat)magnitude
Parameters
angle

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

The default angle is 0 radians, using standard UIKit geometry.

magnitude

The magnitude of the force vector for the push behavior.

The default magnitude is nil, equivalent to no force. A 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².

Setting the magnitude parameter to a negative value reverses the direction of the force.

Discussion

Whether you express a push behavior’s force direction in terms of radian angle or with x, y components, the alternate, equivalent values update automatically.

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

setTargetOffsetFromCenter:forItem:

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

- (void)setTargetOffsetFromCenter:(UIOffset)o forItem:(id<UIDynamicItem>)item
Parameters
o

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

item

The dynamic item for which you’re setting a target offset.

Discussion

If you don’t set a target offset for a dynamic item, a push behavior’s force vector is applied at the item center.

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

targetOffsetFromCenterForItem:

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

- (UIOffset)targetOffsetFromCenterForItem:(id<UIDynamicItem>)item
Parameters
item

The dynamic item for which you’re retrieving the target offset.

Return Value

The offset, from the center of the dynamic item, at which the push behavior’s force vector is applied. If you haven’t set a target offset, returns the center of the dynamic item.

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

Constants

UIPushBehaviorMode

The type of force for the push behavior.

typedef NS_ENUM(NSInteger,
   UIPushBehaviorMode) {
   UIPushBehaviorModeContinuous,
   UIPushBehaviorModeInstantaneous
};
Constants
UIPushBehaviorModeContinuous

Option for continuous force.

Available in iOS 7.0 and later.

Declared in UIPushBehavior.h.

UIPushBehaviorModeInstantaneous

Option for instantaneous force.

Available in iOS 7.0 and later.

Declared in UIPushBehavior.h.