< prev index next >
src/java.desktop/share/classes/javax/print/attribute/standard/MediaPrintableArea.java
Print this page
@@ -20,74 +20,83 @@
*
* 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.DocFlavor;
+import javax.print.PrintService;
import javax.print.attribute.Attribute;
import javax.print.attribute.AttributeSet;
import javax.print.attribute.DocAttribute;
import javax.print.attribute.PrintJobAttribute;
import javax.print.attribute.PrintRequestAttribute;
/**
- * Class MediaPrintableArea is a printing attribute used to distinguish
+ * Class {@code 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.
+ * 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.
+ * 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} provides the method to query the supported
- * values of an attribute in a suitable context :
- * See {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) PrintService.getSupportedAttributeValues()}
- * <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 {@literal >} 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).
+ * 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} provides the method to query the supported
+ * values of an attribute in a suitable context : See
+ * {@link PrintService#getSupportedAttributeValues(Class, DocFlavor, AttributeSet)
+ * PrintService.getSupportedAttributeValues()}
+ * <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
+ * {@literal >} width.
* <p>
- * <B>IPP Compatibility:</B> MediaPrintableArea is not an IPP attribute.
+ * 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 {
+ /**
+ * Printable {@code x}, {@code y}, {@code width} and {@code height}.
+ */
private int x, y, w, h;
+
+ /**
+ * The units in which the values are expressed.
+ */
private int units;
+ /**
+ * Use serialVersionUID from JDK 1.4 for interoperability.
+ */
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).
@@ -99,21 +108,20 @@
* 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.
+ * Constructs a {@code 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 < 0} or {@code y < 0}
- * or {@code w <= 0} or {@code h <= 0} or
- * {@code units < 1}.
+ * @param units in which the values are expressed
+ * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or
+ * {@code w <= 0} or {@code h <= 0} or {@code units < 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");
@@ -125,21 +133,19 @@
this.h = (int) (h * units + 0.5f);
}
/**
- * Constructs a MediaPrintableArea object from integer values.
+ * Constructs a {@code 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 < 0} or {@code y < 0}
- * or {@code w <= 0} or {@code h <= 0} or
- * {@code units < 1}.
+ * @param units in which the values are expressed
+ * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or
+ * {@code w <= 0} or {@code h <= 0} or {@code units < 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");
@@ -151,106 +157,88 @@
}
/**
* 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 INCH} or
- * {@link #MM MM}.
+ * {@code x, y, w, h}. The values returned are in the given units.
*
- * @return printable area as array of x, y, w, h in the specified units.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return printable area as array of {@code x, y, w, h} in the specified
+ * units
+ * @throws IllegalArgumentException if {@code units < 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 INCH} or
- * {@link #MM MM}.
- *
- * @return x location of the origin of the printable area in the
+ * Get the {@code x} location of the origin of the printable area in the
* specified units.
*
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return {@code x} location of the origin of the printable area in the
+ * specified units
+ * @throws IllegalArgumentException if {@code units < 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 INCH} or
- * {@link #MM MM}.
- *
- * @return y location of the origin of the printable area in the
+ * Get the {@code y} location of the origin of the printable area in the
* specified units.
*
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return {@code y} location of the origin of the printable area in the
+ * specified units
+ * @throws IllegalArgumentException if {@code units < 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 INCH} or
- * {@link #MM MM}.
+ * Get the {@code width} of the printable area in the specified units.
*
- * @return width of the printable area in the specified units.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return {@code width} of the printable area in the specified units
+ * @throws IllegalArgumentException if {@code units < 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 INCH} or
- * {@link #MM MM}.
- *
- * @return height of the printable area in the specified units.
+ * Get the {@code height} of the printable area in the specified units.
*
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return {@code height} of the printable area in the specified units
+ * @throws IllegalArgumentException if {@code units < 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} is not null.
- * <LI>
- * {@code object} 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} is equivalent to this media margins
- * attribute, false otherwise.
+ * in object. To be equivalent, all of the following conditions must be
+ * true:
+ * <ol type=1>
+ * <li>{@code object} is not {@code null}.
+ * <li>{@code object} is an instance of class {@code MediaPrintableArea}.
+ * <li>The origin and dimensions are the same.
+ * </ol>
+ *
+ * @param object {@code Object} to compare to
+ * @return {@code true} if {@code object} is equivalent to this media
+ * margins attribute, {@code false} otherwise
*/
public boolean equals(Object object) {
boolean ret = false;
if (object instanceof MediaPrintableArea) {
MediaPrintableArea mm = (MediaPrintableArea)object;
@@ -262,50 +250,46 @@
}
/**
* 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.
+ * <p>
+ * For class {@code MediaPrintableArea}, the category is class
+ * {@code MediaPrintableArea} itself.
*
- * @return Printing attribute class (category), an instance of class
- * {@link java.lang.Class java.lang.Class}.
+ * @return printing attribute class (category), an instance of class
+ * {@link 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"}.
- * <p>This is not an IPP V1.1 attribute.
+ * <p>
+ * For class {@code MediaPrintableArea}, the category name is
+ * {@code "media-printable-area"}.
+ * <p>
+ * This is not an IPP V1.1 attribute.
*
- * @return Attribute category name.
+ * @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 INCH} or
- * {@link #MM MM}.
- * @param unitsName
- * Units name string, e.g. {@code "in"} or {@code "mm"}. If
- * null, no units name is appended to the result.
+ * Returns a string version of this rectangular size attribute in the given
+ * units.
*
- * @return String version of this two-dimensional size attribute.
- *
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code units < 1}.
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @param unitsName units name string, e.g. {@code "in"} or {@code "mm"}.
+ * If {@code null}, no units name is appended to the result
+ * @return string version of this two-dimensional size attribute
+ * @throws IllegalArgumentException if {@code units < 1}
*/
public String toString(int units, String unitsName) {
if (unitsName == null) {
unitsName = "";
}
@@ -326,10 +310,18 @@
*/
public int hashCode() {
return x + 37*y + 43*w + 47*h;
}
+ /**
+ * Converts the {@code x} from micrometers to {@code units}.
+ *
+ * @param x the value
+ * @param units unit conversion factor, e.g. {@link #INCH INCH} or
+ * {@link #MM MM}
+ * @return the value of {@code x} in the specified units
+ */
private static float convertFromMicrometers(int x, int units) {
if (units < 1) {
throw new IllegalArgumentException("units is < 1");
}
return ((float)x) / ((float)units);
< prev index next >