| /* |
| * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| package javax.print.attribute.standard; |
| |
| import javax.print.attribute.Attribute; |
| import javax.print.attribute.DocAttribute; |
| import javax.print.attribute.PrintJobAttribute; |
| import javax.print.attribute.PrintRequestAttribute; |
| |
| /** |
| * Class MediaPrintableArea is a printing attribute used to distinguish |
| * the printable and non-printable areas of media. |
| * <p> |
| * The printable area is specified to be a rectangle, within the overall |
| * dimensions of a media. |
| * <p> |
| * Most printers cannot print on the entire surface of the media, due |
| * to printer hardware limitations. This class can be used to query |
| * the acceptable values for a supposed print job, and to request an area |
| * within the constraints of the printable area to be used in a print job. |
| * <p> |
| * To query for the printable area, a client must supply a suitable context. |
| * Without specifying at the very least the size of the media being used |
| * no meaningful value for printable area can be obtained. |
| * <p> |
| * The attribute is not described in terms of the distance from the edge |
| * of the paper, in part to emphasise that this attribute is not independent |
| * of a particular media, but must be described within the context of a |
| * choice of other attributes. Additionally it is usually more convenient |
| * for a client to use the printable area. |
| * <p> |
| * The hardware's minimum margins is not just a property of the printer, |
| * but may be a function of the media size, orientation, media type, and |
| * any specified finishings. |
| * <code>PrintService</code> provides the method to query the supported |
| * values of an attribute in a suitable context : |
| * See {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) <code>PrintService.getSupportedAttributeValues()</code>} |
| * <p> |
| * The rectangular printable area is defined thus: |
| * The (x,y) origin is positioned at the top-left of the paper in portrait |
| * mode regardless of the orientation specified in the requesting context. |
| * For example a printable area for A4 paper in portrait or landscape |
| * orientation will have height > width. |
| * <p> |
| * A printable area attribute's 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> |
| * <B>IPP Compatibility:</B> MediaPrintableArea is not an IPP attribute. |
| */ |
| |
| public final class MediaPrintableArea |
| implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { |
| |
| private int x, y, w, h; |
| private int units; |
| |
| private static final long serialVersionUID = -1597171464050795793L; |
| |
| /** |
| * 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; |
| |
| /** |
| * Constructs a MediaPrintableArea object from floating point values. |
| * @param x printable x |
| * @param y printable y |
| * @param w printable width |
| * @param h printable height |
| * @param units in which the values are expressed. |
| * |
| * @exception IllegalArgumentException |
| * Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0 |
| * or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or |
| * <CODE>units</CODE> < 1. |
| */ |
| public MediaPrintableArea(float x, float y, float w, float h, int units) { |
| if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) || |
| (units < 1)) { |
| throw new IllegalArgumentException("0 or negative value argument"); |
| } |
| |
| this.x = (int) (x * units + 0.5f); |
| this.y = (int) (y * units + 0.5f); |
| this.w = (int) (w * units + 0.5f); |
| this.h = (int) (h * units + 0.5f); |
| |
| } |
| |
| /** |
| * Constructs a MediaPrintableArea object from integer values. |
| * @param x printable x |
| * @param y printable y |
| * @param w printable width |
| * @param h printable height |
| * @param units in which the values are expressed. |
| * |
| * @exception IllegalArgumentException |
| * Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0 |
| * or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or |
| * <CODE>units</CODE> < 1. |
| */ |
| public MediaPrintableArea(int x, int y, int w, int h, int units) { |
| if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) || |
| (units < 1)) { |
| throw new IllegalArgumentException("0 or negative value argument"); |
| } |
| this.x = x * units; |
| this.y = y * units; |
| this.w = w * units; |
| this.h = h * units; |
| |
| } |
| |
| /** |
| * Get the printable area as an array of 4 values in the order |
| * x, y, w, h. The values returned are in the given units. |
| * @param units |
| * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or |
| * {@link #MM <CODE>MM</CODE>}. |
| * |
| * @return printable area as array of x, y, w, h in the specified units. |
| * |
| * @exception IllegalArgumentException |
| * (unchecked exception) Thrown if <CODE>units</CODE> < 1. |
| */ |
| public float[] getPrintableArea(int units) { |
| return new float[] { getX(units), getY(units), |
| getWidth(units), getHeight(units) }; |
| } |
| |
| /** |
| * Get the x location of the origin of the printable area in the |
| * specified units. |
| * @param units |
| * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or |
| * {@link #MM <CODE>MM</CODE>}. |
| * |
| * @return x location of the origin of the printable area in the |
| * specified units. |
| * |
| * @exception IllegalArgumentException |
| * (unchecked exception) Thrown if <CODE>units</CODE> < 1. |
| */ |
| public float getX(int units) { |
| return convertFromMicrometers(x, units); |
| } |
| |
| /** |
| * Get the y location of the origin of the printable area in the |
| * specified units. |
| * @param units |
| * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or |
| * {@link #MM <CODE>MM</CODE>}. |
| * |
| * @return y location of the origin of the printable area in the |
| * specified units. |
| * |
| * @exception IllegalArgumentException |
| * (unchecked exception) Thrown if <CODE>units</CODE> < 1. |
| */ |
| public float getY(int units) { |
| return convertFromMicrometers(y, units); |
| } |
| |
| /** |
| * Get the width of the printable area in the specified units. |
| * @param units |
| * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or |
| * {@link #MM <CODE>MM</CODE>}. |
| * |
| * @return width of the printable area in the specified units. |
| * |
| * @exception IllegalArgumentException |
| * (unchecked exception) Thrown if <CODE>units</CODE> < 1. |
| */ |
| public float getWidth(int units) { |
| return convertFromMicrometers(w, units); |
| } |
| |
| /** |
| * Get the height of the printable area in the specified units. |
| * @param units |
| * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or |
| * {@link #MM <CODE>MM</CODE>}. |
| * |
| * @return height of the printable area in the specified units. |
| * |
| * @exception IllegalArgumentException |
| * (unchecked exception) Thrown if <CODE>units</CODE> < 1. |
| */ |
| public float getHeight(int units) { |
| return convertFromMicrometers(h, units); |
| } |
| |
| /** |
| * Returns whether this media margins 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 MediaPrintableArea. |
| * <LI> |
| * The origin and dimensions are the same. |
| * </OL> |
| * |
| * @param object Object to compare to. |
| * |
| * @return True if <CODE>object</CODE> is equivalent to this media margins |
| * attribute, false otherwise. |
| */ |
| public boolean equals(Object object) { |
| boolean ret = false; |
| if (object instanceof MediaPrintableArea) { |
| MediaPrintableArea mm = (MediaPrintableArea)object; |
| if (x == mm.x && y == mm.y && w == mm.w && h == mm.h) { |
| ret = true; |
| } |
| } |
| return ret; |
| } |
| |
| /** |
| * Get the printing attribute class which is to be used as the "category" |
| * for this printing attribute value. |
| * <P> |
| * For class MediaPrintableArea, the category is |
| * class MediaPrintableArea itself. |
| * |
| * @return Printing attribute class (category), an instance of class |
| * {@link java.lang.Class java.lang.Class}. |
| */ |
| public final Class<? extends Attribute> getCategory() { |
| return MediaPrintableArea.class; |
| } |
| |
| /** |
| * Get the name of the category of which this attribute value is an |
| * instance. |
| * <P> |
| * For class MediaPrintableArea, |
| * the category name is <CODE>"media-printable-area"</CODE>. |
| * <p>This is not an IPP V1.1 attribute. |
| * |
| * @return Attribute category name. |
| */ |
| public final String getName() { |
| return "media-printable-area"; |
| } |
| |
| /** |
| * Returns a string version of this rectangular size attribute in the |
| * given units. |
| * |
| * @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) { |
| if (unitsName == null) { |
| unitsName = ""; |
| } |
| float []vals = getPrintableArea(units); |
| String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")"; |
| return str + unitsName; |
| } |
| |
| /** |
| * Returns a string version of this rectangular size attribute in mm. |
| */ |
| public String toString() { |
| return(toString(MM, "mm")); |
| } |
| |
| /** |
| * Returns a hash code value for this attribute. |
| */ |
| public int hashCode() { |
| return x + 37*y + 43*w + 47*h; |
| } |
| |
| private static float convertFromMicrometers(int x, int units) { |
| if (units < 1) { |
| throw new IllegalArgumentException("units is < 1"); |
| } |
| return ((float)x) / ((float)units); |
| } |
| } |
