Source for javax.print.attribute.standard.MediaPrintableArea

   1: /* MediaPrintableArea.java -- 
   2:    Copyright (C) 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.print.attribute.standard;
  40: 
  41: import javax.print.attribute.DocAttribute;
  42: import javax.print.attribute.PrintJobAttribute;
  43: import javax.print.attribute.PrintRequestAttribute;
  44: 
  45: /**
  46:  * The <code>MediaPrintableArea</code> attribute specifies the area
  47:  * of a media sheet which is available for printing.
  48:  * <p>
  49:  * Due to hardware limitation its not possible with most printers to use the 
  50:  * whole area of a media sheet for printing. This attribute defines the area 
  51:  * for printing through the values of the upper left corner position (x,y)
  52:  * on the sheet and the available width and height of the area. The units of 
  53:  * the values are determined by two defined constants:
  54:  * <ul>
  55:  * <li>INCH - defines an inch</li>
  56:  * <li>MM - defines a millimeter</li>
  57:  * </ul>
  58:  * </p>
  59:  * <p>
  60:  * <b>Internal storage:</b><br>
  61:  * The values of x, y, width and height are stored internally in micrometers. 
  62:  * The values of the provided constants for inch (value 25400) and millimeters
  63:  * (value 1000) are used as conversion factors to the internal storage units.
  64:  * To get the internal micrometers values a multiplication of a given
  65:  * size value with its units constant value is done. Retrieving the size value
  66:  * for specific units is done by dividing the internal stored value by the 
  67:  * units constant value.
  68:  * </p>
  69:  * <p>
  70:  * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP 1.1 attribute.
  71:  * </p>
  72:  *
  73:  * @author Michael Koch (konqueror@gmx.de)
  74:  * @author Wolfgang Baer (WBaer@gmx.de)
  75:  */
  76: public final class MediaPrintableArea
  77:   implements DocAttribute, PrintJobAttribute, PrintRequestAttribute
  78: {
  79:   private static final long serialVersionUID = -1597171464050795793L;
  80: 
  81:   /**
  82:    * Constant for the units of inches.
  83:    * The actual value is the conversion factor to micrometers.
  84:    */
  85:   public static final int INCH = 25400;
  86:   
  87:   /**
  88:    * Constant for the units of millimeters.
  89:    * The actual value is the conversion factor to micrometers.
  90:    */
  91:   public static final int MM = 1000;
  92:   
  93:   /** x in micrometers. */
  94:   private int x;
  95:   /** y in micrometers. */
  96:   private int y;
  97:   /** width in micrometers. */
  98:   private int width;
  99:   /** height in micrometers. */
 100:   private int height;
 101:   
 102:   /**
 103:    * Creates a new <code>MediaPrintableArea</code> object with the given
 104:    * float values for the given units.
 105:    * 
 106:    * @param x start of the printable area on the sheet in x direction.
 107:    * @param y start of the printable area on the sheet in y direction.
 108:    * @param w the width of the printable area.
 109:    * @param h the height of the printable area.
 110:    * @param units the units of the given values.
 111:    * 
 112:    * @throws IllegalArgumentException if x i&lt; 0 or y i&lt; 0 or w i&lt;= 0
 113:    * or h i&lt;= 0 or units i&lt; 1
 114:    */
 115:   public MediaPrintableArea(float x, float y, float w, float h, int units)
 116:   {
 117:     if (x < 0.0f || y < 0.0f || w <= 0.0f || h <= 0.0f)
 118:       throw new IllegalArgumentException();
 119: 
 120:     this.x = (int) (x * units + 0.5f);
 121:     this.y = (int) (y * units + 0.5f);
 122:     this.width = (int) (w * units + 0.5f);
 123:     this.height = (int) (h * units + 0.5f);
 124:   }
 125: 
 126:   /**
 127:    * Creates a new <code>MediaPrintableArea</code> object with the given
 128:    * int values for the given units.
 129:    * 
 130:    * @param x start of the printable area on the sheet in x direction.
 131:    * @param y start of the printable area on the sheet in y direction.
 132:    * @param w the width of the printable area.
 133:    * @param h the height of the printable area.
 134:    * @param units the units of the given values.
 135:    * 
 136:    * @throws IllegalArgumentException if x i&lt; 0 or y i&lt; 0 or w i&lt;= 0
 137:    * or h i&lt;= 0 or units i&lt; 1
 138:    */
 139:   public MediaPrintableArea(int x, int y, int w, int h, int units)
 140:   {
 141:     if (x < 0 || y < 0 || w <= 0 || h <= 0)
 142:       throw new IllegalArgumentException();
 143: 
 144:     this.x = x * units;
 145:     this.y = y * units;
 146:     this.width = w * units;
 147:     this.height = h * units;
 148:   }
 149: 
 150:   /**
 151:    * Returns category of this class.
 152:    *
 153:    * @return The class <code>MediaPrintableArea</code> itself.
 154:    */
 155:   public Class getCategory()
 156:   {
 157:     return MediaPrintableArea.class;
 158:   }
 159: 
 160:   /**
 161:    * Returns the name of this attribute.
 162:    *
 163:    * @return The name "media-printable-area".
 164:    */
 165:   public String getName()
 166:   {
 167:     return "media-printable-area";
 168:   }
 169: 
 170:   /**
 171:    * Returns the height of the printable area for the given units.
 172:    * 
 173:    * @param units the units conversion factor.
 174:    * @return The height.
 175:    * 
 176:    * @throws IllegalArgumentException if <code>units</code> is &lt; 1
 177:    */
 178:   public float getHeight(int units)
 179:   {
 180:     if (units < 1)
 181:       throw new IllegalArgumentException("units may not be less than 1");
 182: 
 183:     return height / ((float)units);
 184:   }
 185: 
 186:   /**
 187:    * Returns the width of the printable area for the given units.
 188:    * 
 189:    * @param units the units conversion factor.
 190:    * @return The width.
 191:    * 
 192:    * @throws IllegalArgumentException if <code>units</code> is &lt; 1
 193:    */
 194:   public float getWidth(int units)
 195:   {
 196:     if (units < 1)
 197:       throw new IllegalArgumentException("units may not be less than 1");
 198: 
 199:     return width / ((float)units);
 200:   }
 201: 
 202:   /**
 203:    * Returns the position in x direction of the printable area 
 204:    * for the given units.
 205:    * 
 206:    * @param units the units conversion factor.
 207:    * @return The position in x direction.
 208:    * 
 209:    * @throws IllegalArgumentException if <code>units</code> is &lt; 1
 210:    */
 211:   public float getX(int units)
 212:   {
 213:     if (units < 1)
 214:       throw new IllegalArgumentException("units may not be less than 1");
 215: 
 216:     return x / ((float)units);
 217:   }
 218: 
 219:   /**
 220:    * Returns the position in y direction of the printable area 
 221:    * for the given units.
 222:    * 
 223:    * @param units the units conversion factor.
 224:    * @return The position in y direction.
 225:    * 
 226:    * @throws IllegalArgumentException if <code>units</code> is &lt; 1
 227:    */
 228:   public float getY(int units)
 229:   {
 230:     if (units < 1)
 231:       throw new IllegalArgumentException("units may not be less than 1");
 232: 
 233:     return y / ((float)units);
 234:   }
 235:   
 236:   /**
 237:    * Tests if the given object is equal to this object.
 238:    *
 239:    * @param obj the object to test
 240:    *
 241:    * @return <code>true</code> if both objects are equal, <code>false</code> otherwise.
 242:    */
 243:   public boolean equals(Object obj)
 244:   {
 245:     if (! (obj instanceof MediaPrintableArea))
 246:       return false;
 247: 
 248:     MediaPrintableArea tmp = (MediaPrintableArea) obj;
 249: 
 250:     return (x == tmp.getX(1) && y == tmp.getY(1)
 251:             && width == tmp.getWidth(1) && height == tmp.getHeight(1));
 252:   }
 253: 
 254:   /**
 255:    * Returns the string representation for this object in units of millimeters..
 256:    * <p>
 257:    * The returned string is in the form "(x,y)->(width,height)mm".
 258:    * </p> 
 259:    * @return The string representation in millimeters.
 260:    */
 261:   public String toString()
 262:   {
 263:     return toString(MM, "mm");
 264:   }
 265: 
 266:   /**
 267:    * Returns the hashcode for this object.
 268:    *
 269:    * @return The hashcode.
 270:    */
 271:   public int hashCode()
 272:   {
 273:     return x ^ y + width ^ height;
 274:   }
 275:   
 276:   /**
 277:    * Returns the string representation for this object in units of millimeters..
 278:    * <p>
 279:    * The returned string is in the form "(x,y)->(width,height)unitsName".
 280:    * </p>
 281:    * @param units the units to use for conversion.
 282:    * @param unitsName the name of the used units, appended to the resulting
 283:    * string if not <code>null</code>.
 284:    * @return The string representation in millimeters.
 285:    * 
 286:    * @throws IllegalArgumentException if <code>units</code> is &lt; 1
 287:    */
 288:   public String toString(int units, String unitsName)
 289:   {
 290:     if (units < 1)
 291:       throw new IllegalArgumentException("units may not be less than 1");
 292:     
 293:     String tmp = "(" + getX(units) + "," + getY(units) + ")->("
 294:                  + getWidth(units) + "," + getHeight(units) + ")";
 295:     
 296:     return unitsName == null ? tmp : tmp + unitsName;
 297:   }
 298: 
 299:   /**
 300:    * Returns the printable area as an float[] with 4 values 
 301:    * (order x, y, width, height) in the given units.
 302:    * 
 303:    * @param units the units to use.
 304:    * @return The printable area as float array.
 305:    */
 306:   public float[] getPrintableArea(int units)
 307:   {
 308:     return new float[] { getX(units), getY(units), 
 309:                          getWidth(units), getHeight(units) };
 310:   }  
 311: }