# Titanium.UI.Matrix2D

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

Availability

8.0.0

9.2.0

Extends

Titanium.Proxy

# Overview

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:

a	b	0
c	d	0
tx	ty	1

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 method to create a new 2D matrix. You can pass an optional Matrix2DCreationDict dictionary to the method to initialize the matrix. For example, the following creates a new matrix with a 45 degree rotation.

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

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

# Examples

# Apply a 2D Matrix to a Label

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

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});

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();

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

# Methods

# invert

Availability

8.0.0

9.2.0

invert() → Titanium.UI.Matrix2D

Returns a matrix constructed by inverting this matrix.

Returns

Type: Titanium.UI.Matrix2D

# multiply

Availability

8.0.0

9.2.0

multiply(t2) → Titanium.UI.Matrix2D

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

Name	Type	Description
`t2`	Titanium.UI.Matrix2D	The second matrix.

Returns

Type: Titanium.UI.Matrix2D

# rotate

Availability

8.0.0

9.2.0

rotate(angle[, toAngle]) → Titanium.UI.Matrix2D

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 property to specify a rotation animation.

Parameters

Name	Type	Description
`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	Ending angle for a rotation animation, in degrees. Android only.

Returns

Type: Titanium.UI.Matrix2D

# scale

Availability

8.0.0

9.2.0

scale(sx, sy[, toSx[, toSy]]) → Titanium.UI.Matrix2D

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 transform property to specify a scaling animation.

Parameters

Name	Type	Description
`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	Ending horizontal scaling factor, at the end of an animation. If specified, `toSy` must be specified as well. Android only.
`toSy`	Number	Ending vertical scaling factor, at the end of an animation. If specified, `toSx` must be specified as well. Android only.

Returns

Type: Titanium.UI.Matrix2D

# translate

Availability

8.0.0

9.2.0

translate(tx, ty) → Titanium.UI.Matrix2D

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

Parameters

Name	Type	Description
`tx`	Number	Horizontal component of the translation.
`ty`	Number	Vertical component of the translation.

Returns

Type: Titanium.UI.Matrix2D