UICollisionBehavior Class Reference

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

Overview

A collision behavior confers, to a specified array of dynamic items, the ability of those items to engage in collisions with each other and with the behavior’s specified boundaries. A collision behavior also specifies some characteristics of its items’ collisions, with other characteristics optionally specified by a UIDynamicItemBehavior object.

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.

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

  1. Associate the item with the behavior using the addItem: method, or initialize a new collision 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 collision 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 add multiple collision behaviors to a dynamic animator. A dynamic item can be part of any number of collision behaviors, provided those behaviors belong to the same animator. For example, you can specify a collision behavior for a set of say, blue, items and another for, say, pink items. When you add both behaviors to a dynamic animator, blue items can collide with each other and pink items can collide with each other, but a blue item and a pink item would not collide—they would ignore each other.

By default, a collision behavior’s items can collide with each other and with any boundaries you’ve specified for the behavior. If you want to specify that a behavior’s items collide only with each other, or only with boundaries, explicitly set the collisionMode property.

You can define a collision boundary with a bezier path (see the addBoundaryWithIdentifier:forPath: method) or with a line segment (see the addBoundaryWithIdentifier:fromPoint:toPoint: method). When you use a collision behavior with a dynamic animator you’ve initialized with a reference view or a collection view layout, you can also specify a collision boundary according to the bounds of the dynamic animator’s coordinate system (see the setTranslatesReferenceBoundsIntoBoundaryWithInsets: method).

To respond to collisions, implement a delegate object that adopts the UICollisionBehaviorDelegate protocol. Add the delegate to the behavior using the collisionDelegate property.

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

Tasks

Initializing and Managing a Collision Behavior

Configuring a Collision Behavior

Properties

boundaryIdentifiers

The set of boundary identifiers that you’ve added to the collision behavior. (read-only)

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

If you haven’t added any boundary identifiers to the collision behavior, this property’s value is nil.

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

collisionDelegate

The delegate object that you want to respond to collisions for the collision behavior.

@property(nonatomic, assign, readwrite) id<UICollisionBehaviorDelegate> collisionDelegate
Availability
  • Available in iOS 7.0 and later.
Declared In
UICollisionBehavior.h

collisionMode

The type of edges that participate in collisions for the collision behavior.

@property(nonatomic, readwrite) UICollisionBehaviorMode collisionMode
Discussion

To specify collisionMode, use one of the values in the “UICollisionBehaviorMode” enum. The default value is UICollisionBehaviorModeEverything.

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

items

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

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

translatesReferenceBoundsIntoBoundary

Specifies whether a boundary based on the reference system is active.

@property(nonatomic, readwrite) BOOL translatesReferenceBoundsIntoBoundary
Discussion

To specify a collision boundary based on the reference system, use the setTranslatesReferenceBoundsIntoBoundaryWithInsets: method.

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

Instance Methods

addBoundaryWithIdentifier:forPath:

Adds a collision boundary, specified as a Bezier path, to the collision behavior.

- (void)addBoundaryWithIdentifier:(id<NSCopying>)identifier forPath:(UIBezierPath *)bezierPath
Parameters
identifier

An arbitrary identifier for the boundary you are adding.

bezierPath

An arbitrary Bezier path that specifies the collision boundary you are adding.

The coordinate system and origin point for the path depend on how you’ve initialized the dynamic animator (that you’re adding the behavior to). See the overview in UIDynamicAnimator Class Reference for more information.

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

addBoundaryWithIdentifier:fromPoint:toPoint:

Adds a collision boundary, specified as a line segment, to the collision behavior.

- (void)addBoundaryWithIdentifier:(id<NSCopying>)identifier fromPoint:(CGPoint)p1 toPoint:(CGPoint)p2
Parameters
identifier

An arbitrary identifier for the boundary you are adding.

p1

The starting point for the boundary line segment.

p2

The ending point for the boundary line segment.

Discussion

This is a convenience method based on the addBoundaryWithIdentifier:forPath: method. The coordinate system and origin point for the p1 and p2 parameters depend on how you’ve initialized the dynamic animator (that you’re adding the behavior to). See the overview in UIDynamicAnimator Class Reference for more information.

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

addItem:

Adds a dynamic item to the collision 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 collision behaviors. For example, you can use two collision behaviors to specify that item A can collide with item B and that item C can collide with item D, but that items A and B ignore items C and D.

There is no hard limit to the number of dynamic items you can add to a collision behavior. However, adding a large number of items might result in a performance impact. Be sure to test your behaviors on the device configurations you are targeting.

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

boundaryWithIdentifier:

Returns a specified Bezier-path boundary.

- (UIBezierPath *)boundaryWithIdentifier:(id<NSCopying>)identifier
Parameters
identifier

A boundary identifier that you’ve previously added to the collision behavior.

Return Value

A Bezier-path boundary.

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

initWithItems:

Initializes a collision behavior with an array of dynamic items.

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

The dynamic items that you want to participate in the collision behavior.

Return Value

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

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

removeAllBoundaries

Removes all previously-specified collision boundaries from the collision behavior.

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

removeBoundaryWithIdentifier:

Removes a specific collision boundary from the collision behavior.

- (void)removeBoundaryWithIdentifier:(id<NSCopying>)identifier
Parameters
identifier

The identifier of the boundary you want to remove.

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

removeItem:

Removes a specific dynamic item from the collision 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
UICollisionBehavior.h

setTranslatesReferenceBoundsIntoBoundaryWithInsets:

Specifies a collision boundary based on the bounds of the animation reference system, with optional insets.

- (void)setTranslatesReferenceBoundsIntoBoundaryWithInsets:(UIEdgeInsets)insets
Parameters
insets

Insets to apply to the reference system’s bounds when defining the collision boundary.

Discussion

The result of using this method depends on how you’ve initialized the dynamic animator (of class UIDynamicAnimator) that you’ve added the collision behavior to. See the overview in UIDynamicAnimator Class Reference for a discussion of initialization options and modes for animators.

Here is how the dynamic animator’s initialization impacts use of this method:

  • For a view-only dynamic animator, the reference bounds are those of the reference view

  • For a collection-view dynamic animator, the reference bounds are those of the collection view layout

  • For a dynamic-item dynamic animator, there are no reference bounds.

For a collision behavior added to a view-only or collection-view dynamic animator, activate a reference-system-based collision boundary by setting the translatesReferenceBoundsIntoBoundary property to YES.

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

Constants

UICollisionBehaviorMode

The types of edges that participate in collisions for a collision behavior.

typedef NS_OPTIONS(NSUInteger,
   UICollisionBehaviorMode) {
   UICollisionBehaviorModeItems       = 1 << 0,
   UICollisionBehaviorModeBoundaries  = 1 << 1,
   UICollisionBehaviorModeEverything  = NSUIntegerMax
};
Constants
UICollisionBehaviorModeItems

Specifies that the dynamic items, associated with the collision behavior, collide only with each other and not with specified collision boundaries.

Available in iOS 7.0 and later.

Declared in UICollisionBehavior.h.

UICollisionBehaviorModeBoundaries

Specifies that the dynamic items, associated with the collision behavior, collide only with specified collision boundaries and do not collide with each other.

Available in iOS 7.0 and later.

Declared in UICollisionBehavior.h.

UICollisionBehaviorModeEverything

Specifies that the dynamic items, associated with the collision behavior, collide with each other and with specified collision boundaries.

This is the default collision behavior mode.

Available in iOS 7.0 and later.

Declared in UICollisionBehavior.h.