# Titanium.UI.Matrix2D

> The 2D Matrix is an object for holding values for an affine transformation matrix.

- Source: https://titaniumsdk.com/docs/sdk/12.7.1/Titanium.UI.Matrix2D
- Titanium SDK version: 12.7.1
- Kind: proxy
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 8.0.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

A 2D matrix is used to rotate, scale, translate, or skew the objects in a two-dimensional space.
A 2D affine transformation can be  represented by a 3 by 3 matrix:

<table>
  <tbody>
    <tr>
      <td><i>a</i></td>
      <td><i>b</i></td>
      <td>0</td>
    </tr>
    <tr>
      <td><i>c</i></td>
      <td><i>d</i></td>
      <td>0</td>
    </tr>
    <tr>
      <td><i>tx</i></td>
      <td><i>ty</i></td>
      <td>1</td>
    </tr>
  </tbody>
</table>

The third column is constant (0,0,1).

On iOS, the matrix terms, `a`, `b`, `c`, `d`, `tx`, and `ty`,
are available as properties. On Android, the matrix terms are not available as properties.

Use the [Titanium.UI.createMatrix2D](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createMatrix2D) method to create a new 2D matrix. You can
pass an optional [Matrix2DCreationDict](https://titaniumsdk.com/docs/sdk/Matrix2DCreationDict.md) dictionary to the method to initialize the
matrix. For example, the following creates a new matrix with a 45 degree rotation.

``` js
var matrix = Ti.UI.createMatrix2D({
    rotate: 45
});
```

If you pass no arguments, `createMatrix2D` returns an identity matrix.

## Example: Apply a 2D Matrix to a Label

The following uses a 2D matrix to translate a label in the y direction.

``` js
var win = Ti.UI.createWindow();

var label = Ti.UI.createLabel({
  font: { fontSize: 50 },
  text: 'Titanium',
  textAlign: 'center',
  top: 100
});
win.add(label);

var button = Ti.UI.createButton({
  title: 'Animate',
  bottom: 20,
  width: 200,
  height: 40
});
win.add(button);

button.addEventListener('click', function() {
  var t1 = Ti.UI.createMatrix2D();
  t1 = t1.translate(0, 300);
  var a1 = Ti.UI.createAnimation();
  a1.transform = t1;
  a1.duration = 800;
  label.animate(a1);
});
win.open();
```

## Properties

### a

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [1,1] in the matrix.

### b

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [1,2] in the matrix.

### c

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [2,1] in the matrix.

### d

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [2,2] in the matrix.

### tx

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [3,1] in the matrix.

### ty

- Type: Number
- Platforms: iPhone, iPad, macOS

The entry at position [3,2] in the matrix.

## Methods

### invert

- Platforms: Android, iPhone, iPad, macOS

Returns a matrix constructed by inverting this matrix.

Returns: Titanium.UI.Matrix2D

### multiply

- Platforms: Android, iPhone, iPad, macOS

Returns a matrix constructed by combining two existing matrices.

The argument, `t2` is concatenated to the matrix instance against which the function is invoked. The
resulting matrix is the result of multiplying this matrix by `t2`. You might perform several
multiplications in order to create a single matrix that contains the cumulative effects of
several transformations.

Note that matrix operations are not commutative -- the order in which you concatenate matrices
is important. That is, the result of multiplying matrix `t1` by matrix `t2` does not necessarily
equal the result of multiplying matrix `t2` by matrix `t1`.

Parameters:

- `t2` (Titanium.UI.Matrix2D): The second matrix.

Returns: Titanium.UI.Matrix2D

### rotate

- Platforms: Android, iPhone, iPad, macOS

Returns a matrix constructed by rotating this matrix.

There are two distinct versions of this method, depending on whether one argument
or two are specified.

*   `rotate(angle)`. The standard `rotate` method.
*   `rotate(fromAngle, toAngle)`. Android only. Used for specifying rotation
    animations.

In both cases, a positive value specifies clockwise rotation and a negative value
specifies counter-clockwise rotation.

Details for each version are discussed below.

#### rotate(angle)

Returns a matrix constructed by rotating this matrix.

Note that the resulting  matrix only expresses the final transformation, not the
direction of the rotation. For example, the matrix produced by `m1.rotate(-10)`
is identical to the matrix produced by `m1.rotate(350)` and `m1.rotate(710)`.

Note that if you specify a rotation matrix as the `transform` property of an
animation, the animation animates the view from its current rotation to the
rotation represented by the matrix by its shortest path. So to rotate a view
in a complete circle, the easiest method is to chain together three animations,
rotating 120 degrees each time.

For the purposes of animation, it should be noted that the rotation angle is
normalized to the range -180 <= angle < 180. In other
words, an angle of 180 degrees is normalized to -180. This makes no difference
except when determining which direction an animation rotates. 179 degrees rotates
rotate clockwise, but 180 degrees is normalized to -180, so rotates counter-clockwise.

#### rotate(angle, toAngle) -- Android Only

This is an Android-specific method used for creating rotation animations.
Returns a `Matrix2D` object that represents a rotation from `angle` to `toAngle`.

Angles are specified in degrees. Positive values represent clockwise rotation, and negative values
represent counter-clockwise rotation. Values are not normalized, so for example an
angle of 720 degrees represents two complete clockwise revolutions.

The resulting object cannot be expressed as an affine transform, but can be used with the
[Titanium.UI.Animation.transform](https://titaniumsdk.com/docs/sdk/Titanium.UI.Animation.md#transform) property to specify a rotation animation.

Parameters:

- `angle` (Number): Angle to rotate to, in degrees. On Android, if `toAngle` is specified, this specifies the starting angle for a rotation animation.
- `toAngle` (Number, optional): Ending angle for a rotation animation, in degrees. Android only.

Returns: Titanium.UI.Matrix2D

### scale

- Platforms: Android, iPhone, iPad, macOS

Returns a `Matrix2D` object that specifies a scaling animation from one scale to another.

There are two distinct versions of this method, depending on whether two arguments
or four are specified.

*   `scale(sx, sy)`. The standard `scale` method.
*   `scale(fromSx, fromSy, toSx, toSy)`. Android only. Used for specifying a
    scaling animation from one size to another.

#### scale(sx, sy)

Returns a matrix constructed by applying a scale transform to this matrix.
Scaling the current matrix by `sx` along the X axis and by `sy` along the Y axis.

#### scale(sx, sy, toSx, toSy) -- Android Only

This Android-specific method returns a `Matrix2D` object that can be used to
create a scaling animation from one scale factor to another scale factor.

The resulting object cannot be expressed as an affine transform, but can be used with the
[Titanium.UI.Animation.transform](https://titaniumsdk.com/docs/sdk/Titanium.UI.Animation.md#transform) property to specify a scaling animation.

Parameters:

- `sx` (Number): Horizontal scaling factor. If `toSx` and `toSy` are specified, this specifies the starting horizontal scaling factor, at the beginning of an animation.
- `sy` (Number): Vertical scaling factor. If `toSx` and `toSy` are specified, this specifies the starting vertical scaling factor, at the beginning of an animation.
- `toSx` (Number, optional): Ending horizontal scaling factor, at the end of an animation. If specified, `toSy` must be specified as well. Android only.
- `toSy` (Number, optional): Ending vertical scaling factor, at the end of an animation. If specified, `toSx` must be specified as well. Android only.

Returns: Titanium.UI.Matrix2D

### translate

- Platforms: Android, iPhone, iPad, macOS

Returns a matrix constructed by applying a translation transform to this matrix.

Parameters:

- `tx` (Number): Horizontal component of the translation.
- `ty` (Number): Vertical component of the translation.

Returns: Titanium.UI.Matrix2D

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.7.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `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`.