iOS Developer Library

Developer

UIKit Framework Reference UIAttachmentBehavior Class Reference

Options
Deployment Target:

On This Page
Language:

UIAttachmentBehavior

A UIAttachmentBehavior object creates a relationship between two dynamic items, or between a dynamic item and an anchor point. When two items are attached to each other, forces imparted on one item affect the movement of the other in a prescribed way. When an item is attached to an anchor point, the movement of that item is affected by its attachment to the specified anchor point. Some attachment behaviors support both two items and an anchor point.

You specify type of attachment behavior you want at creation time. This class offers many creation and initialization methods, each of which creates a different type of attachment behavior, which cannot be changed later. However, you may change specific attributes of the attachment behavior using the properties of this class. For example, you can change the distance between two attached items or change the damping forces applied to the items.

Applying an Attachment Behavior to Dynamic Items

To apply an attachment behavior to your dynamic items, do the following:

  1. Create the attachment behavior using one of the creation or initialization methods. The method you choose defines the relationship between the items and the anchor point (if any).

  2. Enable the attachment behavior by adding it to your UIDynamicAnimator object using the addBehavior: method. Do not add the same attachment behavior to multiple animator objects.

The attachment behavior derives its coordinate system from the reference view of its associated dynamic animator object. For more information about the dynamic animator and the reference coordinate system, see UIDynamicAnimator Class Reference.

  • Creates and returns an attachment behavior where one item slides along the specified axis.

    Declaration

    Swift

    class func slidingAttachmentWithItem(_ item: UIDynamicItem, attachmentAnchor point: CGPoint, axisOfTranslation axis: CGVector) -> Self

    Objective-C

    + (instancetype)slidingAttachmentWithItem:(id<UIDynamicItem>)item attachmentAnchor:(CGPoint)point axisOfTranslation:(CGVector)axis

    Parameters

    item

    The dynamic item connected by the attachment behavior.

    point

    The initial anchor point for the item. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    axis

    The axis of translation, along which the item’s anchor point slides. The magnitude of the vector is ignored. Use the attachmentRange property to define the distance that the anchor point can travel along the vector.

    Return Value

    A new attachment object or nil if the object could not be created.

    Discussion

    The behavior created by this method acts like a solid rod between item and the anchor point whose initial position you specify using the point parameter. As forces are applied to the item, the item’s anchor point slides along the specified axis, causing the item to move with it. The item does not rotate relative to the axis of translation or anchor point.

    The axis of translation is infinitely long initially, but you can change the length by assigning a new value to the attachmentRange property. When specifying a new attachment range, remember that the value in point represents the value 0 on the axis. Any new range you specify must include 0.

    You can use this behavior to create an effect of an item sliding in a specific direction in response to other forces. For example, using the vector (0.0, 1.0) would cause the item to slide only vertically.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns an attachment behavior where two items are fixed to points that slide along the specified axis.

    Declaration

    Swift

    class func slidingAttachmentWithItem(_ item1: UIDynamicItem, attachedToItem item2: UIDynamicItem, attachmentAnchor point: CGPoint, axisOfTranslation axis: CGVector) -> Self

    Objective-C

    + (instancetype)slidingAttachmentWithItem:(id<UIDynamicItem>)item1 attachedToItem:(id<UIDynamicItem>)item2 attachmentAnchor:(CGPoint)point axisOfTranslation:(CGVector)axis

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    item2

    The second of two dynamic items connected by the attachment behavior.

    point

    The initial anchor point for both items. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    axis

    The axis of translation, along which the anchor points of the items slide.

    Return Value

    A new attachment object or nil if the object could not be created.

    Discussion

    For this behavior, each item acts like it is at the end of a solid rod attached to its anchor point. Both items start with the same anchor point, but as animations progress, each item’s anchor point is allowed to slide along the specified axis of translation independently. So if one item moves, it pushes the translation axis and the other item with it. The items do not rotate relative to the axis of translation or to each other, but the proximity of the items to one another varies depending on the movement of each item’s anchor point along the translation axis.

    The axis of translation is infinitely long initially, but you can change the length by assigning a new value to the attachmentRange property. When specifying a new attachment range, remember that the value in point represents the value 0 on the axis. Any new range you specify must include 0.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns an attachment behavior where the two items are fixed together through the specified anchor point.

    Declaration

    Swift

    class func fixedAttachmentWithItem(_ item1: UIDynamicItem, attachedToItem item2: UIDynamicItem, attachmentAnchor point: CGPoint) -> Self

    Objective-C

    + (instancetype)fixedAttachmentWithItem:(id<UIDynamicItem>)item1 attachedToItem:(id<UIDynamicItem>)item2 attachmentAnchor:(CGPoint)point

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    item2

    The second of two dynamic items connected by the attachment behavior.

    point

    The anchor point for both items. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    Return Value

    A new attachment object or nil if the object could not be created.

    Discussion

    The behavior created by this method acts like a solid rod connecting each item to the specified anchor point. The position of the items relative to each other does not change. Forces acting on the items move them together as if they were a single unit.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns an attachment behavior object where two items are constrained by a maximum distance from one another.

    Declaration

    Swift

    class func limitAttachmentWithItem(_ item1: UIDynamicItem, offsetFromCenter offset1: UIOffset, attachedToItem item2: UIDynamicItem, offsetFromCenter offset2: UIOffset) -> Self

    Objective-C

    + (instancetype)limitAttachmentWithItem:(id<UIDynamicItem>)item1 offsetFromCenter:(UIOffset)offset1 attachedToItem:(id<UIDynamicItem>)item2 offsetFromCenter:(UIOffset)offset2

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    offset1

    The offset from the center of item1 that corresponds to the attachment point. Use an offset value to create rotational torque on the item. To pull the item from its center, specify UIOffsetZero.

    item2

    The second of two dynamic items connected by the attachment behavior.

    offset2

    The offset from the center of item2 that corresponds to the attachment point. Use an offset value to create rotational torque on the item. To pull the item from its center, specify UIOffsetZero.

    Return Value

    A new attachment object or nil if the object could not be created.

    Discussion

    The behavior created by this method is like connecting two items with a rope. The only constraint between the items is the maximum distance between them, which corresponds to the moment when the rope is taut. At other times, the objects move freely relative to one another.

    The initial maximum distance between the items is set using the current position of the items. You can change the maximum distance by modifying the length property.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns an attachment behavior where the two items are pinned to, and move around, an anchor point

    Declaration

    Swift

    class func pinAttachmentWithItem(_ item1: UIDynamicItem, attachedToItem item2: UIDynamicItem, attachmentAnchor point: CGPoint) -> Self

    Objective-C

    + (instancetype)pinAttachmentWithItem:(id<UIDynamicItem>)item1 attachedToItem:(id<UIDynamicItem>)item2 attachmentAnchor:(CGPoint)point

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    item2

    The second of two dynamic items connected by the attachment behavior.

    point

    The initial anchor point for each item. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    Return Value

    A new attachment object or nil if the object could not be created.

    Discussion

    The behavior created by this method acts like a solid rod connecting each item to the specified anchor point. Each item is free to rotate around the anchor point, inscribing a circle whose radius is the defined at creation time by the distance between point and the item’s center. When forces act on one or both items, the anchor point and other item also move accordingly. The anchor point of the attachment does not interact with collision boundaries.

    Use the frictionTorque property to control the rotational behavior of the items. When the value of that property is 0, items rotate freely in response to almost any impulse. Adding torque increases the amount of force that must be applied to an item before it rotates.

    Use the attachmentRange property to limit the amount of rotation for each item. This property lets you specify the minimum and maximum amount of rotation of the items from their starting positions.

    Availability

    Available in iOS 9.0 and later.

  • Initializes a behavior where the center of a dynamic item is attached to the specified anchor point.

    Declaration

    Swift

    convenience init(item item: UIDynamicItem, attachedToAnchor point: CGPoint)

    Objective-C

    - (instancetype)initWithItem:(id<UIDynamicItem>)item attachedToAnchor:(CGPoint)point

    Parameters

    item

    The dynamic item to attach to the specified point.

    point

    The anchor point for the item. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    Return Value

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

    Discussion

    The behavior created by this method acts like a solid rod connecting the item to the specified anchor point. The item is free to rotate around the anchor point, but its distance to the anchor point remains fixed.

    The attachment object returned by this method is of type UIAttachmentBehaviorTypeAnchor.

    Availability

    Available in iOS 7.0 and later.

  • Initializes a behavior where the centers of two dynamic items are attached to each other.

    Declaration

    Swift

    convenience init(item item1: UIDynamicItem, attachedToItem item2: UIDynamicItem)

    Objective-C

    - (instancetype)initWithItem:(id<UIDynamicItem>)item1 attachedToItem:(id<UIDynamicItem>)item2

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    item2

    The second of two dynamic items connected by the attachment behavior.

    Return Value

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

    Discussion

    The behavior created by this method acts like a solid rod connecting the two items at their center points. Forces applied to one item push or pull the other item accordingly. The items are free to rotate around each other but always remain the same distance apart.

    The attachment object returned by this method is of type UIAttachmentBehaviorTypeItems.

    Availability

    Available in iOS 7.0 and later.

  • Initializes a behavior where the specified point in a dynamic item is attached to an anchor point.

    Declaration

    Swift

    init(item item: UIDynamicItem, offsetFromCenter offset: UIOffset, attachedToAnchor point: CGPoint)

    Objective-C

    - (instancetype)initWithItem:(id<UIDynamicItem>)item offsetFromCenter:(UIOffset)p1 attachedToAnchor:(CGPoint)point

    Parameters

    item

    The dynamic item to attach to the specified point.

    p1

    The offset from the center of item at which to create the attachment. Specifying UIOffsetZero creates the attachment at the center of item.

    point

    The anchor point for the item. Specify this point in the coordinate system of the dynamic animator’s reference view. For more information about coordinate systems, see UIDynamicAnimator Class Reference.

    Return Value

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

    Discussion

    The behavior created by this method acts like a solid rod connecting the item to the specified anchor point. The item is free to rotate around the anchor point, but its distance to the anchor point remains fixed. If you specify a nonzero offset value, the item is connected at the specified point instead of the center of the item.

    The attachment object returned by this method is of type UIAttachmentBehaviorTypeAnchor.

    Availability

    Available in iOS 7.0 and later.

  • Initializes an attachment behavior that connects a specified point in one dynamic item to a specified point in another dynamic item.

    Declaration

    Swift

    init(item item1: UIDynamicItem, offsetFromCenter offset1: UIOffset, attachedToItem item2: UIDynamicItem, offsetFromCenter offset2: UIOffset)

    Objective-C

    - (instancetype)initWithItem:(id<UIDynamicItem>)item1 offsetFromCenter:(UIOffset)p1 attachedToItem:(id<UIDynamicItem>)item2 offsetFromCenter:(UIOffset)p2

    Parameters

    item1

    The first of two dynamic items connected by the attachment behavior.

    p1

    The offset from the center of item1 at which to create the attachment. Specifying UIOffsetZero creates the attachment at the center of item1.

    item2

    The second of two dynamic items connected by the attachment behavior.

    p2

    The offset from the center of item2 at which to create the attachment. Specifying UIOffsetZero creates the attachment at the center of item2.

    Return Value

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

    Discussion

    The behavior created by this method acts like a solid rod connecting the two items at the specified offsets from their center points. Forces applied to one item push or pull the other item accordingly. The items are free to rotate around each other but always remain the same distance apart.

    The attachment object returned by this method is of type UIAttachmentBehaviorTypeItems.

    Availability

    Available in iOS 7.0 and later.

  • The dynamic items connected by the attachment behavior. (read-only)

    Declaration

    Swift

    var items: [UIDynamicItem] { get }

    Objective-C

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

    Discussion

    Contains two elements when used for an attachment behavior of type UIAttachmentBehaviorTypeItems; contains one element when used for an attachment behavior of type UIAttachmentBehaviorTypeAnchor.

    Availability

    Available in iOS 7.0 and later.

  • The anchor point for the attachment behavior, if any.

    Declaration

    Swift

    var anchorPoint: CGPoint

    Objective-C

    @property(readwrite, nonatomic) CGPoint anchorPoint

    Discussion

    The anchor point is relative to the coordinate system for the behavior’s associated dynamic animator. For attachment types without an anchor point, the value in this property is CGPointZero. For more information about the coordinate system of the reference view, see UIDynamicAnimator Class Reference.

    Availability

    Available in iOS 7.0 and later.

  • The type of the attachment behavior. (read-only)

    Declaration

    Swift

    var attachedBehaviorType: UIAttachmentBehaviorType { get }

    Objective-C

    @property(readonly, nonatomic) UIAttachmentBehaviorType attachedBehaviorType

    Discussion

    The available types for attachment behaviors are described in the UIAttachmentBehaviorType enum.

    Availability

    Available in iOS 7.0 and later.

  • The amount of damping to apply to the attachment behavior.

    Declaration

    Swift

    var damping: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat damping

    Availability

    Available in iOS 7.0 and later.

  • The frequency of oscillation for the attachment behavior.

    Declaration

    Swift

    var frequency: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat frequency

    Availability

    Available in iOS 7.0 and later.

  • The distance, in points, between the two attachment points of the attachment behavior.

    Declaration

    Swift

    var length: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat length

    Discussion

    Use this property to adjust the attachment length, if you want to, after creating an attachment. The system sets initial length automatically based on how you initialize the attachment.

    Availability

    Available in iOS 7.0 and later.

  • The amount of force needed to overcome rotational forces around an anchor point.

    Declaration

    Swift

    var frictionTorque: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat frictionTorque

    Discussion

    For attachments where each item rotates around an anchor point, use this property to specify the resistance to that rotation. The default value of this property is 0.0, which causes items to rotate freely with even very small impulses. Higher torque values increase the amount of force needed to cause rotation.

    This property has no formal units, so you need to experiment with values to get the behavior that you want.

    Availability

    Available in iOS 9.0 and later.

  • The range of motion for the attachment behavior.

    Declaration

    Swift

    var attachmentRange: UIFloatRange

    Objective-C

    @property(readwrite, nonatomic) UIFloatRange attachmentRange

    Discussion

    For sliding attachments, this property defines the range of motion (measured in points) supported along the given axis of translation. The specified range must always contain the value 0, which represents the starting point of movement for items. Items slide along the axis between the minimum and maximum values you specify. Setting this property to UIFloatRangeZero prevents items from sliding at all along their axis of translation.

    For pin attachments, this property defines the amount of rotation (measured in radians) supported in the counter-clockwise and clockwise directions. The specified range must contain the value 0, which represents the starting angle of each item. Items rotate around the anchor point between the minimum and maximum values you specify. Setting this property to UIFloatRangeZero prevents items from rotating at all.

    The default value of this property is UIFloatRangeInfinite.

    Availability

    Available in iOS 9.0 and later.

  • Constants indicating the type of the attachment behavior object.

    Declaration

    Swift

    enum UIAttachmentBehaviorType : Int { case Items case Anchor }

    Objective-C

    typedef enum { UIAttachmentBehaviorTypeItems, UIAttachmentBehaviorTypeAnchor } UIAttachmentBehaviorType;

    Constants

    • Items

      UIAttachmentBehaviorTypeItems

      Designates an attachment behavior that connects a dynamic item to another dynamic item.

      Available in iOS 7.0 and later.

    • Anchor

      UIAttachmentBehaviorTypeAnchor

      Designates an attachment behavior that connects a dynamic item to an anchor point.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Constants for specifying standard ranges.

    Declaration

    Swift

    let UIFloatRangeZero: UIFloatRange let UIFloatRangeInfinite: UIFloatRange

    Objective-C

    const UIFloatRange UIFloatRangeZero; const UIFloatRange UIFloatRangeInfinite;

    Constants

    • UIFloatRangeZero

      UIFloatRangeZero

      A range whose minimum and maximum are both 0.0.

      Available in iOS 9.0 and later.

    • UIFloatRangeInfinite

      UIFloatRangeInfinite

      A range whose range is minus infinity to infinity.

      Available in iOS 9.0 and later.