org.eclipse.swt.graphics.Transform Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.swt.win32.win32.x86 Show documentation
SWT is an open source widget toolkit for Java designed to provide efficient, portable access to the user-interface facilities of the operating systems on which it is implemented.
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2012 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.swt.graphics;

import org.eclipse.swt.*;
import org.eclipse.swt.internal.gdip.*;

/**
 * Instances of this class represent transformation matrices for 
 * points expressed as (x, y) pairs of floating point numbers.
 * 
 * Application code must explicitly invoke the Transform.dispose() 
 * method to release the operating system resources managed by each instance
 * when those instances are no longer required.
 * 
 * 
 * This class requires the operating system's advanced graphics subsystem
 * which may not be available on some platforms.
 * 
 * 
 * @see SWT Example: GraphicsExample
 * @see Sample code and further information
 * 
 * @since 3.1
 */
public class Transform extends Resource {

	/**
	 * the OS resource for the Transform
	 * (Warning: This field is platform dependent)
	 * 
	 * IMPORTANT: This field is not part of the SWT
	 * public API. It is marked public only so that it can be shared
	 * within the packages provided by SWT. It is not available on all
	 * platforms and should never be accessed from application code.
	 * 
	 * 
	 * @noreference This field is not intended to be referenced by clients.
	 */
	public int /*long*/ handle;
	
/**
 * Constructs a new identity Transform.
 * 
 * This operation requires the operating system's advanced
 * graphics subsystem which may not be available on some
 * platforms.
 * 
 * 
 * @param device the device on which to allocate the Transform
 * 
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if device is null and there is no current device
 * 
 * @exception SWTException 
 *    ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available
 * 
 * @exception SWTError 
 *    ERROR_NO_HANDLES if a handle for the Transform could not be obtained
 * 
 * 
 * @see #dispose()
 */
public Transform (Device device) {
	this(device, 1, 0, 0, 1, 0, 0);
}

/**
 * Constructs a new Transform given an array of elements that represent the 
 * matrix that describes the transformation.
 * 
 * This operation requires the operating system's advanced
 * graphics subsystem which may not be available on some
 * platforms.
 * 
 * 
 * @param device the device on which to allocate the Transform
 * @param elements an array of floats that describe the transformation matrix
 * 
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null
 *    ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values
 * 
 * @exception SWTException 
 *    ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available
 * 
 * @exception SWTError 
 *    ERROR_NO_HANDLES if a handle for the Transform could not be obtained
 * 
 * 
 * @see #dispose()
 */
public Transform(Device device, float[] elements) {
	this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
}

/**
 * Constructs a new Transform given all of the elements that represent the 
 * matrix that describes the transformation.
 * 
 * This operation requires the operating system's advanced
 * graphics subsystem which may not be available on some
 * platforms.
 * 
 * 
 * @param device the device on which to allocate the Transform
 * @param m11 the first element of the first row of the matrix
 * @param m12 the second element of the first row of the matrix
 * @param m21 the first element of the second row of the matrix
 * @param m22 the second element of the second row of the matrix
 * @param dx the third element of the first row of the matrix
 * @param dy the third element of the second row of the matrix
 * 
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if device is null and there is no current device
 * 
 * @exception SWTException 
 *    ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available
 * 
 * @exception SWTError 
 *    ERROR_NO_HANDLES if a handle for the Transform could not be obtained
 * 
 * 
 * @see #dispose()
 */
public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
	super(device);
	this.device.checkGDIP();
	handle = Gdip.Matrix_new(m11, m12, m21, m22, dx, dy);
	if (handle == 0) SWT.error(SWT.ERROR_NO_HANDLES);
	init();
}

static float[] checkTransform(float[] elements) {
	if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
	if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
	return elements;
}

void destroy() {
	Gdip.Matrix_delete(handle);
	handle = 0;
}

/**
 * Fills the parameter with the values of the transformation matrix
 * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
 *
 * @param elements array to hold the matrix values
 *
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if the parameter is null
 *    ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values
 * 
 */
public void getElements(float[] elements) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
	if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
	Gdip.Matrix_GetElements(handle, elements);
}

/**
 * Modifies the receiver such that the matrix it represents becomes the
 * identity matrix. 
 *
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 * 
 * @since 3.4
 */
public void identity() {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_SetElements(handle, 1, 0, 0, 1, 0, 0);
}

/**
 * Modifies the receiver such that the matrix it represents becomes
 * the mathematical inverse of the matrix it previously represented. 
 *
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 *    ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertible
 * 
 */
