com.trolltech.qt.gui
Class QTransform

java.lang.Object
  com.trolltech.qt.internal.QSignalEmitterInternal
      com.trolltech.qt.QSignalEmitter
          com.trolltech.qt.QtJambiObject
              com.trolltech.qt.gui.QTransform

All Implemented Interfaces:

QtJambiInterface, java.lang.Cloneable

public class QTransform
extends QtJambiObject
implements java.lang.Cloneable

The QTransform class specifies 2D transformations of a coordinate system. A transformation specifies how to translate, scale, shear, rotate or project the coordinate system, and is typically used when rendering graphics.

QTransform differs from QMatrix in that it is a true 3x3 matrix, allowing perspective transformations. QTransform's toAffine() method allows casting QTransform to QMatrix. If a perspective transformation has been specified on the matrix, then the conversion to an affine QMatrix will cause loss of data.

QTransform is the recommended transformation class in Qt.

A QTransform object can be built using the setMatrix(), scale(), rotate(), translate() and shear() functions. Alternatively, it can be built by applying basic matrix operations. The matrix can also be defined when constructed, and it can be reset to the identity matrix (the default) using the reset() function.

The QTransform class supports mapping of graphic primitives: A given point, line, polygon, region, or painter path can be mapped to the coordinate system defined by this matrix using the map() function. In case of a rectangle, its coordinates can be transformed using the mapRect() function. A rectangle can also be transformed into a polygon (mapped to the coordinate system defined by this matrix), using the mapToPolygon() function.

QTransform provides the isIdentity() function which returns true if the matrix is the identity matrix, and the isInvertible() function which returns true if the matrix is non-singular (i.e. AB = BA = I). The inverted() function returns an inverted copy of this matrix if it is invertible (otherwise it returns the identity matrix). In addition, QTransform provides the det() function returning the matrix's determinant.

Finally, the QTransform class supports matrix multiplication, and objects of the class can be streamed as well as compared.

• Rendering Graphics
• Basic Matrix Operations

Rendering Graphics

When rendering graphics, the matrix defines the transformations but the actual transformation is performed by the drawing routines in QPainter.

By default, QPainter operates on the associated device's own coordinate system. The standard coordinate system of a QPaintDevice has its origin located at the top-left position. The x values increase to the right; y values increase downward. For a complete description, see the coordinate system documentation.

QPainter has functions to translate, scale, shear and rotate the coordinate system without using a QTransform. For example:

void SimpleTransformation.paintEvent(QPaintEvent ) { QPainter painter(this); painter.setPen(QPen(Qt.blue, 1, Qt.DashLine)); painter.drawRect(0, 0, 100, 100); painter.rotate(45); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt.black, 1)); painter.drawText(20, 10, "QTransform"); }

Although these functions are very convenient, it can be more efficient to build a QTransform and call QPainter::setTransform() if you want to perform more than a single transform operation. For example:

void CombinedTransformation.paintEvent(QPaintEvent ) { QPainter painter(this); painter.setPen(QPen(Qt.blue, 1, Qt.DashLine)); painter.drawRect(0, 0, 100, 100); QTransform transform; transform.translate(50, 50); transform.rotate(45); transform.scale(0.5, 1.0); painter.setTransform(transform); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt.black, 1)); painter.drawText(20, 10, "QTransform"); }

Basic Matrix Operations

A QTransform object contains a 3 x 3 matrix. The dx and dy elements specify horizontal and vertical translation. The m11 and m22 elements specify horizontal and vertical scaling. The m21 and m12 elements specify horizontal and vertical shearing. And finally, the m13 and m23 elements specify horizontal and vertical projection, with m33 as an additional projection factor.

QTransform transforms a point in the plane to another point using the following formulas:

        x' = m11 + m21 + dx
        y' = m22 + m12 + dy

The point (x, y) is the original point, and (x', y') is the transformed point. (x', y') can be transformed back to (x, y) by performing the same operation on the inverted() matrix.

The various matrix elements can be set when constructing the matrix, or by using the setMatrix() function later on. They can also be manipulated using the translate(), rotate(), scale() and shear() convenience functions, The currently set values can be retrieved using the m11(), m12(), m13(), m21(), m22(), m23(), m31(), m32(), m33(), dx() and dy() functions.

