Source for javax.print.attribute.standard.MediaPrintableArea

   1: /* MediaPrintableArea.java --
   2:    Copyright (C) 2005, 2006  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.Attribute;
  42: import javax.print.attribute.DocAttribute;
  43: import javax.print.attribute.PrintJobAttribute;
  44: import javax.print.attribute.PrintRequestAttribute;
  45: 
  46: /**
  47:  * The <code>MediaPrintableArea</code> attribute specifies the area
  48:  * of a media sheet which is available for printing.
  49:  * <p>
  50:  * Due to hardware limitation its not possible with most printers to use the
  51:  * whole area of a media sheet for printing. This attribute defines the area
  52:  * for printing through the values of the upper left corner position (x,y)
  53:  * on the sheet and the available width and height of the area. The units of
  54:  * the values are determined by two defined constants:
  55:  * <ul>
  56:  * <li>INCH - defines an inch</li>
  57:  * <li>MM - defines a millimeter</li>
  58:  * </ul>
  59:  * </p>
  60:  * <p>
  61:  * <b>Internal storage:</b><br>
  62:  * The values of x, y, width and height are stored internally in micrometers.
  63:  * The values of the provided constants for inch (value 25400) and millimeters
  64:  * (value 1000) are used as conversion factors to the internal storage units.
  65:  * To get the internal micrometers values a multiplication of a given
  66:  * size value with its units constant value is done. Retrieving the size value
  67:  * for specific units is done by dividing the internal stored value by the
  68:  * units constant value.
  69:  * </p>
  70:  * <p>
  71:  * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP 1.1 attribute.
  72:  * </p>
  73:  *
  74:  * @author Michael Koch (konqueror@gmx.de)
  75:  * @author Wolfgang Baer (WBaer@gmx.de)
  76:  */
  77: public final class MediaPrintableArea
  78:   implements DocAttribute, PrintJobAttribute, PrintRequestAttribute
  79: {
  80:   private static final long serialVersionUID = -1597171464050795793L;
  81: 
  82:   /**
  83:    * Constant for the units of inches.
  84:    * The actual value is the conversion factor to micrometers.
  85:    */
  86:   public static final int INCH = 25400;
  87: 
  88:   /**
  89:    * Constant for the units of millimeters.
  90:    * The actual value is the conversion factor to micrometers.
  91:    */
  92:   public static final int MM = 1000;
  93: 
  94:   /** x in micrometers. */
  95:   private int x;
  96:   /** y in micrometers. */
  97:   private int y;
  98:   /** width in micrometers. */
  99:   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&lt; 0 or y i&lt; 0 or w i&lt;= 0
 114:    * or h i&lt;= 0 or units i&lt; 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&lt; 0 or y i&lt; 0 or w i&lt;= 0
 138:    * or h i&lt;= 0 or units i&lt; 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 &lt; 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 &lt; 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 &lt; 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 &lt; 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 &lt; 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: }