# Titanium.UI.iOS.PushBehavior

> Continuous or instantaneous force to apply to an item.

- Source: https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.UI.iOS.PushBehavior
- Titanium SDK version: 12.6.4
- 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 push behavior configures the continuous or instaneous force to apply to one or more items. To
define a push behavior:

  1. Use the [Titanium.UI.iOS.createPushBehavior](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#createPushBehavior) method to create and define the behavior.
  2. To define a force vector, either set the
     [angle](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.PushBehavior.md#angle) and
     [magnitude](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.PushBehavior.md#magnitude) properties, or set the
     [pushDirection](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.PushBehavior.md#pushDirection) property.
  3. Use the [addItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.PushBehavior.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).

## Example: Simple Example

The following example generates a random push force on the block when it stops.

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

var block = Ti.UI.createView({
    width: 100,
    height: 100,
    backgroundColor: 'blue',
    transform: Ti.UI.createMatrix2D({ rotate: 45 })
});

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

// Push the block down when the application first starts
var push = Ti.UI.iOS.createPushBehavior({
    pushDirection: {x: 0.0, y: 1.0},
    pushMode: Ti.UI.iOS.PUSH_MODE_INSTANTANEOUS
});
push.addItem(block);
animator.addBehavior(push);

// Apply a new push behavior when the item stops
animator.addEventListener('pause', function(e){
    push.angle = 2 * Math.PI * Math.random();
    push.magnitude = Math.random() * 5 + 5;
    push.active = true;
});

animator.addEventListener('resume', function(e){
    Ti.API.info(JSON.stringify(
        'push force: ' + push.magnitude * 100 + " points/s^2 @ "
        + (push.angle * 360 / (2 * Math.PI)) + " degrees")
    );
});

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

win.add(block);
win.open();
```

## Properties

### active

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

State of the push behavior's force.

Set to `true` to activate the force or `false` to deactivate it.  Use this property rather
than removing and re-adding the behavior to the animator.

### angle

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

Specifies the angle of the force vector in radians.

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

### 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 force vector.

A value of 1.0 represents an acceleration of 100 points per second squared if the item is
100 x 100 points with a `density` of 1.0.

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

### pushDirection

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

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

For example, specifiying `{x: 0.0, y: 1.0}` indicates a positive upward force of 100
points per second squared if the item is 100 x 100 points with a `density` of 1.0.

Specifiying a negative value reverses the direction of the force.

### pushMode

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

Specifies the push mode.

Accepts: `Titanium.UI.iOS.PUSH_MODE_CONTINUOUS`, `Titanium.UI.iOS.PUSH_MODE_INSTANTANEOUS`

## 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/12.6.4/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`.