Translation is the simplest transformation. Setting dx and dy will move the coordinate system dx units along the X axis and dy units along the Y axis. Scaling can be done by setting m11 and m22. For example, setting m11 to 2 and m22 to 1.5 will double the height and increase the width by 50%. The identity matrix has m11, m22, and m33 set to 1 (all others are set to 0) mapping a point to itself. Shearing is controlled by m12 and m21. Setting these elements to values different from zero will twist the coordinate system. Rotation is achieved by carefully setting both the shearing factors and the scaling factors. Perspective transformation is achieved by carefully setting both the projection factors and the scaling factors.

Here's the combined transformations example using basic matrix operations:

void BasicOperations.paintEvent(QPaintEvent ) { double pi = 3.14; double a = pi/180 45.0; double sina = sin(a); double cosa = cos(a); QTransform translationTransform(1, 0, 0, 1, 50.0, 50.0); QTransform rotationTransform(cosa, sina, -sina, cosa, 0, 0); QTransform scalingTransform(0.5, 0, 0, 1.0, 0, 0); QTransform transform; transform = scalingTransform rotationTransform translationTransform; QPainter painter(this); painter.setPen(QPen(Qt.blue, 1, Qt.DashLine)); painter.drawRect(0, 0, 100, 100); painter.setTransform(transform); painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt.black, 1)); painter.drawText(20, 10, "QTransform"); }

See also:

QPainter, The Coordinate System, Affine Transformations Demo, and Transformations Example.

Nested Class Summary

static class

QTransform.TransformationType

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter

QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9

Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal

Field Summary

Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

currentSender

Constructor Summary

QTransform()

QTransform(double h11, double h12, double h21, double h22, double dx, double dy)
Constructs a matrix with the elements, h11, h12, h21, h22, dx and dy.

QTransform(double h11, double h12, double h13, double h21, double h22, double h23, double h31, double h32)
Constructs a matrix with the elements, h11, h12, h13, h21, h22, h23, h31, h32, h33.

QTransform(double h11, double h12, double h13, double h21, double h22, double h23, double h31, double h32, double h33)
Constructs a matrix with the elements, h11, h12, h13, h21, h22, h23, h31, h32, h33.

QTransform(QMatrix mtx)
Constructs a matrix that is a copy of the given matrix.

Method Summary

QTransform	add(double d) Adds d to this QTransform.
QTransform	adjoint() Returns the adjoint of this matrix.
QTransform	clone()
double	det() Returns the matrix's determinant.
double	determinant() Returns the matrix's determinant.
QTransform	divide(double d) Divides this QTransform by d.
double	dx() Returns the horizontal translation factor.
double	dy() Returns the vertical translation factor.
static QTransform	fromScale(double dx, double dy) Creates a matrix which corresponds to a scaling of sx horizontally and sy vertically.
static QTransform	fromTranslate(double dx, double dy) Creates a matrix which corresponds to a translation of dx along the x axis and dy along the y axis.
QTransform	inverted() Returns an inverted copy of this transformation.
boolean	isAffine() Returns true if the matrix represent an affine transformation, otherwise returns false.
boolean	isIdentity() Returns true if the matrix is the identity matrix, otherwise returns false.
boolean	isInvertible() Returns true if the matrix is invertible, otherwise returns false.
boolean	isRotating() Returns true if the matrix represents some kind of a rotating transformation, otherwise returns false.
boolean	isScaling() Returns true if the matrix represents a scaling transformation, otherwise returns false.
boolean	isTranslating() Returns true if the matrix represents a translating transformation, otherwise returns false.
double	m11() Returns the horizontal scaling factor.
double	m12() Returns the vertical shearing factor.
double	m13() Returns the horizontal projection factor.
double	m21() Returns the horizontal shearing factor.
double	m22() Returns the vertical scaling factor.
double	m23() Returns the vertical projection factor.
double	m31() Returns the horizontal translation factor.
double	m32() Returns the vertical translation factor.
double	m33() Returns the division factor.
QLine	map(QLine l) This is an overloaded member function, provided for convenience.
QLineF	map(QLineF l) This is an overloaded member function, provided for convenience.
QPainterPath	map(QPainterPath p) This is an overloaded member function, provided for convenience.
QPoint	map(QPoint p) This is an overloaded member function, provided for convenience.
QPointF	map(QPointF p) This is an overloaded member function, provided for convenience.
QPolygon	map(QPolygon a) This is an overloaded member function, provided for convenience.
QPolygonF	map(QPolygonF a) This is an overloaded member function, provided for convenience.
QRegion	map(QRegion r) This is an overloaded member function, provided for convenience.
QRect	mapRect(QRect arg__1) This is an overloaded member function, provided for convenience.
QRectF	mapRect(QRectF arg__1) Creates and returns a QRectF object that is a copy of the given rectangle, mapped into the coordinate system defined by this matrix.
QPolygon	mapToPolygon(QRect r) Creates and returns a QPolygon representation of the given rectangle, mapped into the coordinate system defined by this matrix.
QTransform	multiplied(QTransform o) Multiplies this QTransform with o, and returns the result.
QTransform	multiply(double d) Multiplies this QTransform with d.
QTransform	multiply(QTransform matrix) Returns the result of multiplying this matrix by the given matrix.
static QTransform	quadToQuad(QPolygonF from, QPolygonF to) Creates a transformation mapping one arbitrary quad into another.
static QTransform	quadToSquare(QPolygonF quad) Creates a transformation that maps a quad to a unit square.
void	readFrom(QDataStream arg__1) Reads a QTransform
void	reset() Resets the matrix to an identity matrix, i.
QTransform	rotate(double angle) Rotates the transformation around the z-axis.
QTransform	rotate(double angle, Qt.Axis axis) Rotates the transformation around the given axis.
QTransform	rotateRadians(double angle) Rotates the transformation around the z-axis.
QTransform	rotateRadians(double angle, Qt.Axis axis) Rotates the transformation around the given axis.
QTransform	scale(double x, double y) Scales the transformation using x and y.
void	setMatrix(double m11, double m12, double m13, double m21, double m22, double m23, double m31, double m32, double m33) Sets the matrix elements to the specified values, m11, m12, m13m21, m22, m23m31, m32 and m33.
QTransform	shear(double x, double y) Shears the transformation using x and y.
static QTransform	squareToQuad(QPolygonF quad) Creates a transformation that maps a unit square to a the given quad.
QTransform	subtract(double d) Subtracts d from this QTransform.
QMatrix	toAffine() Returns the QTransform cast to a QMatrix.
java.lang.String	toString()
QTransform	translate(double x, double y) Translates the transformation using x and y.
QTransform	transposed() Returns the transpose of this matrix.
QTransform.TransformationType	type() Returns the transformation type of this matrix.
void	writeTo(QDataStream arg__1) Writes thisQTransform

