Module java.desktop
Package javax.print.attribute.standard

# Class MediaSize

java.lang.Object
javax.print.attribute.Size2DSyntax
javax.print.attribute.standard.MediaSize

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Attribute`

    public class MediaSize
    extends Size2DSyntax
    implements Attribute

Class `MediaSize` is a two-dimensional size valued printing attribute class that indicates the dimensions of the medium in a portrait orientation, with the `X` dimension running along the bottom edge and the `Y` dimension running along the left edge. Thus, the `Y` dimension must be greater than or equal to the `X` dimension. Class `MediaSize` declares many standard media size values, organized into nested classes for ISO, JIS, North American, engineering, and other media.

`MediaSize` is not yet used to specify media. Its current role is as a mapping for named media (see `MediaSizeName`). Clients can use the mapping method `MediaSize.getMediaSizeForName(MediaSizeName)` to find the physical dimensions of the `MediaSizeName` instances enumerated in this API. This is useful for clients which need this information to format & paginate printing.

See Also:
  Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type | Class | Description
--- | --- | ---
`static class` | `MediaSize.Engineering` | Class `MediaSize.Engineering` includes `MediaSize` values for engineering media.
`static class` | `MediaSize.ISO` | Class `MediaSize.ISO` includes `MediaSize` values for ISO media.
`static class` | `MediaSize.JIS` | Class `MediaSize.JIS` includes `MediaSize` values for JIS (Japanese) media.
`static class` | `MediaSize.NA` | Class `MediaSize.NA` includes `MediaSize` values for North American media.
`static class` | `MediaSize.Other` | Class `MediaSize.Other` includes `MediaSize` values for miscellaneous media.

## Field Summary

### Fields declared in class javax.print.attribute.Size2DSyntax

`INCH, MM`

## Constructor Summary

Constructors
Constructor | Description
--- | ---
`MediaSize​(float x, float y, int units)` | Construct a new media size attribute from the given floating-point values.
`MediaSize​(float x, float y, int units, MediaSizeName media)` | Construct a new media size attribute from the given floating-point values.
`MediaSize​(int x, int y, int units)` | Construct a new media size attribute from the given integer values.
`MediaSize​(int x, int y, int units, MediaSizeName media)` | Construct a new media size attribute from the given integer values.

## Method Summary

Modifier and Type | Method | Description
--- | --- | ---
`boolean` | `equals​(Object object)` | Returns whether this media size attribute is equivalent to the passed in object.
`static MediaSizeName` | `findMedia​(float x, float y, int units)` | The specified dimensions are used to locate a matching `MediaSize` instance from amongst all the standard `MediaSize` instances.
`Class<? extends Attribute>` | `getCategory()` | Get the printing attribute class which is to be used as the "category" for this printing attribute value.
`static MediaSize` | `getMediaSizeForName​(MediaSizeName media)` | Get the `MediaSize` for the specified named media.
`MediaSizeName` | `getMediaSizeName()` | Get the media name, if any, for this size.
`String` | `getName()` | Get the name of the category of which this attribute value is an instance.

### Methods declared in class javax.print.attribute.Size2DSyntax

`getSize, getX, getXMicrometers, getY, getYMicrometers, hashCode, toString, toString`

### Methods declared in class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

## Constructor Details

### MediaSize

public MediaSize​(float x, float y, int units)
Construct a new media size attribute from the given floating-point values.

Parameters:
  `x` - `X` dimension
  `y` - `Y` dimension
  `units` - unit conversion factor, e.g. `Size2DSyntax.INCH` or `Size2DSyntax.MM`
Throws:
  `IllegalArgumentException` - if `x < 0` or `y < 0` or `units < 1` or `x > y`

### MediaSize

public MediaSize​(int x, int y, int units)
Construct a new media size attribute from the given integer values.

Parameters:
  `x` - `X` dimension
  `y` - `Y` dimension
  `units` - unit conversion factor, e.g. `Size2DSyntax.INCH` or `Size2DSyntax.MM`
Throws:
  `IllegalArgumentException` - if `x < 0` or `y < 0` or `units < 1` or `x > y`

### MediaSize

public MediaSize​(float x, float y, int units, MediaSizeName media)
Construct a new media size attribute from the given floating-point values.

Parameters:
  `x` - `X` dimension
  `y` - `Y` dimension
  `units` - unit conversion factor, e.g. `Size2DSyntax.INCH` or `Size2DSyntax.MM`
  `media` - a media name to associate with this `MediaSize`
Throws:
  `IllegalArgumentException` - if `x < 0` or `y < 0` or `units < 1` or `x > y`

### MediaSize

public MediaSize​(int x, int y, int units, MediaSizeName media)
Construct a new media size attribute from the given integer values.

Parameters:
  `x` - `X` dimension
  `y` - `Y` dimension
  `units` - unit conversion factor, e.g. `Size2DSyntax.INCH` or `Size2DSyntax.MM`
  `media` - a media name to associate with this `MediaSize`
Throws:
  `IllegalArgumentException` - if `x < 0` or `y < 0` or `units < 1` or `x > y`

## Method Details

### getMediaSizeName

public MediaSizeName getMediaSizeName()
Get the media name, if any, for this size.

Returns:
  the name for this media size, or `null` if no name was associated with this size (an anonymous size)

### getMediaSizeForName

public static MediaSize getMediaSizeForName​(MediaSizeName media)
Get the `MediaSize` for the specified named media.

Parameters:
  `media` - the name of the media for which the size is sought
Returns:
  size of the media, or `null` if this media is not associated with any size

### findMedia

public static MediaSizeName findMedia​(float x, float y, int units)
The specified dimensions are used to locate a matching `MediaSize` instance from amongst all the standard `MediaSize` instances. If there is no exact match, the closest match is used.

The `MediaSize` is in turn used to locate the `MediaSizeName` object. This method may return `null` if the closest matching `MediaSize` has no corresponding `Media` instance.

This method is useful for clients which have only dimensions and want to find a `Media` which corresponds to the dimensions.

Parameters:
  `x` - `X` dimension
  `y` - `Y` dimension
  `units` - unit conversion factor, e.g. `Size2DSyntax.INCH` or `Size2DSyntax.MM`
Returns:
  `MediaSizeName` matching these dimensions, or `null`
Throws:
  `IllegalArgumentException` - if `x <= 0`, `y <= 0`, or `units < 1`

### equals

public boolean equals​(Object object)
Returns whether this media size 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 `MediaSize`.
3. This media size attribute's `X` dimension is equal to `object`'s `X` dimension.
4. This media size attribute's `Y` dimension is equal to `object`'s `Y` dimension.

Overrides:
  `equals` in class `Size2DSyntax`
Parameters:
  `object` - `Object` to compare to
Returns:
  `true` if `object` is equivalent to this media size attribute, `false` otherwise
See Also:
  `Object.hashCode()`, `HashMap`

### getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class `MediaSize` and any vendor-defined subclasses, the category is class `MediaSize` itself.

Specified by:
  `getCategory` in interface `Attribute`
Returns:
  printing attribute class (category), an instance of class `java.lang.Class`

### getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class `MediaSize` and any vendor-defined subclasses, the category name is `"media-size"`.

Specified by:
  `getName` in interface `Attribute`
Returns:
  attribute category name