Titanium.UI.Matrix2D

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

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:

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.

Extends: Titanium.Proxy · Since: 8.0.0 · Platforms: android, iphone, ipad, macos

Properties #

a#

Type: Number

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

apiName#

extended

Type: String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.

b#

Type: Number

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

bubbleParent#

extended

Type: Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.

c#

Type: Number

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

d#

Type: Number

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

lifecycleContainer#

extended

Type: Titanium.UI.Window, Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.

tx#

Type: Number

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

ty#

Type: Number

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

Methods #

addEventListener #

extended

Adds the specified callback as an event listener for the named event.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to invoke when the event is fired.	No

applyProperties #

extended

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.

Parameters:

Name	Type	Summary	Optional
`props`	`Dictionary`	A dictionary of properties to apply.	No

fireEvent #

extended

Fires a synthesized event to any registered listeners.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`event`	`Dictionary`	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.	Yes

invert #

Returns a matrix constructed by inverting this matrix.

Returns: Titanium.UI.Matrix2D

multiply #

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	Summary	Optional
`t2`	`Titanium.UI.Matrix2D`	The second matrix.	No

Returns: Titanium.UI.Matrix2D

removeEventListener #

extended

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function
in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to remove. Must be the same function passed to `addEventListener`.	No

rotate #

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	Summary	Optional
`angle`	`Number`	Angle to rotate to, in degrees. On Android, if `toAngle` is specified, this specifies the starting angle for a rotation animation.	No
`toAngle`	`Number`	Ending angle for a rotation animation, in degrees. Android only.	Yes

Returns: Titanium.UI.Matrix2D

scale #

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

Parameters:

Name	Type	Summary	Optional
`sx`	`Number`	Horizontal scaling factor. If `toSx` and `toSy` are specified, this specifies the starting horizontal scaling factor, at the beginning of an animation.	No
`sy`	`Number`	Vertical scaling factor. If `toSx` and `toSy` are specified, this specifies the starting vertical scaling factor, at the beginning of an animation.	No
`toSx`	`Number`	Ending horizontal scaling factor, at the end of an animation. If specified, `toSy` must be specified as well. Android only.	Yes
`toSy`	`Number`	Ending vertical scaling factor, at the end of an animation. If specified, `toSx` must be specified as well. Android only.	Yes

Returns: Titanium.UI.Matrix2D

translate #

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

Parameters:

Name	Type	Summary	Optional
`tx`	`Number`	Horizontal component of the translation.	No
`ty`	`Number`	Vertical component of the translation.	No

Returns: Titanium.UI.Matrix2D

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

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

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.UI.Matrix2D ​

Properties #

a#

apiName#

b#

bubbleParent#

c#

d#

lifecycleContainer#

tx#

ty#

Methods #

addEventListener #

applyProperties #

fireEvent #

invert #

multiply #

removeEventListener #

rotate #

rotate(angle)

rotate(angle, toAngle) -- Android Only

scale #

scale(sx, sy)

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

translate #

Examples #

Apply a 2D Matrix to a Label

Titanium.UI.Matrix2D