Methods inherited from class com.trolltech.qt.QtJambiObject

dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr

Methods inherited from class com.trolltech.qt.QSignalEmitter

blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread

Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal

__qt_signalInitialization

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.trolltech.qt.QtJambiInterface

disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership

Constructor Detail

QTransform

public QTransform()

QTransform

public QTransform(QMatrix mtx)

Constructs a matrix that is a copy of the given matrix. Note that the m13, m23, and m33 elements are set to 0, 0, and 1 respectively.

QTransform

public QTransform(double h11,
                  double h12,
                  double h13,
                  double h21,
                  double h22,
                  double h23,
                  double h31,
                  double h32)

Constructs a matrix with the elements, h11, h12, h13, h21, h22, h23, h31, h32, h33.

See also:

setMatrix().

QTransform

public QTransform(double h11,
                  double h12,
                  double h13,
                  double h21,
                  double h22,
                  double h23,
                  double h31,
                  double h32,
                  double h33)

Constructs a matrix with the elements, h11, h12, h13, h21, h22, h23, h31, h32, h33.

See also:

setMatrix().

QTransform

public QTransform(double h11,
                  double h12,
                  double h21,
                  double h22,
                  double dx,
                  double dy)

Constructs a matrix with the elements, h11, h12, h21, h22, dx and dy.

See also:

setMatrix().

Method Detail

adjoint

public final QTransform adjoint()

Returns the adjoint of this matrix.

det

public final double det()

Returns the matrix's determinant.

determinant

public final double determinant()

Returns the matrix's determinant.

dx

public final double dx()

Returns the horizontal translation factor.

See also:

m31(), translate(), and Basic Matrix Operations.

dy

public final double dy()

Returns the vertical translation factor.

See also:

translate(), and Basic Matrix Operations.

isAffine

public final boolean isAffine()

Returns true if the matrix represent an affine transformation, otherwise returns false.

isIdentity

public final boolean isIdentity()

Returns true if the matrix is the identity matrix, otherwise returns false.

See also:

reset().

isInvertible

public final boolean isInvertible()

Returns true if the matrix is invertible, otherwise returns false.

See also:

inverted().

isRotating

public final boolean isRotating()

Returns true if the matrix represents some kind of a rotating transformation, otherwise returns false.

See also:

reset().

isScaling

public final boolean isScaling()

Returns true if the matrix represents a scaling transformation, otherwise returns false.

