- /*
- * @(#)Size2DSyntax.java 1.3 03/01/23
- *
- * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
- * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- */
-
-
- package javax.print.attribute;
-
- import java.io.Serializable;
-
- /**
- * Class Size2DSyntax is an abstract base class providing the common
- * implementation of all attributes denoting a size in two dimensions.
- * <P>
- * A two-dimensional size attribute's value consists of two items, the X
- * dimension and the Y dimension. A two-dimensional size attribute may be
- * constructed by supplying the two values and indicating the units in which the
- * values are measured. Methods are provided to return a two-dimensional size
- * attribute's values, indicating the units in which the values are to be
- * returned. The two most common size units are inches (in) and millimeters
- * (mm), and exported constants {@link #INCH <CODE>INCH</CODE>} and {@link #MM
- * <CODE>MM</CODE>} are provided for indicating those units.
- * <P>
- * Once constructed, a two-dimensional size attribute's value is immutable.
- * <P>
- * <B>Design</B>
- * <P>
- * A two-dimensional size attribute's X and Y dimension values are stored
- * internally as integers in units of micrometers (µm), where 1 micrometer
- * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits
- * dimensions to be represented exactly to a precision of 1/1000 mm (= 1
- * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
- * negative powers of two, this permits dimensions to be represented exactly to
- * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
- * does not equal an integral number of µm).
- * <P>
- * Storing the dimensions internally in common units of µm lets two size
- * attributes be compared without regard to the units in which they were
- * created; for example, 8.5 in will compare equal to 215.9 mm, as they both are
- * stored as 215900 µm. For example, a lookup service can
- * match resolution attributes based on equality of their serialized
- * representations regardless of the units in which they were created. Using
- * integers for internal storage allows precise equality comparisons to be done,
- * which would not be guaranteed if an internal floating point representation
- * were used. Note that if you're looking for U.S. letter sized media in metric
- * units, you have to search for a media size of 215.9 x 279.4 mm; rounding off
- * to an integral 216 x 279 mm will not match.
- * <P>
- * The exported constant {@link #INCH <CODE>INCH</CODE>} is actually the
- * conversion factor by which to multiply a value in inches to get the value in
- * µm. Likewise, the exported constant {@link #MM <CODE>MM</CODE>} is the
- * conversion factor by which to multiply a value in mm to get the value in
- * µm. A client can specify a resolution value in units other than inches
- * or mm by supplying its own conversion factor. However, since the internal
- * units of µm was chosen with supporting only the external units of inch
- * and mm in mind, there is no guarantee that the conversion factor for the
- * client's units will be an exact integer. If the conversion factor isn't an
- * exact integer, resolution values in the client's units won't be stored
- * precisely.
- * <P>
- *
- * @author Alan Kaminsky
- */
- public abstract class Size2DSyntax implements Serializable, Cloneable {
-
- /**
- * X dimension in units of micrometers (µm).
- * @serial
- */
- private int x;
-
- /**
- * Y dimension in units of micrometers (µm).
- * @serial
- */
- private int y;
-
- /**
- * Value to indicate units of inches (in). It is actually the conversion
- * factor by which to multiply inches to yield µm (25400).
- */
- public static final int INCH = 25400;
-
- /**
- * Value to indicate units of millimeters (mm). It is actually the
- * conversion factor by which to multiply mm to yield µm (1000).
- */
- public static final int MM = 1000;
-
-
- /**
- * Construct a new two-dimensional size attribute from the given
- * floating-point values.
- *
- * @param x X dimension.
- * @param y Y dimension.
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @exception IllegalArgumentException
- * (Unchecked exception) Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE>
- * < 0 or <CODE>units</CODE> < 1.
- */
- protected Size2DSyntax(float x, float y, int units) {
- if (x < 0.0f) {
- throw new IllegalArgumentException("x < 0");
- }
- if (y < 0.0f) {
- throw new IllegalArgumentException("y < 0");
- }
- if (units < 1) {
- throw new IllegalArgumentException("units < 1");
- }
- this.x = (int) (x * units + 0.5f);
- this.y = (int) (y * units + 0.5f);
- }
-
- /**
- * Construct a new two-dimensional size attribute from the given integer
- * values.
- *
- * @param x X dimension.
- * @param y Y dimension.
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @exception IllegalArgumentException
- * (Unchecked exception) Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE>
- * < 0 or <CODE>units</CODE> < 1.
- */
- protected Size2DSyntax(int x, int y, int units) {
- if (x < 0) {
- throw new IllegalArgumentException("x < 0");
- }
- if (y < 0) {
- throw new IllegalArgumentException("y < 0");
- }
- if (units < 1) {
- throw new IllegalArgumentException("units < 1");
- }
- this.x = x * units;
- this.y = y * units;
- }
-
- /**
- * Convert a value from micrometers to some other units. The result is
- * returned as a floating-point number.
- *
- * @param x
- * Value (micrometers) to convert.
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @return The value of <CODE>x</CODE> converted to the desired units.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
- */
- private static float convertFromMicrometers(int x, int units) {
- if (units < 1) {
- throw new IllegalArgumentException("units is < 1");
- }
- return ((float)x) / ((float)units);
- }
-
- /**
- * Get this two-dimensional size attribute's dimensions in the given units
- * as floating-point values.
- *
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @return A two-element array with the X dimension at index 0 and the Y
- * dimension at index 1.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
- */
- public float[] getSize(int units) {
- return new float[] {getX(units), getY(units)};
- }
-
- /**
- * Returns this two-dimensional size attribute's X dimension in the given
- * units as a floating-point value.
- *
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @return X dimension.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
- */
- public float getX(int units) {
- return convertFromMicrometers(x, units);
- }
-
- /**
- * Returns this two-dimensional size attribute's Y dimension in the given
- * units as a floating-point value.
- *
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- *
- * @return Y dimension.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
- */
- public float getY(int units) {
- return convertFromMicrometers(y, units);
- }
-
- /**
- * Returns a string version of this two-dimensional size attribute in the
- * given units. The string takes the form <CODE>"<I>X</I>x<I>Y</I>
- * <I>U</I>"</CODE>, where <I>X</I> is the X dimension, <I>Y</I> is the Y
- * dimension, and <I>U</I> is the units name. The values are displayed in
- * floating point.
- *
- * @param units
- * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
- * {@link #MM <CODE>MM</CODE>}.
- * @param unitsName
- * Units name string, e.g. <CODE>"in"</CODE> or <CODE>"mm"</CODE>. If
- * null, no units name is appended to the result.
- *
- * @return String version of this two-dimensional size attribute.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
- */
- public String toString(int units, String unitsName) {
- StringBuffer result = new StringBuffer();
- result.append(getX (units));
- result.append('x');
- result.append(getY (units));
- if (unitsName != null) {
- result.append(' ');
- result.append(unitsName);
- }
- return result.toString();
- }
-
- /**
- * Returns whether this two-dimensional size attribute is equivalent to the
- * passed in object. To be equivalent, all of the following conditions must
- * be true:
- * <OL TYPE=1>
- * <LI>
- * <CODE>object</CODE> is not null.
- * <LI>
- * <CODE>object</CODE> is an instance of class Size2DSyntax.
- * <LI>
- * This attribute's X dimension is equal to <CODE>object</CODE>'s X
- * dimension.
- * <LI>
- * This attribute's Y dimension is equal to <CODE>object</CODE>'s Y
- * dimension.
- * </OL>
- *
- * @param object Object to compare to.
- *
- * @return True if <CODE>object</CODE> is equivalent to this
- * two-dimensional size attribute, false otherwise.
- */
- public boolean equals(Object object) {
- return(object != null &&
- object instanceof Size2DSyntax &&
- this.x == ((Size2DSyntax) object).x &&
- this.y == ((Size2DSyntax) object).y);
- }
-
- /**
- * Returns a hash code value for this two-dimensional size attribute.
- */
- public int hashCode() {
- return (((x & 0x0000FFFF) ) |
- ((y & 0x0000FFFF) << 16));
- }
-
- /**
- * Returns a string version of this two-dimensional size attribute. The
- * string takes the form <CODE>"<I>X</I>x<I>Y</I> um"</CODE>, where
- * <I>X</I> is the X dimension and <I>Y</I> is the Y dimension.
- * The values are reported in the internal units of micrometers.
- */
- public String toString() {
- StringBuffer result = new StringBuffer();
- result.append(x);
- result.append('x');
- result.append(y);
- result.append(" um");
- return result.toString();
- }
-
- /**
- * Returns this two-dimensional size attribute's X dimension in units of
- * micrometers (µm). (For use in a subclass.)
- *
- * @return X dimension (µm).
- */
- protected int getXMicrometers(){
- return x;
- }
-
- /**
- * Returns this two-dimensional size attribute's Y dimension in units of
- * micrometers (µm). (For use in a subclass.)
- *
- * @return Y dimension (µm).
- */
- protected int getYMicrometers() {
- return y;
- }
-
- }