001/* MediaPrintableArea.java -- 002 Copyright (C) 2005, 2006 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package javax.print.attribute.standard; 040 041import javax.print.attribute.Attribute; 042import javax.print.attribute.DocAttribute; 043import javax.print.attribute.PrintJobAttribute; 044import javax.print.attribute.PrintRequestAttribute; 045 046/** 047 * The <code>MediaPrintableArea</code> attribute specifies the area 048 * of a media sheet which is available for printing. 049 * <p> 050 * Due to hardware limitation its not possible with most printers to use the 051 * whole area of a media sheet for printing. This attribute defines the area 052 * for printing through the values of the upper left corner position (x,y) 053 * on the sheet and the available width and height of the area. The units of 054 * the values are determined by two defined constants: 055 * <ul> 056 * <li>INCH - defines an inch</li> 057 * <li>MM - defines a millimeter</li> 058 * </ul> 059 * </p> 060 * <p> 061 * <b>Internal storage:</b><br> 062 * The values of x, y, width and height are stored internally in micrometers. 063 * The values of the provided constants for inch (value 25400) and millimeters 064 * (value 1000) are used as conversion factors to the internal storage units. 065 * To get the internal micrometers values a multiplication of a given 066 * size value with its units constant value is done. Retrieving the size value 067 * for specific units is done by dividing the internal stored value by the 068 * units constant value. 069 * </p> 070 * <p> 071 * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP 1.1 attribute. 072 * </p> 073 * 074 * @author Michael Koch (konqueror@gmx.de) 075 * @author Wolfgang Baer (WBaer@gmx.de) 076 */ 077public final class MediaPrintableArea 078 implements DocAttribute, PrintJobAttribute, PrintRequestAttribute 079{ 080 private static final long serialVersionUID = -1597171464050795793L; 081 082 /** 083 * Constant for the units of inches. 084 * The actual value is the conversion factor to micrometers. 085 */ 086 public static final int INCH = 25400; 087 088 /** 089 * Constant for the units of millimeters. 090 * The actual value is the conversion factor to micrometers. 091 */ 092 public static final int MM = 1000; 093 094 /** x in micrometers. */ 095 private int x; 096 /** y in micrometers. */ 097 private int y; 098 /** width in micrometers. */ 099 private int w; 100 /** height in micrometers. */ 101 private int h; 102 103 /** 104 * Creates a new <code>MediaPrintableArea</code> object with the given 105 * float values for the given units. 106 * 107 * @param x start of the printable area on the sheet in x direction. 108 * @param y start of the printable area on the sheet in y direction. 109 * @param w the width of the printable area. 110 * @param h the height of the printable area. 111 * @param units the units of the given values. 112 * 113 * @throws IllegalArgumentException if x i< 0 or y i< 0 or w i<= 0 114 * or h i<= 0 or units i< 1 115 */ 116 public MediaPrintableArea(float x, float y, float w, float h, int units) 117 { 118 if (x < 0.0f || y < 0.0f || w <= 0.0f || h <= 0.0f) 119 throw new IllegalArgumentException(); 120 121 this.x = (int) (x * units + 0.5f); 122 this.y = (int) (y * units + 0.5f); 123 this.w = (int) (w * units + 0.5f); 124 this.h = (int) (h * units + 0.5f); 125 } 126 127 /** 128 * Creates a new <code>MediaPrintableArea</code> object with the given 129 * int values for the given units. 130 * 131 * @param x start of the printable area on the sheet in x direction. 132 * @param y start of the printable area on the sheet in y direction. 133 * @param w the width of the printable area. 134 * @param h the height of the printable area. 135 * @param units the units of the given values. 136 * 137 * @throws IllegalArgumentException if x i< 0 or y i< 0 or w i<= 0 138 * or h i<= 0 or units i< 1 139 */ 140 public MediaPrintableArea(int x, int y, int w, int h, int units) 141 { 142 if (x < 0 || y < 0 || w <= 0 || h <= 0) 143 throw new IllegalArgumentException(); 144 145 this.x = x * units; 146 this.y = y * units; 147 this.w = w * units; 148 this.h = h * units; 149 } 150 151 /** 152 * Returns category of this class. 153 * 154 * @return The class <code>MediaPrintableArea</code> itself. 155 */ 156 public Class< ? extends Attribute> getCategory() 157 { 158 return MediaPrintableArea.class; 159 } 160 161 /** 162 * Returns the name of this attribute. 163 * 164 * @return The name "media-printable-area". 165 */ 166 public String getName() 167 { 168 return "media-printable-area"; 169 } 170 171 /** 172 * Returns the height of the printable area for the given units. 173 * 174 * @param units the units conversion factor. 175 * @return The height. 176 * 177 * @throws IllegalArgumentException if <code>units</code> is < 1 178 */ 179 public float getHeight(int units) 180 { 181 if (units < 1) 182 throw new IllegalArgumentException("units may not be less than 1"); 183 184 return h / ((float)units); 185 } 186 187 /** 188 * Returns the width of the printable area for the given units. 189 * 190 * @param units the units conversion factor. 191 * @return The width. 192 * 193 * @throws IllegalArgumentException if <code>units</code> is < 1 194 */ 195 public float getWidth(int units) 196 { 197 if (units < 1) 198 throw new IllegalArgumentException("units may not be less than 1"); 199 200 return w / ((float)units); 201 } 202 203 /** 204 * Returns the position in x direction of the printable area 205 * for the given units. 206 * 207 * @param units the units conversion factor. 208 * @return The position in x direction. 209 * 210 * @throws IllegalArgumentException if <code>units</code> is < 1 211 */ 212 public float getX(int units) 213 { 214 if (units < 1) 215 throw new IllegalArgumentException("units may not be less than 1"); 216 217 return x / ((float)units); 218 } 219 220 /** 221 * Returns the position in y direction of the printable area 222 * for the given units. 223 * 224 * @param units the units conversion factor. 225 * @return The position in y direction. 226 * 227 * @throws IllegalArgumentException if <code>units</code> is < 1 228 */ 229 public float getY(int units) 230 { 231 if (units < 1) 232 throw new IllegalArgumentException("units may not be less than 1"); 233 234 return y / ((float)units); 235 } 236 237 /** 238 * Tests if the given object is equal to this object. 239 * 240 * @param obj the object to test 241 * 242 * @return <code>true</code> if both objects are equal, <code>false</code> otherwise. 243 */ 244 public boolean equals(Object obj) 245 { 246 if (! (obj instanceof MediaPrintableArea)) 247 return false; 248 249 MediaPrintableArea tmp = (MediaPrintableArea) obj; 250 251 return (x == tmp.getX(1) && y == tmp.getY(1) 252 && w == tmp.getWidth(1) && h == tmp.getHeight(1)); 253 } 254 255 /** 256 * Returns the string representation for this object in units of millimeters.. 257 * <p> 258 * The returned string is in the form "(x,y)->(width,height)mm". 259 * </p> 260 * @return The string representation in millimeters. 261 */ 262 public String toString() 263 { 264 return toString(MM, "mm"); 265 } 266 267 /** 268 * Returns the hashcode for this object. 269 * 270 * @return The hashcode. 271 */ 272 public int hashCode() 273 { 274 return x ^ y + w ^ h; 275 } 276 277 /** 278 * Returns the string representation for this object in units of millimeters.. 279 * <p> 280 * The returned string is in the form "(x,y)->(width,height)unitsName". 281 * </p> 282 * @param units the units to use for conversion. 283 * @param unitsName the name of the used units, appended to the resulting 284 * string if not <code>null</code>. 285 * @return The string representation in millimeters. 286 * 287 * @throws IllegalArgumentException if <code>units</code> is < 1 288 */ 289 public String toString(int units, String unitsName) 290 { 291 if (units < 1) 292 throw new IllegalArgumentException("units may not be less than 1"); 293 294 String tmp = "(" + getX(units) + "," + getY(units) + ")->(" 295 + getWidth(units) + "," + getHeight(units) + ")"; 296 297 return unitsName == null ? tmp : tmp + unitsName; 298 } 299 300 /** 301 * Returns the printable area as an float[] with 4 values 302 * (order x, y, width, height) in the given units. 303 * 304 * @param units the units to use. 305 * @return The printable area as float array. 306 */ 307 public float[] getPrintableArea(int units) 308 { 309 return new float[] { getX(units), getY(units), 310 getWidth(units), getHeight(units) }; 311 } 312}