See also:

reset().

isTranslating

public final boolean isTranslating()

Returns true if the matrix represents a translating transformation, otherwise returns false.

See also:

reset().

m11

public final double m11()

Returns the horizontal scaling factor.

See also:

scale(), and Basic Matrix Operations.

m12

public final double m12()

Returns the vertical shearing factor.

See also:

shear(), and Basic Matrix Operations.

m13

public final double m13()

Returns the horizontal projection factor.

See also:

translate(), and Basic Matrix Operations.

m21

public final double m21()

Returns the horizontal shearing factor.

See also:

shear(), and Basic Matrix Operations.

m22

public final double m22()

Returns the vertical scaling factor.

See also:

scale(), and Basic Matrix Operations.

m23

public final double m23()

Returns the vertical projection factor.

See also:

translate(), and Basic Matrix Operations.

m31

public final double m31()

Returns the horizontal translation factor.

See also:

dx(), translate(), and Basic Matrix Operations.

m32

public final double m32()

Returns the vertical translation factor.

See also:

dy(), translate(), and Basic Matrix Operations.

m33

public final double m33()

Returns the division factor.

See also:

translate(), and Basic Matrix Operations.

map

public final QLine map(QLine l)

This is an overloaded member function, provided for convenience.

Creates and returns a QLineF object that is a copy of the given line, l, mapped into the coordinate system defined by this matrix.

map

public final QLineF map(QLineF l)

This is an overloaded member function, provided for convenience.

Creates and returns a QLine object that is a copy of the given line, mapped into the coordinate system defined by this matrix. Note that the transformed coordinates are rounded to the nearest integer.

map

public final QPainterPath map(QPainterPath p)

This is an overloaded member function, provided for convenience.

Creates and returns a QPainterPath object that is a copy of the given path, mapped into the coordinate system defined by this matrix.

map

public final QPoint map(QPoint p)

This is an overloaded member function, provided for convenience.

Creates and returns a QPoint object that is a copy of the given point, mapped into the coordinate system defined by this matrix. Note that the transformed coordinates are rounded to the nearest integer.

map

public final QPointF map(QPointF p)

This is an overloaded member function, provided for convenience.

Creates and returns a QPointF object that is a copy of the given point, p, mapped into the coordinate system defined by this matrix.

map

public final QPolygon map(QPolygon a)

This is an overloaded member function, provided for convenience.

Creates and returns a QPolygon object that is a copy of the given polygon, mapped into the coordinate system defined by this matrix. Note that the transformed coordinates are rounded to the nearest integer.

map

public final QPolygonF map(QPolygonF a)

This is an overloaded member function, provided for convenience.

Creates and returns a QPolygonF object that is a copy of the given polygon, mapped into the coordinate system defined by this matrix.

map

public final QRegion map(QRegion r)

This is an overloaded member function, provided for convenience.

Creates and returns a QRegion object that is a copy of the given region, mapped into the coordinate system defined by this matrix.

Calling this method can be rather expensive if rotations or shearing are used.

mapRect

public final QRect mapRect(QRect arg__1)

This is an overloaded member function, provided for convenience.

Creates and returns a QRect object that is a copy of the given rectangle, mapped into the coordinate system defined by this matrix. Note that the transformed coordinates are rounded to the nearest integer.

mapRect

public final QRectF mapRect(QRectF arg__1)

Creates and returns a QRectF object that is a copy of the given rectangle, mapped into the coordinate system defined by this matrix.

The rectangle's coordinates are transformed using the following formulas:

        x' = m11 + m21 + dx
        y' = m22 + m12 + dy
        if (is not affine) {
            w' = m13 + m23 + m33
            x' /= w'
            y' /= w'
        }

If rotation or shearing has been specified, this function returns the bounding rectangle. To retrieve the exact region the given rectangle maps to, use the mapToPolygon() function instead.

See also:

mapToPolygon(), and Basic Matrix Operations.

mapToPolygon

public final QPolygon mapToPolygon(QRect r)

Creates and returns a QPolygon representation of the given rectangle, mapped into the coordinate system defined by this matrix.

The rectangle's coordinates are transformed using the following formulas:

        x' = m11 + m21 + dx
        y' = m22 + m12 + dy
        if (is not affine) {
            w' = m13 + m23 + m33
            x' /= w'
            y' /= w'
        }

Polygons and rectangles behave slightly differently when transformed (due to integer rounding), so matrix.map(QPolygon(rectangle)) is not always the same as matrix.mapToPolygon(rectangle).

