1. /*
  2. * @(#)MediaPrintableArea.java 1.9 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.print.attribute.standard;
  8. import javax.print.attribute.DocAttribute;
  9. import javax.print.attribute.PrintJobAttribute;
  10. import javax.print.attribute.PrintRequestAttribute;
  11. /**
  12. * Class MediaPrintableArea is a printing attribute used to distinguish
  13. * the printable and non-printable areas of media.
  14. * <p>
  15. * The printable area is specified to be a rectangle, within the overall
  16. * dimensions of a media.
  17. * <p>
  18. * Most printers cannot print on the entire surface of the media, due
  19. * to printer hardware limitations. This class can be used to query
  20. * the acceptable values for a supposed print job, and to request an area
  21. * within the constraints of the printable area to be used in a print job.
  22. * <p>
  23. * To query for the printable area, a client must supply a suitable context.
  24. * Without specifying at the very least the size of the media being used
  25. * no meaningful value for printable area can be obtained.
  26. * <p>
  27. * The attribute is not described in terms of the distance from the edge
  28. * of the paper, in part to emphasise that this attribute is not independent
  29. * of a particular media, but must be described within the context of a
  30. * choice of other attributes. Additionally it is usually more convenient
  31. * for a client to use the printable area.
  32. * <p>
  33. * The hardware's minimum margins is not just a property of the printer,
  34. * but may be a function of the media size, orientation, media type, and
  35. * any specified finishings.
  36. * <code>PrintService</code> provides the method to query the supported
  37. * values of an attribute in a suitable context :
  38. * See {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) <code>PrintService.getSupportedAttributeValues()</code>}
  39. * <p>
  40. * The rectangular printable area is defined thus:
  41. * The (x,y) origin is positioned at the top-left of the paper in portrait
  42. * mode regardless of the orientation specified in the requesting context.
  43. * For example a printable area for A4 paper in portrait or landscape
  44. * orientation will have height > width.
  45. * <p>
  46. * A printable area attribute's values are stored
  47. * internally as integers in units of micrometers (µm), where 1 micrometer
  48. * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits
  49. * dimensions to be represented exactly to a precision of 1/1000 mm (= 1
  50. * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
  51. * negative powers of two, this permits dimensions to be represented exactly to
  52. * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
  53. * does not equal an integral number of µm).
  54. * <p>
  55. * <B>IPP Compatibility:</B> MediaPrintableArea is not an IPP attribute.
  56. */
  57. public final class MediaPrintableArea
  58. implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
  59. private int x, y, w, h;
  60. private int units;
  61. /**
  62. * Value to indicate units of inches (in). It is actually the conversion
  63. * factor by which to multiply inches to yield µm (25400).
  64. */
  65. public static final int INCH = 25400;
  66. /**
  67. * Value to indicate units of millimeters (mm). It is actually the
  68. * conversion factor by which to multiply mm to yield µm (1000).
  69. */
  70. public static final int MM = 1000;
  71. /**
  72. * Constructs a MediaPrintableArea object from floating point values.
  73. * @param x printable x
  74. * @param y printable y
  75. * @param w printable width
  76. * @param h printable height
  77. * @param units in which the values are expressed.
  78. *
  79. * @exception IllegalArgumentException
  80. * Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0
  81. * or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or
  82. * <CODE>units</CODE> < 1.
  83. */
  84. public MediaPrintableArea(float x, float y, float w, float h, int units) {
  85. if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) ||
  86. (units < 1)) {
  87. throw new IllegalArgumentException("0 or negative value argument");
  88. }
  89. this.x = (int) (x * units + 0.5f);
  90. this.y = (int) (y * units + 0.5f);
  91. this.w = (int) (w * units + 0.5f);
  92. this.h = (int) (h * units + 0.5f);
  93. }
  94. /**
  95. * Constructs a MediaPrintableArea object from integer values.
  96. * @param x printable x
  97. * @param y printable y
  98. * @param w printable width
  99. * @param h printable height
  100. * @param units in which the values are expressed.
  101. *
  102. * @exception IllegalArgumentException
  103. * Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0
  104. * or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or
  105. * <CODE>units</CODE> < 1.
  106. */
  107. public MediaPrintableArea(int x, int y, int w, int h, int units) {
  108. if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) ||
  109. (units < 1)) {
  110. throw new IllegalArgumentException("0 or negative value argument");
  111. }
  112. this.x = x * units;
  113. this.y = y * units;
  114. this.w = w * units;
  115. this.h = h * units;
  116. }
  117. /**
  118. * Get the printable area as an array of 4 values in the order
  119. * x, y, w, h. The values returned are in the given units.
  120. * @param units
  121. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  122. * {@link #MM <CODE>MM</CODE>}.
  123. *
  124. * @return printable area as array of x, y, w, h in the specified units.
  125. *
  126. * @exception IllegalArgumentException
  127. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  128. */
  129. public float[] getPrintableArea(int units) {
  130. return new float[] { getX(units), getY(units),
  131. getWidth(units), getHeight(units) };
  132. }
  133. /**
  134. * Get the x location of the origin of the printable area in the
  135. * specified units.
  136. * @param units
  137. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  138. * {@link #MM <CODE>MM</CODE>}.
  139. *
  140. * @return x location of the origin of the printable area in the
  141. * specified units.
  142. *
  143. * @exception IllegalArgumentException
  144. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  145. */
  146. public float getX(int units) {
  147. return convertFromMicrometers(x, units);
  148. }
  149. /**
  150. * Get the y location of the origin of the printable area in the
  151. * specified units.
  152. * @param units
  153. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  154. * {@link #MM <CODE>MM</CODE>}.
  155. *
  156. * @return y location of the origin of the printable area in the
  157. * specified units.
  158. *
  159. * @exception IllegalArgumentException
  160. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  161. */
  162. public float getY(int units) {
  163. return convertFromMicrometers(y, units);
  164. }
  165. /**
  166. * Get the width of the printable area in the specified units.
  167. * @param units
  168. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  169. * {@link #MM <CODE>MM</CODE>}.
  170. *
  171. * @return width of the printable area in the specified units.
  172. *
  173. * @exception IllegalArgumentException
  174. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  175. */
  176. public float getWidth(int units) {
  177. return convertFromMicrometers(w, units);
  178. }
  179. /**
  180. * Get the height of the printable area in the specified units.
  181. * @param units
  182. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  183. * {@link #MM <CODE>MM</CODE>}.
  184. *
  185. * @return height of the printable area in the specified units.
  186. *
  187. * @exception IllegalArgumentException
  188. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  189. */
  190. public float getHeight(int units) {
  191. return convertFromMicrometers(h, units);
  192. }
  193. /**
  194. * Returns whether this media margins attribute is equivalent to the passed
  195. * in object.
  196. * To be equivalent, all of the following conditions must be true:
  197. * <OL TYPE=1>
  198. * <LI>
  199. * <CODE>object</CODE> is not null.
  200. * <LI>
  201. * <CODE>object</CODE> is an instance of class MediaPrintableArea.
  202. * <LI>
  203. * The origin and dimensions are the same.
  204. * </OL>
  205. *
  206. * @param object Object to compare to.
  207. *
  208. * @return True if <CODE>object</CODE> is equivalent to this media margins
  209. * attribute, false otherwise.
  210. */
  211. public boolean equals(Object object) {
  212. boolean ret = false;
  213. if (object instanceof MediaPrintableArea) {
  214. MediaPrintableArea mm = (MediaPrintableArea)object;
  215. if (x == mm.x && y == mm.y && w == mm.w && h == mm.h) {
  216. ret = true;
  217. }
  218. }
  219. return ret;
  220. }
  221. /**
  222. * Get the printing attribute class which is to be used as the "category"
  223. * for this printing attribute value.
  224. * <P>
  225. * For class MediaPrintableArea, the category is
  226. * class MediaPrintableArea itself.
  227. *
  228. * @return Printing attribute class (category), an instance of class
  229. * {@link java.lang.Class java.lang.Class}.
  230. */
  231. public final Class getCategory() {
  232. return MediaPrintableArea.class;
  233. }
  234. /**
  235. * Get the name of the category of which this attribute value is an
  236. * instance.
  237. * <P>
  238. * For class MediaPrintableArea,
  239. * the category name is <CODE>"media-printable-area"</CODE>.
  240. * <p>This is not an IPP V1.1 attribute.
  241. *
  242. * @return Attribute category name.
  243. */
  244. public final String getName() {
  245. return "media-printable-area";
  246. }
  247. /**
  248. * Returns a string version of this rectangular size attribute in the
  249. * given units.
  250. *
  251. * @param units
  252. * Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
  253. * {@link #MM <CODE>MM</CODE>}.
  254. * @param unitsName
  255. * Units name string, e.g. <CODE>"in"</CODE> or <CODE>"mm"</CODE>. If
  256. * null, no units name is appended to the result.
  257. *
  258. * @return String version of this two-dimensional size attribute.
  259. *
  260. * @exception IllegalArgumentException
  261. * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
  262. */
  263. public String toString(int units, String unitsName) {
  264. if (unitsName == null) {
  265. unitsName = "";
  266. }
  267. float []vals = getPrintableArea(units);
  268. String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")";
  269. return str + unitsName;
  270. }
  271. /**
  272. * Returns a string version of this rectangular size attribute in mm.
  273. */
  274. public String toString() {
  275. return(toString(MM, "mm"));
  276. }
  277. /**
  278. * Returns a hash code value for this attribute.
  279. */
  280. public int hashCode() {
  281. return x + 37*y + 43*w + 47*h;
  282. }
  283. private static float convertFromMicrometers(int x, int units) {
  284. if (units < 1) {
  285. throw new IllegalArgumentException("units is < 1");
  286. }
  287. return ((float)x) / ((float)units);
  288. }
  289. }