Serializable
, Attribute
, DocAttribute
, PrintJobAttribute
, PrintRequestAttribute
public final class MediaPrintableArea extends Object implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
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.
Modifier and Type | Field | Description |
---|---|---|
static final int |
INCH |
Value to indicate units of inches (in). |
static final int |
MM |
Value to indicate units of millimeters (mm). |
Constructor | Description |
---|---|
MediaPrintableArea |
Constructs a MediaPrintableArea object from floating point values. |
MediaPrintableArea |
Constructs a MediaPrintableArea object from integer values. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
equals |
Returns whether this media margins attribute is equivalent to the passed in object. |
final Class |
getCategory() |
Get the printing attribute class which is to be used as the "category" for this printing attribute value. |
float |
getHeight |
Get the height of the printable area in the specified units. |
final String |
getName() |
Get the name of the category of which this attribute value is an instance. |
float[] |
getPrintableArea |
Get the printable area as an array of 4 values in the order x, y, w, h . |
float |
getWidth |
Get the width of the printable area in the specified units. |
float |
getX |
Get the x location of the origin of the printable area in the specified units. |
float |
getY |
Get the y location of the origin of the printable area in the specified units. |
int |
hashCode() |
Returns a hash code value for this attribute. |
String |
toString() |
Returns a string version of this rectangular size attribute in mm. |
String |
toString |
Returns a string version of this rectangular size attribute in the given units. |
public static final int INCH
public static final int MM
public MediaPrintableArea(float x, float y, float w, float h, int units)
MediaPrintableArea
object from floating point values.x
- printable xy
- printable yw
- printable widthh
- printable heightunits
- in which the values are expressedIllegalArgumentException
- if x < 0
or y < 0
or w <= 0
or h <= 0
or units < 1
public MediaPrintableArea(int x, int y, int w, int h, int units)
MediaPrintableArea
object from integer values.x
- printable xy
- printable yw
- printable widthh
- printable heightunits
- in which the values are expressedIllegalArgumentException
- if x < 0
or y < 0
or w <= 0
or h <= 0
or units < 1
public float[] getPrintableArea(int units)
x, y, w, h
. The values returned are in the given units.units
- unit conversion factor, e.g. INCH
or MM
x, y, w, h
in the specified unitsIllegalArgumentException
- if units < 1
public float getX(int units)
x
location of the origin of the printable area in the specified units.units
- unit conversion factor, e.g. INCH
or MM
x
location of the origin of the printable area in the specified unitsIllegalArgumentException
- if units < 1
public float getY(int units)
y
location of the origin of the printable area in the specified units.units
- unit conversion factor, e.g. INCH
or MM
y
location of the origin of the printable area in the specified unitsIllegalArgumentException
- if units < 1
public float getWidth(int units)
width
of the printable area in the specified units.units
- unit conversion factor, e.g. INCH
or MM
width
of the printable area in the specified unitsIllegalArgumentException
- if units < 1
public float getHeight(int units)
height
of the printable area in the specified units.units
- unit conversion factor, e.g. INCH
or MM
height
of the printable area in the specified unitsIllegalArgumentException
- if units < 1
public boolean equals(Object object)
object
is not null
. object
is an instance of class MediaPrintableArea
. public final Class<? extends Attribute> getCategory()
For class MediaPrintableArea
, the category is class MediaPrintableArea
itself.
getCategory
in interface Attribute
java.lang.Class
public final String getName()
For class MediaPrintableArea
, the category name is "media-printable-area"
.
This is not an IPP V1.1 attribute.
public String toString(int units, String unitsName)
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 resultIllegalArgumentException
- if units < 1
public String toString()
public int hashCode()
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/print/attribute/standard/MediaPrintableArea.html