# Titanium.UI.iOS.GravityBehavior

> Gravitational force to apply to an item.

- Source: https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.UI.iOS.GravityBehavior
- Titanium SDK version: 13.0.1
- Kind: proxy
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

A gravity behavior configures the gravity vector of one or more items. To define a gravity
behavior:

  1. Use the [Titanium.UI.iOS.createGravityBehavior](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#createGravityBehavior) method to create and define the behavior.
  2. To define a gravity vector, either set the
     [angle](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#angle) and
     [magnitude](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#magnitude) properties, or set the
     [gravityDirection](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#gravityDirection) property.
  3. Use the [addItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#addItem) method to add items to the behavior.
  4. Add the behavior to an [Animator object](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Animator.md).

You can only define one gravity behavior per animator.

## Example: Simple Example

The following example creates many random blocks.  The initial gravitational force pulls the
blocks downward. Clicking on the `Change` button generates a new random gravity vector,
which pulls the blocks in a random direction.

<img src="./gravity.gif" height="455" style="border:1px solid black"/>

``` js
var win = Ti.UI.createWindow({backgroundColor: 'white', fullscreen: true});

// Create an Animator object using the window as the coordinate system
var animator = Ti.UI.iOS.createAnimator({referenceView: win});

// Create a default collision behavior, using the window edges as boundaries
var collision = Ti.UI.iOS.createCollisionBehavior();

// Simulate Earth's gravity
var gravity = Ti.UI.iOS.createGravityBehavior({
    gravityDirection: {x: 0.0, y: 1.0}
});

var WIDTH = Ti.Platform.displayCaps.platformWidth;
var HEIGHT = Ti.Platform.displayCaps.platformHeight;

// Create a bunch of random blocks; add to the window and behaviors
var blocks = [];
for (var i = 0; i < 20; i++) {
    var r = Math.round(Math.random() * 255);
    var g = Math.round(Math.random() * 255);
    var b = Math.round(Math.random() * 255);
    var rgb = 'rgb(' + r +"," + g + "," + b + ")";

    blocks[i] = Ti.UI.createView({
        width: 25,
        height: 25,
        top: Math.round(Math.random() * (HEIGHT - 25) + 25),
        left: Math.round(Math.random() * (WIDTH - 25) + 25),
        backgroundColor: rgb
    });
    win.add(blocks[i]);
    collision.addItem(blocks[i]);
    gravity.addItem(blocks[i]);
}

animator.addBehavior(collision);
animator.addBehavior(gravity);
            
// Start the animation when the window opens
win.addEventListener('open', function(e){
    animator.startAnimator();
});

// Change the gravity vector when the button is clicked
var button = Ti.UI.createButton({title: 'Change'});
button.addEventListener('click', function(e){
    gravity.gravityDirection = {
        x: (1 - Math.random() * 2),
        y: (1 - Math.random() * 2)
    };
    Ti.API.info('gravity vector: ' + JSON.stringify(gravity.gravityDirection));
});
win.add(button);
win.open();
```

## Properties

### angle

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `0`

Specifies the angle of the gravity vector in radians.

To configure the gravity vector, you need to also specify the
[magnitude](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#magnitude) property.

### gravityDirection

- Type: Point
- Platforms: iPhone, iPad, macOS
- Default: `(0, 0)`

Specifies the direction of the gravity vector as an x, y pair.

For example, specifiying `{x: 0.0, y: 1.0}` indicates a downward gravity force of 1000
points per second squared.

### items

- Type: Array<Titanium.UI.View>
- Platforms: iPhone, iPad, macOS
- Permission: read-only

Items added to this behavior.

### magnitude

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `0`

Specifies the magnitude of the gravity vector.

A value of 1.0 represents an acceleration of 1000 points per second squared.

To configure the gravity vector, you need to also specify the
[angle](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.GravityBehavior.md#angle) property.

## Methods

### addItem

- Platforms: iPhone, iPad, macOS

Adds an item to this behavior.

Parameters:

- `item` (Titanium.UI.View): View object to add to the behavior.

### removeItem

- Platforms: iPhone, iPad, macOS

Removes the specified item from this behavior.

Parameters:

- `item` (Titanium.UI.View): Item to remove.

## Inherited members

6 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.