OpenJDK 1.23 · javax.print.attribute.standard.MediaPrintableArea

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.

Field Summary

Modifier and Type	Field and Description
private int	h Printable `x`, `y`, `width` and `height`.
public static final int	INCH Value to indicate units of inches (in).
public static final int	MM Value to indicate units of millimeters (mm).
private static final long	serialVersionUID Use serialVersionUID from JDK 1.4 for interoperability.
private int	units The units in which the values are expressed.
private int	w Printable `x`, `y`, `width` and `height`.
private int	x Printable `x`, `y`, `width` and `height`.
private int	y Printable `x`, `y`, `width` and `height`.

Constructor Summary

Access	Constructor and Description
public	MediaPrintableArea(float printable x x, float printable y y, float printable width w, float printable height h, int in which the values are expressed units) Constructs a `MediaPrintableArea` object from floating point values.
public	MediaPrintableArea(int printable x x, int printable y y, int printable width w, int printable height h, int in which the values are expressed units) Constructs a `MediaPrintableArea` object from integer values.

Method Summary

Modifier and Type	Method and Description
private static float	Returns: the value of `x` in the specified units convertFromMicrometers(int the value x, int unit conversion factor, e.g. `INCH` or `MM` units) Converts the `x` from micrometers to `units`.
public boolean	Returns: `true` if `object` is equivalent to this media margins attribute, `false` otherwise equals(Object `Object` to compare to object) Overrides java.lang.Object.equals. Returns whether this media margins attribute is equivalent to the passed in object.
public final Class<? extends Attribute>	Returns: printing attribute class (category), an instance of class `java.lang.Class` getCategory() Implements javax.print.attribute.Attribute.getCategory. Get the printing attribute class which is to be used as the "category" for this printing attribute value.
public float	Returns: `height` of the printable area in the specified units getHeight(int unit conversion factor, e.g. `INCH` or `MM` units) Get the `height` of the printable area in the specified units.
public final String	Returns: attribute category name getName() Implements javax.print.attribute.Attribute.getName. Get the name of the category of which this attribute value is an instance.
public float[]	Returns: printable area as array of `x, y, w, h` in the specified units getPrintableArea(int unit conversion factor, e.g. `INCH` or `MM` units) Get the printable area as an array of 4 values in the order `x, y, w, h`.
public float	Returns: `width` of the printable area in the specified units getWidth(int unit conversion factor, e.g. `INCH` or `MM` units) Get the `width` of the printable area in the specified units.
public float	Returns: `x` location of the origin of the printable area in the specified units getX(int unit conversion factor, e.g. `INCH` or `MM` units) Get the `x` location of the origin of the printable area in the specified units.
public float	Returns: `y` location of the origin of the printable area in the specified units getY(int unit conversion factor, e.g. `INCH` or `MM` units) Get the `y` location of the origin of the printable area in the specified units.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this attribute.
public String	Returns: string version of this two-dimensional size attribute toString(int unit conversion factor, e.g. `INCH` or `MM` units, String units name string, e.g. `"in"` or `"mm"`. If `null`, no units name is appended to the result unitsName) Returns a string version of this rectangular size attribute in the given units.
public String	toString() Overrides java.lang.Object.toString. Returns a string version of this rectangular size attribute in mm.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

h	back to summary
private int h Printable `x`, `y`, `width` and `height`.

INCH	back to summary
public static final int INCH Value to indicate units of inches (in). It is actually the conversion factor by which to multiply inches to yield µm (25400).

MM	back to summary
public static final int MM Value to indicate units of millimeters (mm). It is actually the conversion factor by which to multiply mm to yield µm (1000).

serialVersionUID	back to summary
private static final long serialVersionUID Use serialVersionUID from JDK 1.4 for interoperability. Annotations @Serial

units	back to summary
private int units The units in which the values are expressed.

w	back to summary
private int w Printable `x`, `y`, `width` and `height`.

x	back to summary
private int x Printable `x`, `y`, `width` and `height`.

y	back to summary
private int y Printable `x`, `y`, `width` and `height`.

Constructor Detail

MediaPrintableArea back to summary

MediaPrintableArea	back to summary
public MediaPrintableArea(float x, float y, float w, float h, int units) Constructs a `MediaPrintableArea` object from floating point values. Parameters x:float printable x y:float printable y w:float printable width h:float printable height units:int in which the values are expressed Exceptions IllegalArgumentException: if `x < 0` or `y < 0` or `w <= 0` or `h <= 0` or `units < 1`

public MediaPrintableArea(float x, float y, float w, float h, int units)

Constructs a MediaPrintableArea object from floating point values.

Parameters

x:float: printable x
y:float: printable y
w:float: printable width
h:float: printable height
units:int: in which the values are expressed

Exceptions

IllegalArgumentException:: if x < 0 or y < 0 or w <= 0 or h <= 0 or units < 1

MediaPrintableArea back to summary

MediaPrintableArea	back to summary
public MediaPrintableArea(int x, int y, int w, int h, int units) Constructs a `MediaPrintableArea` object from integer values. Parameters x:int printable x y:int printable y w:int printable width h:int printable height units:int in which the values are expressed Exceptions IllegalArgumentException: 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)

Constructs a MediaPrintableArea object from integer values.

Parameters

x:int: printable x
y:int: printable y
w:int: printable width
h:int: printable height
units:int: in which the values are expressed

