# Titanium.UI.iOS.CollisionBehavior

> Dynamic behavior to support collisions between items and boundaries.

- Source: https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.UI.iOS.CollisionBehavior
- Titanium SDK version: 12.6.2
- 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 collision behavior specifies the behavior when items collide with each other and boundaries.
To define a collision behavior:

  1. Use the [Titanium.UI.iOS.createCollisionBehavior](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#createCollisionBehavior) method to create and define the behavior.
  2. Use the [addItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.CollisionBehavior.md#addItem) method to add items to the behavior.
  3. Use the [addBoundary](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.CollisionBehavior.md#addBoundary) method to add custom
     boundaries for the item to collide with. By default, the behavior uses the Animator
     object's reference view as the boundary.
  4. Add the behavior to an [Animator object](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Animator.md).

## Example: Simple Example

The following example creates many blocks scattered across the top of the window, which
start falling after the window opens.  The item and boundary collisions are reported to the
console.

<img src="./collision.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();

// Listen for collisions
function report(e) {
    Ti.API.info(JSON.stringify(e.type));
};
collision.addEventListener('itemcollision', report);
collision.addEventListener('boundarycollision', report);

// 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 < 25; 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 / 4) + 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();
});

win.open();
```

## Properties

### boundaryIdentifiers

- Type: Array<BoundaryIdentifier>
- Platforms: iPhone, iPad, macOS
- Permission: read-only

Boundary identfiers added to this behavior.

### collisionMode

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `<Titanium.UI.iOS.COLLISION_MODE_ALL>`

Specifies the collision behavior.

Accepts: `Titanium.UI.iOS.COLLISION_MODE_ALL`, `Titanium.UI.iOS.COLLISION_MODE_BOUNDARY`, `Titanium.UI.iOS.COLLISION_MODE_ITEM`

### items

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

Items added to this behavior.

### referenceInsets

- Type: Padding
- Platforms: iPhone, iPad, macOS
- Default: `All insets are zero.`

Insets to apply when using the animator's reference view as the boundary.

The `treatReferenceAsBoundary` property needs to be set to `true` to use this property.

### treatReferenceAsBoundary

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Use the animator's reference view as the boundary.

Set to `true` to enable this behavior or `false` to disable it.

## Methods

### addBoundary

- Platforms: iPhone, iPad, macOS

Adds a boundary to this behavior.

Parameters:

- `boundary` (BoundaryIdentifier): Boundary to add to the behavior.

### addItem

- Platforms: iPhone, iPad, macOS

Adds an item to this behavior.

Parameters:

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

### removeAllBoundaries

- Platforms: iPhone, iPad, macOS

Removes all boundaries from this behavior.

### removeBoundary

- Platforms: iPhone, iPad, macOS

Removes the specified boundary from this behavior.

Parameters:

- `boundary` (BoundaryIdentifier): Boundary to remove.

### removeItem

- Platforms: iPhone, iPad, macOS

Removes the specified item from this behavior.

Parameters:

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

## Events

### boundarycollision

- Platforms: iPhone, iPad, macOS

Fired when an item collides with a boundary.

Event properties:

- `item` (Titanium.UI.View): Item that collided with the boundary.
- `identifier` (String): Identifier of the boundary the item collided with.
- `point` (Point): Point of the collision when it started. Only returned when `start` is `true`.
- `start` (Boolean): Returns `true` if the collision started else `false`.

### itemcollision

- Platforms: iPhone, iPad, macOS

Fired when two items collide.

Event properties:

- `item1` (Titanium.UI.View): Item that collided with `item2`.
- `item2` (Titanium.UI.View): Item that collided with `item1`.
- `point` (Point): Point of the collision when it started. Only returned when `start` is `true`.
- `start` (Boolean): Returns `true` if the collision started else `false`.

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.2/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`.