See also:

mapRect(), and Basic Matrix Operations.

multiplied

public final QTransform multiplied(QTransform o)

Multiplies this QTransform with o, and returns the result.

writeTo

public final void writeTo(QDataStream arg__1)

Writes thisQTransform

readFrom

public final void readFrom(QDataStream arg__1)

Reads a QTransform

reset

public final void reset()

Resets the matrix to an identity matrix, i. . all elements are set to zero, except m11 and m22 (specifying the scale) which are set to 1.

See also:

QTransform(), isIdentity(), and Basic Matrix Operations.

setMatrix

public final void setMatrix(double m11,
                            double m12,
                            double m13,
                            double m21,
                            double m22,
                            double m23,
                            double m31,
                            double m32,
                            double m33)

Sets the matrix elements to the specified values, m11, m12, m13m21, m22, m23m31, m32 and m33. Note that this function replaces the previous values. QMatrix provides the translate(), rotate(), scale() and shear() convenience functions to manipulate the various matrix elements based on the currently defined coordinate system.

See also:

QTransform().

toAffine

public final QMatrix toAffine()

Returns the QTransform cast to a QMatrix.

transposed

public final QTransform transposed()

Returns the transpose of this matrix.

type

public final QTransform.TransformationType type()

Returns the transformation type of this matrix.

The transformation type is the highest enumeration value capturing all of the matrix's transformations. For example, if the matrix both scales and shears, the type would be TxShear, because TxShear has a higher enumeration value than TxScale.

Knowing the transformation type of a matrix is useful for optimization: you can often handle specific types more optimally than handling the generic case.

fromScale

public static QTransform fromScale(double dx,
                                   double dy)

Creates a matrix which corresponds to a scaling of sx horizontally and sy vertically. This is the same as QTransform().scale(sx, sy) but slightly faster.

fromTranslate

public static QTransform fromTranslate(double dx,
                                       double dy)

Creates a matrix which corresponds to a translation of dx along the x axis and dy along the y axis. This is the same as QTransform().translate(dx, dy) but slightly faster.

multiply

public final QTransform multiply(double d)

Multiplies this QTransform with d.

multiply

public final QTransform multiply(QTransform matrix)

Returns the result of multiplying this matrix by the given matrix.

Note that matrix multiplication is not commutative, i.e. a*b != b*a.

add

public final QTransform add(double d)

Adds d to this QTransform. d

divide

public final QTransform divide(double d)

Divides this QTransform by d.

subtract

public final QTransform subtract(double d)

Subtracts d from this QTransform.

inverted

public final QTransform inverted()

Returns an inverted copy of this transformation.

Returns:

The inverse of the transformation.

Throws:

java.lang.IllegalArgumentException - If this transformation is not invertible.

quadToQuad

public static final QTransform quadToQuad(QPolygonF from,
                                          QPolygonF to)

Creates a transformation mapping one arbitrary quad into another.

Returns:

The transformation.

Throws:

java.lang.IllegalArgumentException - If this transformation is not possible.

quadToSquare

public static final QTransform quadToSquare(QPolygonF quad)

Creates a transformation that maps a quad to a unit square.

Returns:

The transformation.

Throws:

java.lang.IllegalArgumentException - If this transformation is not possible.

squareToQuad

public static final QTransform squareToQuad(QPolygonF quad)

Creates a transformation that maps a unit square to a the given quad.

Returns:

The transformation.

Throws:

java.lang.IllegalArgumentException - If this transformation is not possible.

rotate

public final QTransform rotate(double angle,
                               Qt.Axis axis)

Rotates the transformation around the given axis.

Returns:

The rotated transformation.

rotate

public final QTransform rotate(double angle)

Rotates the transformation around the z-axis.

Returns:

The rotated transformation.

rotateRadians

public final QTransform rotateRadians(double angle,
                                      Qt.Axis axis)

Rotates the transformation around the given axis.

Returns:

The rotated transformation.

rotateRadians

public final QTransform rotateRadians(double angle)

Rotates the transformation around the z-axis.

Returns:

The rotated transformation.

scale

public final QTransform scale(double x,
                              double y)

Scales the transformation using x and y.

Returns:

The scaled transformation.

shear

public final QTransform shear(double x,
                              double y)

Shears the transformation using x and y.

Returns:

The sheared transformation.

translate

public final QTransform translate(double x,
                                  double y)

Translates the transformation using x and y.

Returns:

The translated transformation.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clone

public QTransform clone()

Overrides:

clone in class java.lang.Object