iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIGravityBehavior Class Reference

Options
Deployment Target:

On This Page
Language:

UIGravityBehavior

A UIGravityBehavior object applies a gravity-like force to all of its associated dynamic items. The magnitude and direction of the gravity force are configurable and are applied equally to all associated items. Use this behavior to modify the position of views and other dynamic items in your app’s interface.

You specify the magnitude and direction of the gravity force as a two-dimensional vector in the reference view’s coordinate system. A value of 1.0 imparts the standard UIKit gravity, which corresponds to an acceleration of 1000 points / second² in the direction of the given axis. The default vector in the gravityDirection property is (0.0, 1.0), which causes items to accelerate downward along the positive y axis. If you prefer to set the vector angle and magnitude separately, you can do so using the corresponding properties.

If you want to influence a gravity behavior at each step of a dynamic animation, assign an appropriate block to the inherited action property. Use your block to make any needed changes to the dynamic items associated with the gravity behavior.

Applying a Gravity Behavior to an Item

To apply a gravity behavior to one or more dynamic items, do the following:

  1. Initialize the behavior using the initWithItems: method, passing in the items you want associated with the behavior. Use the addItem: method to add items after initialization. For more information about dynamic items, see UIDynamicItem Protocol Reference.

  2. Enable the gravity behavior by adding it to your UIDynamicAnimator object using the addBehavior: method. (Do not add more than one gravity behavior to an animator.)

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

  • init(items:) - initWithItems: Designated Initializer

    Initializes a gravity behavior with an array of dynamic items.

    Declaration

    Swift

    init(items items: [UIDynamicItem])

    Objective-C

    - (instancetype)initWithItems:(NSArray<id<UIDynamicItem>> *)items

    Parameters

    items

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

    Return Value

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

    Availability

    Available in iOS 7.0 and later.

  • The set of dynamic items associated with the gravity behavior. (read-only)

    Declaration

    Swift

    var items: [UIDynamicItem] { get }

    Objective-C

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

    Availability

    Available in iOS 7.0 and later.

  • Associates the specified dynamic item with the gravity behavior.

    Declaration

    Swift

    func addItem(_ item: UIDynamicItem)

    Objective-C

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

    Parameters

    item

    The dynamic item to add to the item array. If the specified item is already associated with the gravity behavior, this method does nothing.

    Discussion

    Use this method to add new dynamic items to the gravity behavior after initialization. All the dynamic items added to a gravity behavior are subject to the same gravity vector.

    If the gravity behavior has an associated dynamic animator, this method notifies the dynamic animator of the presence of the new item so that it can initiate any needed animations.

    Availability

    Available in iOS 7.0 and later.

  • Removes the specified dynamic item from the gravity behavior.

    Declaration

    Swift

    func removeItem(_ item: UIDynamicItem)

    Objective-C

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

    Parameters

    item

    The dynamic item that you want to remove. If the specified item is not associated with the behavior, this method does nothing.

    Discussion

    If the gravity behavior has an associated dynamic animator, this method notifies the dynamic animator of the removal of the item so that it can stop any associated animations.

    Availability

    Available in iOS 7.0 and later.

  • The direction and magnitude of the gravitational force, expressed as a vector.

    Declaration

    Swift

    var gravityDirection: CGVector

    Objective-C

    @property(readwrite, nonatomic) CGVector gravityDirection

    Discussion

    The gravity vector is expressed as an x, y pair that represents the relative motion along the x and y axes of the reference view. A value of 1.0 corresponds to an acceleration of 1000 points / second², which is referred to as UIKit gravity and approximates the Earth’s own gravitational force. A value of -1.0 represents the same amount of force, but in the opposite direction of the corresponding axis.

    The default value of this property is the vector (0.0, 1.0), which represents a downward force in the reference view. Changing the angle or magnitude values also changes the value of this property.

    Availability

    Available in iOS 7.0 and later.

    See Also

    angle

  • The direction of the gravity vector, expressed in radians in the reference coordinate system.

    Declaration

    Swift

    var angle: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat angle

    Discussion

    Modify this property when you want to change the angle of the gravity vector separately from the magnitude of that vector. The value in this property is tied to the value in the gravityDirection property, so changes in one affect the other.

    The default angle is pi / 2 radians, which represents a downward force in the reference view. A value of 0 represents a force that moves items toward the right side of the reference view.

    Availability

    Available in iOS 7.0 and later.

  • The magnitude of the gravity vector.

    Declaration

    Swift

    var magnitude: CGFloat

    Objective-C

    @property(readwrite, nonatomic) CGFloat magnitude

    Discussion

    Modify this property when you want to change the magnitude of the gravity vector separately from the angle of that vector. A magnitude value of 1.0 represents an acceleration of 1000 points / second² at the specified angle, which roughly approximates the force of Earth’s gravity. The value in this property is tied to the value in the gravityDirection property, so changes in one affect the other.

    The default value of this property is 1.0.

    Availability

    Available in iOS 7.0 and later.

  • Sets the angle and magnitude of the gravity 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 radian angle for the gravity vector, using standard UIKit geometry. Specify the value pi / 2 to create a force that pulls items downward toward the bottom of the reference view.

    magnitude

    The magnitude of the gravitational force. Specify 1.0 to get the standard UIKit gravity, which has an acceleration value of 1000 points / second².

    Availability

    Available in iOS 7.0 and later.

    See Also

    angle
    magnitude