https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2021, 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 java.io.Serial;

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 the printable and non-printable areas of media. 

The printable area is specified to be a rectangle, within the overall
dimensions of a media.


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.


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.


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.

 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. PrintService provides the method to query the supported values of an attribute in a suitable context : See 
PrintService.getSupportedAttributeValues() 
 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. 

A printable area attribute's values are stored internally as integers in
units of micrometers (µm), where 1 micrometer = 10-6 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).


IPP Compatibility: MediaPrintableArea is not an IPP attribute.

/**
 * 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.
 * <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} 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>
 * A printable area attribute's values are stored internally as integers in
 * units of micrometers (&#181;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 &#181;m) or 1/100 inch (= 254
 * &#181;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 &#181;m) but not 1/16 inch (because 1/16 inch does not equal an
 * integral number of &#181;m).
 * <p>
 * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP attribute.
 */
public final class MediaPrintableArea
      implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {

    
Printable x, y, width and height. 
/**
     * Printable {@code x}, {@code y}, {@code width} and {@code height}.
     */
    private int x, y, w, h;

    
The units in which the values are expressed.

/**
     * The units in which the values are expressed.
     */
    private int units;

    
Use serialVersionUID from JDK 1.4 for interoperability.

/**
     * Use serialVersionUID from JDK 1.4 for interoperability.
     */
    @Serial
    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).

/**
     * Value to indicate units of inches (in). It is actually the conversion
     * factor by which to multiply inches to yield &#181;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).

/**
     * Value to indicate units of millimeters (mm). It is actually the
     * conversion factor by which to multiply mm to yield &#181;m (1000).
     */
    public static final int MM = 1000;

    
Constructs a MediaPrintableArea object from floating point values. 
Params:
  • x – printable x
  • y – printable y
  • w – printable width
  • h – printable height
  • units – in which the values are expressed
Throws:
/**
     * 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
     * @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");
        }

        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. 
Params:
  • x – printable x
  • y – printable y
  • w – printable width
  • h – printable height
  • units – in which the values are expressed
Throws:
/**
     * 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
     * @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");
        }
        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. 
Params:
  • units – unit conversion factor, e.g. INCH or MM
Throws:
Returns:printable area as array of x, y, w, h in the specified units
/**
     * Get the printable area as an array of 4 values in the order
     * {@code 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}
     * @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. 
Params:
  • units – unit conversion factor, e.g. INCH or MM
Throws:
Returns:x location of the origin of the printable area in the specified units
/**
     * Get the {@code 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 {@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. 
Params:
  • units – unit conversion factor, e.g. INCH or MM
Throws:
Returns:y location of the origin of the printable area in the specified units
/**
     * Get the {@code 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 {@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. 
Params:
  • units – unit conversion factor, e.g. INCH or MM
Throws:
Returns:width of the printable area in the specified units
/**
     * Get the {@code width} of the printable area in the specified units.
     *
     * @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. 
Params:
  • units – unit conversion factor, e.g. INCH or MM
Throws:
Returns:height of the printable area in the specified units
/**
     * Get the {@code height} of the printable area in the specified units.
     *
     * @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:

    
  
  1. object is not null. 
  2. object is an instance of class MediaPrintableArea. 
  3. The origin and dimensions are the same.



Params:
  • object – Object to compare to
Returns:true if object is equivalent to this media margins attribute, false otherwise
/**
     * 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 {@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;
           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.

 For class MediaPrintableArea, the category is class MediaPrintableArea itself. 
Returns:printing attribute class (category), an instance of class java.lang.Class
/**
     * Get the printing attribute class which is to be used as the "category"
     * for this printing attribute value.
     * <p>
     * For class {@code MediaPrintableArea}, the category is class
     * {@code MediaPrintableArea} itself.
     *
     * @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.

 For class MediaPrintableArea, the category name is "media-printable-area". 

This is not an IPP V1.1 attribute.

Returns:attribute category name
/**
     * Get the name of the category of which this attribute value is an
     * instance.
     * <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
     */
    public final String getName() {
        return "media-printable-area";
    }

    
Returns a string version of this rectangular size attribute in the given
units.

Params:
  • units – unit conversion factor, e.g. INCH or MM
  • unitsName – units name string, e.g. "in" or "mm". If null, no units name is appended to the result
Throws:
Returns:string version of this two-dimensional size attribute
/**
     * 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 {@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 = "";
        }
        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.

/**
     * 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.

/**
     * Returns a hash code value for this attribute.
     */
    public int hashCode() {
        return x + 37*y + 43*w + 47*h;
    }

    
Converts the x from micrometers to units. 
Params:
  • x – the value
  • units – unit conversion factor, e.g. INCH or MM
Returns:the value of x in the specified units
/**
     * 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);
    }
}