public void invert() {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	if (Gdip.Matrix_Invert(handle) != 0) SWT.error(SWT.ERROR_CANNOT_INVERT_MATRIX);
}

/**
 * Returns true if the Transform has been disposed,
 * and false otherwise.
 * 
 * This method gets the dispose state for the Transform.
 * When a Transform has been disposed, it is an error to
 * invoke any other method (except {@link #dispose()}) using the Transform.
 *
 * @return true when the Transform is disposed, and false otherwise
 */
public boolean isDisposed() {
	return handle == 0;
}

/**
 * Returns true if the Transform represents the identity matrix
 * and false otherwise.
 *
 * @return true if the receiver is an identity Transform, and false otherwise
 */
public boolean isIdentity() {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	return Gdip.Matrix_IsIdentity(handle);
}

/**
 * Modifies the receiver such that the matrix it represents becomes the
 * the result of multiplying the matrix it previously represented by the
 * argument. 
 *
 * @param matrix the matrix to multiply the receiver by
 * 
 * @exception SWTException 

 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if the parameter is null
 *    ERROR_INVALID_ARGUMENT - if the parameter has been disposed
 * 
 */
public void multiply(Transform matrix) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
	if (matrix.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
	Gdip.Matrix_Multiply(handle, matrix.handle, Gdip.MatrixOrderPrepend);
}

/**
 * Modifies the receiver so that it represents a transformation that is
 * equivalent to its previous transformation rotated by the specified angle.
 * The angle is specified in degrees and for the identity transform 0 degrees
 * is at the 3 o'clock position. A positive value indicates a clockwise rotation
 * while a negative value indicates a counter-clockwise rotation.
 *
 * @param angle the angle to rotate the transformation by
 * 
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 */
public void rotate(float angle) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_Rotate(handle, angle, Gdip.MatrixOrderPrepend);
}

/**
 * Modifies the receiver so that it represents a transformation that is
 * equivalent to its previous transformation scaled by (scaleX, scaleY).
 * 
 * @param scaleX the amount to scale in the X direction
 * @param scaleY the amount to scale in the Y direction
 * 
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 */
public void scale(float scaleX, float scaleY) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_Scale(handle, scaleX, scaleY, Gdip.MatrixOrderPrepend);
}

/**
 * Modifies the receiver to represent a new transformation given all of
 * the elements that represent the matrix that describes that transformation.
 * 
 * @param m11 the first element of the first row of the matrix
 * @param m12 the second element of the first row of the matrix
 * @param m21 the first element of the second row of the matrix
 * @param m22 the second element of the second row of the matrix
 * @param dx the third element of the first row of the matrix
 * @param dy the third element of the second row of the matrix
 * 
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 */
public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_SetElements(handle, m11, m12, m21, m22, dx, dy);
}

/**
 * Modifies the receiver so that it represents a transformation that is
 * equivalent to its previous transformation sheared by (shearX, shearY).
 * 
 * @param shearX the shear factor in the X direction
 * @param shearY the shear factor in the Y direction
 * 
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 * 
 * @since 3.4
 */
public void shear(float shearX, float shearY) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_Shear(handle, shearX, shearY, Gdip.MatrixOrderPrepend);
}

/** 
 * Given an array containing points described by alternating x and y values,
 * modify that array such that each point has been replaced with the result of
 * applying the transformation represented by the receiver to that point.
 *
 * @param pointArray an array of alternating x and y values to be transformed
 *
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if the point array is null
 * 	
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 */
public void transform(float[] pointArray) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
	Gdip.Matrix_TransformPoints(handle, pointArray, pointArray.length / 2);
}

/**
 * Modifies the receiver so that it represents a transformation that is
 * equivalent to its previous transformation translated by (offsetX, offsetY).
 * 
 * @param offsetX the distance to translate in the X direction
 * @param offsetY the distance to translate in the Y direction
 * 
 * @exception SWTException 
 *    ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
 * 
 */
public void translate(float offsetX, float offsetY) {
	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
	Gdip.Matrix_Translate(handle, offsetX, offsetY, Gdip.MatrixOrderPrepend);
}

/**
 * Returns a string containing a concise, human-readable
 * description of the receiver.
 *
 * @return a string representation of the receiver
 */
public String toString() {
	if (isDisposed()) return "Transform {*DISPOSED*}";
	float[] elements = new float[6];
	getElements(elements);
	return "Transform {" + elements [0] + "," + elements [1] + "," +elements [2] + "," +elements [3] + "," +elements [4] + "," +elements [5] + "}";
}

}