iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIPushBehavior Class Reference

Options
Deployment Target:

On This Page
Language:

UIPushBehavior

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.

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

    Declaration

    Swift

    var active: Bool

    Objective-C

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

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

    Declaration

    Swift

    func addItem(_ item: UIDynamicItem)

    Objective-C

    - (void)addItem:(id<UIDynamicItem> _Nonnull)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.

  • Initializes a push behavior with an array of dynamic items.

    Declaration

    Swift

    init(items items: [UIDynamicItem], mode mode: UIPushBehaviorMode)

    Objective-C

    - (instancetype _Nonnull)initWithItems:(NSArray<id<UIDynamicItem>> * _Nonnull)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.

  • Removes a specific dynamic item from the behavior.

    Declaration

    Swift

    func removeItem(_ item: UIDynamicItem)

    Objective-C

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

    Parameters

    item

    The dynamic item that you want to remove.

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var items: [UIDynamicItem] { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSArray <id<UIDynamicItem>> * _Nonnull items

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func setAngle(_ angle: CGFloat, magnitude magnitude: CGFloat)

    Objective-C

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

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

    Declaration

    Swift

    var angle: CGFloat

    Objective-C

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

  • The magnitude of the force vector for the push behavior.

    Declaration

    Swift

    var magnitude: CGFloat

    Objective-C

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

  • mode mode Property

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

    Declaration

    Swift

    var mode: UIPushBehaviorMode { get }

    Objective-C

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

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

    Declaration

    Swift

    func setTargetOffsetFromCenter(_ o: UIOffset, forItem item: UIDynamicItem)

    Objective-C

    - (void)setTargetOffsetFromCenter:(UIOffset)o forItem:(id<UIDynamicItem> _Nonnull)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.

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

    Declaration

    Swift

    func targetOffsetFromCenterForItem(_ item: UIDynamicItem) -> UIOffset

    Objective-C

    - (UIOffset)targetOffsetFromCenterForItem:(id<UIDynamicItem> _Nonnull)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.

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

    Declaration

    Swift

    var pushDirection: CGVector

    Objective-C

    @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

    angle

  • The type of force for the push behavior.

    Declaration

    Swift

    enum UIPushBehaviorMode : Int { case Continuous case Instantaneous }

    Objective-C

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

    Constants

    • Continuous

      UIPushBehaviorModeContinuous

      Option for continuous force.

      Available in iOS 7.0 and later.

    • Instantaneous

      UIPushBehaviorModeInstantaneous

      Option for instantaneous force.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.