5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package javax.print.attribute.standard; 26 27 import javax.print.DocFlavor; 28 import javax.print.attribute.Attribute; 29 import javax.print.attribute.AttributeSet; 30 import javax.print.attribute.DocAttribute; 31 import javax.print.attribute.PrintJobAttribute; 32 import javax.print.attribute.PrintRequestAttribute; 33 34 /** 35 * Class MediaPrintableArea is a printing attribute used to distinguish 36 * the printable and non-printable areas of media. 37 * <p> 38 * The printable area is specified to be a rectangle, within the overall 39 * dimensions of a media. 40 * <p> 41 * Most printers cannot print on the entire surface of the media, due 42 * to printer hardware limitations. This class can be used to query 43 * the acceptable values for a supposed print job, and to request an area 44 * within the constraints of the printable area to be used in a print job. 45 * <p> 46 * To query for the printable area, a client must supply a suitable context. 47 * Without specifying at the very least the size of the media being used 48 * no meaningful value for printable area can be obtained. 49 * <p> 50 * The attribute is not described in terms of the distance from the edge 51 * of the paper, in part to emphasise that this attribute is not independent 52 * of a particular media, but must be described within the context of a 53 * choice of other attributes. Additionally it is usually more convenient 54 * for a client to use the printable area. 55 * <p> 56 * The hardware's minimum margins is not just a property of the printer, 57 * but may be a function of the media size, orientation, media type, and 58 * any specified finishings. 59 * {@code PrintService} provides the method to query the supported 60 * values of an attribute in a suitable context : 61 * See {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) PrintService.getSupportedAttributeValues()} 62 * <p> 63 * The rectangular printable area is defined thus: 64 * The (x,y) origin is positioned at the top-left of the paper in portrait 65 * mode regardless of the orientation specified in the requesting context. 66 * For example a printable area for A4 paper in portrait or landscape 67 * orientation will have height {@literal >} width. 68 * <p> 69 * A printable area attribute's values are stored 70 * internally as integers in units of micrometers (µm), where 1 micrometer 71 * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits 72 * dimensions to be represented exactly to a precision of 1/1000 mm (= 1 73 * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in 74 75 * negative powers of two, this permits dimensions to be represented exactly to 76 * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch 77 78 * does not equal an integral number of µm). 79 * <p> 80 * <B>IPP Compatibility:</B> MediaPrintableArea is not an IPP attribute. 81 */ 82 83 public final class MediaPrintableArea 84 implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { 85 86 private int x, y, w, h; 87 private int units; 88 89 private static final long serialVersionUID = -1597171464050795793L; 90 91 /** 92 * Value to indicate units of inches (in). It is actually the conversion 93 * factor by which to multiply inches to yield µm (25400). 94 */ 95 public static final int INCH = 25400; 96 97 /** 98 * Value to indicate units of millimeters (mm). It is actually the 99 * conversion factor by which to multiply mm to yield µm (1000). 100 */ 101 public static final int MM = 1000; 102 103 /** 104 * Constructs a MediaPrintableArea object from floating point values. 105 * @param x printable x 106 * @param y printable y 107 * @param w printable width 108 * @param h printable height 109 * @param units in which the values are expressed. 110 * 111 * @exception IllegalArgumentException 112 * Thrown if {@code x < 0} or {@code y < 0} 113 * or {@code w <= 0} or {@code h <= 0} or 114 * {@code units < 1}. 115 */ 116 public MediaPrintableArea(float x, float y, float w, float h, int units) { 117 if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) || 118 (units < 1)) { 119 throw new IllegalArgumentException("0 or negative value argument"); 120 } 121 122 this.x = (int) (x * units + 0.5f); 123 this.y = (int) (y * units + 0.5f); 124 this.w = (int) (w * units + 0.5f); 125 this.h = (int) (h * units + 0.5f); 126 127 } 128 129 /** 130 * Constructs a MediaPrintableArea object from integer values. 131 * @param x printable x 132 * @param y printable y 133 * @param w printable width 134 * @param h printable height 135 * @param units in which the values are expressed. 136 * 137 * @exception IllegalArgumentException 138 * Thrown if {@code x < 0} or {@code y < 0} 139 * or {@code w <= 0} or {@code h <= 0} or 140 * {@code units < 1}. 141 */ 142 public MediaPrintableArea(int x, int y, int w, int h, int units) { 143 if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) || 144 (units < 1)) { 145 throw new IllegalArgumentException("0 or negative value argument"); 146 } 147 this.x = x * units; 148 this.y = y * units; 149 this.w = w * units; 150 this.h = h * units; 151 152 } 153 154 /** 155 * Get the printable area as an array of 4 values in the order 156 * x, y, w, h. The values returned are in the given units. 157 * @param units 158 * Unit conversion factor, e.g. {@link #INCH INCH} or 159 * {@link #MM MM}. 160 * 161 * @return printable area as array of x, y, w, h in the specified units. 162 * 163 * @exception IllegalArgumentException 164 * (unchecked exception) Thrown if {@code units < 1}. 165 */ 166 public float[] getPrintableArea(int units) { 167 return new float[] { getX(units), getY(units), 168 getWidth(units), getHeight(units) }; 169 } 170 171 /** 172 * Get the x location of the origin of the printable area in the 173 * specified units. 174 * @param units 175 * Unit conversion factor, e.g. {@link #INCH INCH} or 176 * {@link #MM MM}. 177 * 178 * @return x location of the origin of the printable area in the 179 * specified units. 180 * 181 * @exception IllegalArgumentException 182 * (unchecked exception) Thrown if {@code units < 1}. 183 */ 184 public float getX(int units) { 185 return convertFromMicrometers(x, units); 186 } 187 188 /** 189 * Get the y location of the origin of the printable area in the 190 * specified units. 191 * @param units 192 * Unit conversion factor, e.g. {@link #INCH INCH} or 193 * {@link #MM MM}. 194 * 195 * @return y location of the origin of the printable area in the 196 * specified units. 197 * 198 * @exception IllegalArgumentException 199 * (unchecked exception) Thrown if {@code units < 1}. 200 */ 201 public float getY(int units) { 202 return convertFromMicrometers(y, units); 203 } 204 205 /** 206 * Get the width of the printable area in the specified units. 207 * @param units 208 * Unit conversion factor, e.g. {@link #INCH INCH} or 209 * {@link #MM MM}. 210 * 211 * @return width of the printable area in the specified units. 212 * 213 * @exception IllegalArgumentException 214 * (unchecked exception) Thrown if {@code units < 1}. 215 */ 216 public float getWidth(int units) { 217 return convertFromMicrometers(w, units); 218 } 219 220 /** 221 * Get the height of the printable area in the specified units. 222 * @param units 223 * Unit conversion factor, e.g. {@link #INCH INCH} or 224 * {@link #MM MM}. 225 * 226 * @return height of the printable area in the specified units. 227 * 228 * @exception IllegalArgumentException 229 * (unchecked exception) Thrown if {@code units < 1}. 230 */ 231 public float getHeight(int units) { 232 return convertFromMicrometers(h, units); 233 } 234 235 /** 236 * Returns whether this media margins attribute is equivalent to the passed 237 * in object. 238 * To be equivalent, all of the following conditions must be true: 239 * <OL TYPE=1> 240 * <LI> 241 * {@code object} is not null. 242 * <LI> 243 * {@code object} is an instance of class MediaPrintableArea. 244 * <LI> 245 * The origin and dimensions are the same. 246 * </OL> 247 * 248 * @param object Object to compare to. 249 * 250 * @return True if {@code object} is equivalent to this media margins 251 * attribute, false otherwise. 252 */ 253 public boolean equals(Object object) { 254 boolean ret = false; 255 if (object instanceof MediaPrintableArea) { 256 MediaPrintableArea mm = (MediaPrintableArea)object; 257 if (x == mm.x && y == mm.y && w == mm.w && h == mm.h) { 258 ret = true; 259 } 260 } 261 return ret; 262 } 263 264 /** 265 * Get the printing attribute class which is to be used as the "category" 266 * for this printing attribute value. 267 * <P> 268 * For class MediaPrintableArea, the category is 269 * class MediaPrintableArea itself. 270 * 271 * @return Printing attribute class (category), an instance of class 272 * {@link java.lang.Class java.lang.Class}. 273 */ 274 public final Class<? extends Attribute> getCategory() { 275 return MediaPrintableArea.class; 276 } 277 278 /** 279 * Get the name of the category of which this attribute value is an 280 * instance. 281 * <P> 282 * For class MediaPrintableArea, 283 * the category name is {@code "media-printable-area"}. 284 * <p>This is not an IPP V1.1 attribute. 285 * 286 * @return Attribute category name. 287 */ 288 public final String getName() { 289 return "media-printable-area"; 290 } 291 292 /** 293 * Returns a string version of this rectangular size attribute in the 294 * given units. 295 * 296 * @param units 297 * Unit conversion factor, e.g. {@link #INCH INCH} or 298 * {@link #MM MM}. 299 * @param unitsName 300 * Units name string, e.g. {@code "in"} or {@code "mm"}. If 301 * null, no units name is appended to the result. 302 * 303 * @return String version of this two-dimensional size attribute. 304 * 305 * @exception IllegalArgumentException 306 * (unchecked exception) Thrown if {@code units < 1}. 307 */ 308 public String toString(int units, String unitsName) { 309 if (unitsName == null) { 310 unitsName = ""; 311 } 312 float []vals = getPrintableArea(units); 313 String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")"; 314 return str + unitsName; 315 } 316 317 /** 318 * Returns a string version of this rectangular size attribute in mm. 319 */ 320 public String toString() { 321 return(toString(MM, "mm")); 322 } 323 324 /** 325 * Returns a hash code value for this attribute. 326 */ 327 public int hashCode() { 328 return x + 37*y + 43*w + 47*h; 329 } 330 331 private static float convertFromMicrometers(int x, int units) { 332 if (units < 1) { 333 throw new IllegalArgumentException("units is < 1"); 334 } 335 return ((float)x) / ((float)units); 336 } 337 } | 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.print.attribute.standard; 27 28 import javax.print.DocFlavor; 29 import javax.print.PrintService; 30 import javax.print.attribute.Attribute; 31 import javax.print.attribute.AttributeSet; 32 import javax.print.attribute.DocAttribute; 33 import javax.print.attribute.PrintJobAttribute; 34 import javax.print.attribute.PrintRequestAttribute; 35 36 /** 37 * Class {@code MediaPrintableArea} is a printing attribute used to distinguish 38 * the printable and non-printable areas of media. 39 * <p> 40 * The printable area is specified to be a rectangle, within the overall 41 * dimensions of a media. 42 * <p> 43 * Most printers cannot print on the entire surface of the media, due to printer 44 * hardware limitations. This class can be used to query the acceptable values 45 * for a supposed print job, and to request an area within the constraints of 46 * the printable area to be used in a print job. 47 * <p> 48 * To query for the printable area, a client must supply a suitable context. 49 * Without specifying at the very least the size of the media being used no 50 * meaningful value for printable area can be obtained. 51 * <p> 52 * The attribute is not described in terms of the distance from the edge of the 53 * paper, in part to emphasise that this attribute is not independent of a 54 * particular media, but must be described within the context of a choice of 55 * other attributes. Additionally it is usually more convenient for a client to 56 * use the printable area. 57 * <p> 58 * The hardware's minimum margins is not just a property of the printer, but may 59 * be a function of the media size, orientation, media type, and any specified 60 * finishings. {@code PrintService} provides the method to query the supported 61 * values of an attribute in a suitable context : See 62 * {@link PrintService#getSupportedAttributeValues(Class, DocFlavor, AttributeSet) 63 * PrintService.getSupportedAttributeValues()} 64 * <p> 65 * The rectangular printable area is defined thus: The (x,y) origin is 66 * positioned at the top-left of the paper in portrait mode regardless of the 67 * orientation specified in the requesting context. For example a printable area 68 * for A4 paper in portrait or landscape orientation will have height 69 * {@literal >} width. 70 * <p> 71 * A printable area attribute's values are stored internally as integers in 72 * units of micrometers (µm), where 1 micrometer = 10<SUP>-6</SUP> meter = 73 * 1/1000 millimeter = 1/25400 inch. This permits dimensions to be represented 74 * exactly to a precision of 1/1000 mm (= 1 µm) or 1/100 inch (= 254 75 * µm). If fractional inches are expressed in negative powers of two, this 76 * permits dimensions to be represented exactly to a precision of 1/8 inch 77 * (= 3175 µm) but not 1/16 inch (because 1/16 inch does not equal an 78 * integral number of µm). 79 * <p> 80 * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP attribute. 81 */ 82 public final class MediaPrintableArea 83 implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { 84 85 /** 86 * Printable {@code x}, {@code y}, {@code width} and {@code height}. 87 */ 88 private int x, y, w, h; 89 90 /** 91 * The units in which the values are expressed. 92 */ 93 private int units; 94 95 /** 96 * Use serialVersionUID from JDK 1.4 for interoperability. 97 */ 98 private static final long serialVersionUID = -1597171464050795793L; 99 100 /** 101 * Value to indicate units of inches (in). It is actually the conversion 102 * factor by which to multiply inches to yield µm (25400). 103 */ 104 public static final int INCH = 25400; 105 106 /** 107 * Value to indicate units of millimeters (mm). It is actually the 108 * conversion factor by which to multiply mm to yield µm (1000). 109 */ 110 public static final int MM = 1000; 111 112 /** 113 * Constructs a {@code MediaPrintableArea} object from floating point 114 * values. 115 * 116 * @param x printable x 117 * @param y printable y 118 * @param w printable width 119 * @param h printable height 120 * @param units in which the values are expressed 121 * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or 122 * {@code w <= 0} or {@code h <= 0} or {@code units < 1} 123 */ 124 public MediaPrintableArea(float x, float y, float w, float h, int units) { 125 if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) || 126 (units < 1)) { 127 throw new IllegalArgumentException("0 or negative value argument"); 128 } 129 130 this.x = (int) (x * units + 0.5f); 131 this.y = (int) (y * units + 0.5f); 132 this.w = (int) (w * units + 0.5f); 133 this.h = (int) (h * units + 0.5f); 134 135 } 136 137 /** 138 * Constructs a {@code MediaPrintableArea} object from integer values. 139 * 140 * @param x printable x 141 * @param y printable y 142 * @param w printable width 143 * @param h printable height 144 * @param units in which the values are expressed 145 * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or 146 * {@code w <= 0} or {@code h <= 0} or {@code units < 1} 147 */ 148 public MediaPrintableArea(int x, int y, int w, int h, int units) { 149 if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) || 150 (units < 1)) { 151 throw new IllegalArgumentException("0 or negative value argument"); 152 } 153 this.x = x * units; 154 this.y = y * units; 155 this.w = w * units; 156 this.h = h * units; 157 158 } 159 160 /** 161 * Get the printable area as an array of 4 values in the order 162 * {@code x, y, w, h}. The values returned are in the given units. 163 * 164 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 165 * {@link #MM MM} 166 * @return printable area as array of {@code x, y, w, h} in the specified 167 * units 168 * @throws IllegalArgumentException if {@code units < 1} 169 */ 170 public float[] getPrintableArea(int units) { 171 return new float[] { getX(units), getY(units), 172 getWidth(units), getHeight(units) }; 173 } 174 175 /** 176 * Get the {@code x} location of the origin of the printable area in the 177 * specified units. 178 * 179 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 180 * {@link #MM MM} 181 * @return {@code x} location of the origin of the printable area in the 182 * specified units 183 * @throws IllegalArgumentException if {@code units < 1} 184 */ 185 public float getX(int units) { 186 return convertFromMicrometers(x, units); 187 } 188 189 /** 190 * Get the {@code y} location of the origin of the printable area in the 191 * specified units. 192 * 193 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 194 * {@link #MM MM} 195 * @return {@code y} location of the origin of the printable area in the 196 * specified units 197 * @throws IllegalArgumentException if {@code units < 1} 198 */ 199 public float getY(int units) { 200 return convertFromMicrometers(y, units); 201 } 202 203 /** 204 * Get the {@code width} of the printable area in the specified units. 205 * 206 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 207 * {@link #MM MM} 208 * @return {@code width} of the printable area in the specified units 209 * @throws IllegalArgumentException if {@code units < 1} 210 */ 211 public float getWidth(int units) { 212 return convertFromMicrometers(w, units); 213 } 214 215 /** 216 * Get the {@code height} of the printable area in the specified units. 217 * 218 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 219 * {@link #MM MM} 220 * @return {@code height} of the printable area in the specified units 221 * @throws IllegalArgumentException if {@code units < 1} 222 */ 223 public float getHeight(int units) { 224 return convertFromMicrometers(h, units); 225 } 226 227 /** 228 * Returns whether this media margins attribute is equivalent to the passed 229 * in object. To be equivalent, all of the following conditions must be 230 * true: 231 * <ol type=1> 232 * <li>{@code object} is not {@code null}. 233 * <li>{@code object} is an instance of class {@code MediaPrintableArea}. 234 * <li>The origin and dimensions are the same. 235 * </ol> 236 * 237 * @param object {@code Object} to compare to 238 * @return {@code true} if {@code object} is equivalent to this media 239 * margins attribute, {@code false} otherwise 240 */ 241 public boolean equals(Object object) { 242 boolean ret = false; 243 if (object instanceof MediaPrintableArea) { 244 MediaPrintableArea mm = (MediaPrintableArea)object; 245 if (x == mm.x && y == mm.y && w == mm.w && h == mm.h) { 246 ret = true; 247 } 248 } 249 return ret; 250 } 251 252 /** 253 * Get the printing attribute class which is to be used as the "category" 254 * for this printing attribute value. 255 * <p> 256 * For class {@code MediaPrintableArea}, the category is class 257 * {@code MediaPrintableArea} itself. 258 * 259 * @return printing attribute class (category), an instance of class 260 * {@link Class java.lang.Class} 261 */ 262 public final Class<? extends Attribute> getCategory() { 263 return MediaPrintableArea.class; 264 } 265 266 /** 267 * Get the name of the category of which this attribute value is an 268 * instance. 269 * <p> 270 * For class {@code MediaPrintableArea}, the category name is 271 * {@code "media-printable-area"}. 272 * <p> 273 * This is not an IPP V1.1 attribute. 274 * 275 * @return attribute category name 276 */ 277 public final String getName() { 278 return "media-printable-area"; 279 } 280 281 /** 282 * Returns a string version of this rectangular size attribute in the given 283 * units. 284 * 285 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 286 * {@link #MM MM} 287 * @param unitsName units name string, e.g. {@code "in"} or {@code "mm"}. 288 * If {@code null}, no units name is appended to the result 289 * @return string version of this two-dimensional size attribute 290 * @throws IllegalArgumentException if {@code units < 1} 291 */ 292 public String toString(int units, String unitsName) { 293 if (unitsName == null) { 294 unitsName = ""; 295 } 296 float []vals = getPrintableArea(units); 297 String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")"; 298 return str + unitsName; 299 } 300 301 /** 302 * Returns a string version of this rectangular size attribute in mm. 303 */ 304 public String toString() { 305 return(toString(MM, "mm")); 306 } 307 308 /** 309 * Returns a hash code value for this attribute. 310 */ 311 public int hashCode() { 312 return x + 37*y + 43*w + 47*h; 313 } 314 315 /** 316 * Converts the {@code x} from micrometers to {@code units}. 317 * 318 * @param x the value 319 * @param units unit conversion factor, e.g. {@link #INCH INCH} or 320 * {@link #MM MM} 321 * @return the value of {@code x} in the specified units 322 */ 323 private static float convertFromMicrometers(int x, int units) { 324 if (units < 1) { 325 throw new IllegalArgumentException("units is < 1"); 326 } 327 return ((float)x) / ((float)units); 328 } 329 } |