Exceptions

IllegalArgumentException:: if x < 0 or y < 0 or w <= 0 or h <= 0 or units < 1

Method Detail

convertFromMicrometers back to summary

convertFromMicrometers	back to summary
private static float convertFromMicrometers(int x, int units) Converts the `x` from micrometers to `units`. Parameters x:int the value units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float the value of `x` in the specified units

private static float convertFromMicrometers(int x, int units)

Converts the x from micrometers to units.

Parameters

x:int: the value
units:int: unit conversion factor, e.g. INCH or MM

Returns:float

the value of x in the specified units

equals back to summary

equals	back to summary
public boolean equals(Object object) Overrides java.lang.Object.equals. Returns whether this media margins attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true: `object` is not `null`. `object` is an instance of class `MediaPrintableArea`. The origin and dimensions are the same. Parameters object:Object `Object` to compare to Returns:boolean `true` if `object` is equivalent to this media margins attribute, `false` otherwise

public boolean equals(Object object)

Overrides java.lang.Object.equals.

Returns whether this media margins attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:

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

Parameters

object:Object: Object to compare to

Returns:boolean

true if object is equivalent to this media margins attribute, false otherwise

getCategory back to summary

getCategory	back to summary
public final Class<? extends Attribute> getCategory() Implements javax.print.attribute.Attribute.getCategory. 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:Class<? extends Attribute> printing attribute class (category), an instance of class `java.lang.Class`

public final Class<? extends Attribute> getCategory()

Implements javax.print.attribute.Attribute.getCategory.

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:Class<? extends Attribute>: printing attribute class (category), an instance of class java.lang.Class

getHeight back to summary

getHeight	back to summary
public float getHeight(int units) Get the `height` of the printable area in the specified units. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float `height` of the printable area in the specified units Exceptions IllegalArgumentException: if `units < 1`

public float getHeight(int units)

Get the height of the printable area in the specified units.

Parameters

units:int: unit conversion factor, e.g. INCH or MM

Returns:float

height of the printable area in the specified units

Exceptions

IllegalArgumentException:: if units < 1

getName back to summary

getName	back to summary
public final String getName() Implements javax.print.attribute.Attribute.getName. 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:String attribute category name

public final String getName()

Implements javax.print.attribute.Attribute.getName.

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:String: attribute category name

getPrintableArea back to summary

getPrintableArea	back to summary
public float[] getPrintableArea(int 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. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float[] printable area as array of `x, y, w, h` in the specified units Exceptions IllegalArgumentException: if `units < 1`

public float[] getPrintableArea(int 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.

Parameters

units:int: unit conversion factor, e.g. INCH or MM

Returns:float[]

printable area as array of x, y, w, h in the specified units

Exceptions

IllegalArgumentException:: if units < 1

getWidth back to summary

getWidth	back to summary
public float getWidth(int units) Get the `width` of the printable area in the specified units. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float `width` of the printable area in the specified units Exceptions IllegalArgumentException: if `units < 1`

public float getWidth(int units)

Get the width of the printable area in the specified units.

Parameters

units:int: unit conversion factor, e.g. INCH or MM

Returns:float

width of the printable area in the specified units

Exceptions

IllegalArgumentException:: if units < 1

getX back to summary

getX	back to summary
public float getX(int units) Get the `x` location of the origin of the printable area in the specified units. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float `x` location of the origin of the printable area in the specified units Exceptions IllegalArgumentException: if `units < 1`

public float getX(int units)

Get the x location of the origin of the printable area in the specified units.

Parameters

units:int: unit conversion factor, e.g. INCH or MM

Returns:float

x location of the origin of the printable area in the specified units

Exceptions

IllegalArgumentException:: if units < 1

getY back to summary

getY	back to summary
public float getY(int units) Get the `y` location of the origin of the printable area in the specified units. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` Returns:float `y` location of the origin of the printable area in the specified units Exceptions IllegalArgumentException: if `units < 1`

public float getY(int units)

Get the y location of the origin of the printable area in the specified units.

Parameters

units:int: unit conversion factor, e.g. INCH or MM

Returns:float

y location of the origin of the printable area in the specified units

Exceptions

IllegalArgumentException:: if units < 1

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this attribute. Returns:int Doc from java.lang.Object.hashCode. a hash code value for this object

hashCode

back to summary

public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this attribute.

Returns:int

Doc from java.lang.Object.hashCode.

a hash code value for this object

toString back to summary

toString	back to summary
public String toString(int units, String unitsName) Returns a string version of this rectangular size attribute in the given units. Parameters units:int unit conversion factor, e.g. `INCH` or `MM` unitsName:String units name string, e.g. `"in"` or `"mm"`. If `null`, no units name is appended to the result Returns:String string version of this two-dimensional size attribute Exceptions IllegalArgumentException: if `units < 1`

public String toString(int units, String unitsName)

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

Parameters

units:int: unit conversion factor, e.g. INCH or MM
unitsName:String: units name string, e.g. "in" or "mm". If null, no units name is appended to the result

Returns:String

string version of this two-dimensional size attribute

Exceptions

IllegalArgumentException:: if units < 1

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a string version of this rectangular size attribute in mm. Returns:String Doc from java.lang.Object.toString. a string representation of the object

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Returns a string version of this rectangular size attribute in mm.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

public final Class MediaPrintableArea

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail