libjava/classpath/javax/print/attribute/standard/MediaPrintableArea.java

   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.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 w;
  99   /** height in micrometers. */
 100   private int h;
 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.w = (int) (w * units + 0.5f);
 123     this.h = (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.w = w * units;
 147     this.h = 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 h / ((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 w / ((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             && w == tmp.getWidth(1) && h == 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 + w ^ h;
 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 }