Source for javax.print.attribute.Size2DSyntax

   1: /* Size2DSyntax.java -- 
   2:    Copyright (C) 2003, 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: package javax.print.attribute;
  39: 
  40: import java.io.Serializable;
  41: 
  42: /**
  43:  * <code>Size2DSyntax</code> is the abstract base class of all attribute 
  44:  * classes which provide a two dimensional size as value (e.g. the size of
  45:  * a media like Letter or A4).
  46:  * <p>
  47:  * A <code>Size2DSyntax</code> instance consists of two integer values
  48:  * describing the size in the x and y dimension. The units of 
  49:  * the given values is determined by two defined constants:
  50:  * <ul>
  51:  * <li>INCH - defines an inch</li>
  52:  * <li>MM - defines a millimeter</li>
  53:  * </ul>
  54:  * </p>
  55:  * <p>
  56:  * A size 2D attribute is constructed by two values for the size of the x and
  57:  * y dimension and the actual units of the given values as defined by the 
  58:  * constants.
  59:  * </p>
  60:  * <p>
  61:  * There are different methods provided to return the size values for the
  62:  * dimensions in either of the two predefined units or with a given client
  63:  * supplied units conversion factor.
  64:  * </p>
  65:  * <p>
  66:  * <b>Internal storage:</b><br>
  67:  * The size of the x,y dimensions are stored internally in micrometers. The 
  68:  * values of the provided constants for inch (value 25400) and millimeters
  69:  * (value 1000) are used as conversion factors to the internal storage units.
  70:  * To get the internal micrometers values a multiplication of a given
  71:  * size value with its units constant value is done. Retrieving the size value
  72:  * for specific units is done by dividing the internal stored value by the 
  73:  * units constant value. Clients are therefore able to provide their own 
  74:  * size units by supplying other conversion factors.
  75:  * Subclasses of <code>Size2DSyntax</code> have access to the internal
  76:  * size values through the protected methods 
  77:  * {@link #getXMicrometers()} and {@link #getYMicrometers()}.
  78:  * </p>
  79:  *
  80:  * @author Michael Koch (konqueror@gmx.de)
  81:  */
  82: public abstract class Size2DSyntax implements Cloneable, Serializable
  83: {
  84:   /**
  85:    * Constant for the units of inches.
  86:    * The actual value is the conversion factor to micrometers.
  87:    */
  88:   public static final int INCH = 25400;
  89: 
  90:   /**
  91:    * Constant for the units of millimeters.
  92:    * The actual value is the conversion factor to micrometers.
  93:    */
  94:   public static final int MM = 1000;
  95: 
  96:   /** x size in micrometers. */
  97:   private int x;
  98:   /** y size in micrometers. */
  99:   private int y;
 100: 
 101:   /**
 102:    * Creates a <code>Size2DSyntax</code> object with the given arguments.
 103:    *
 104:    * @param x the size in x direction
 105:    * @param y the size in y direction
 106:    * @param units the units to use for the sizes
 107:    *
 108:    * @exception IllegalArgumentException if x or y &lt; 0 or units &lt; 1
 109:    */
 110:   protected Size2DSyntax(float x, float y, int units)
 111:   {
 112:     if (x < 0.0f || y < 0.0f)
 113:       throw new IllegalArgumentException("x and/or y may not be less than 0");
 114: 
 115:     if (units < 1)
 116:       throw new IllegalArgumentException("units may not be less then 1");
 117: 
 118:     this.x = (int) (x * units + 0.5f);
 119:     this.y = (int) (y * units + 0.5f);
 120:   }
 121: 
 122:   /**
 123:    * Creates a <code>Size2DSyntax</code> object with the given arguments.
 124:    *
 125:    * @param x the size in x direction
 126:    * @param y the size in y direction
 127:    * @param units the units to use for the sizes
 128:    *
 129:    * @exception IllegalArgumentException if x or y &lt; 0 or units &lt; 1
 130:    */
 131:   protected Size2DSyntax(int x, int y, int units)
 132:   {
 133:     if (x < 0 || y < 0)
 134:       throw new IllegalArgumentException("x and/or y may not be less then 0");
 135: 
 136:     if (units < 1)
 137:       throw new IllegalArgumentException("units may not be less then 1");
 138: 
 139:     this.x = x * units;
 140:     this.y = y * units;
 141:   }
 142: 
 143:   /**
 144:    * Tests if the given object is equal to this object.
 145:    *
 146:    * @param obj the object to test
 147:    *
 148:    * @return <code>true</code> if both objects are equal, <code>false</code> otherwise.
 149:    */
 150:   public boolean equals(Object obj)
 151:   {
 152:     if (! (obj instanceof Size2DSyntax))
 153:       return false;
 154: 
 155:     Size2DSyntax tmp = (Size2DSyntax) obj;
 156: 
 157:     return (x == tmp.getXMicrometers()
 158:             && y == tmp.getYMicrometers());
 159:   }
 160: 
 161:   /**
 162:    * Returns the size described in this object as a two field array.
 163:    * Index 0 contains the size in x direction, index 1 the size in
 164:    * y direction.
 165:    *
 166:    * @param units the units to use
 167:    *
 168:    * @return The array with the size dimensions.
 169:    *
 170:    * @exception IllegalArgumentException if units &lt; 1
 171:    */
 172:   public float[] getSize(int units)
 173:   {
 174:     float[] size = new float[2];
 175:     size[0] = getX(units);
 176:     size[1] = getY(units);
 177:     return size;
 178:   }
 179: 
 180:   /**
 181:    * Returns the size in x direction.
 182:    *
 183:    * @param units the units to use
 184:    *
 185:    * @return The size in x direction.
 186:    *
 187:    * @exception IllegalArgumentException if units &lt; 1
 188:    */
 189:   public float getX(int units)
 190:   {
 191:     if (units < 1)
 192:       throw new IllegalArgumentException("units may not be less then 1");
 193: 
 194:     return ((float) x) / ((float) units);
 195:   }
 196: 
 197:   /**
 198:    * Returns the size in x direction in mircometers.
 199:    * To be used by sublcasses that need access to the internal storage value.
 200:    *
 201:    * @return The size in x direction in micrometers.
 202:    */
 203:   protected int getXMicrometers()
 204:   {
 205:     return x;
 206:   }
 207: 
 208:   /**
 209:    * Return the size in y direction.
 210:    *
 211:    * @param units the units to use
 212:    *
 213:    * @return The size in y direction.
 214:    *
 215:    * @exception IllegalArgumentException if units &lt; 1
 216:    */
 217:   public float getY(int units)
 218:   {
 219:     if (units < 1)
 220:       throw new IllegalArgumentException("units may not be less then 1");
 221: 
 222:     return ((float) y) / ((float) units);
 223:   }
 224:   
 225:   /**
 226:    * Returns the size in y direction in mircometers.
 227:    * To be used by sublcasses that need access to the internal storage value.
 228:    *
 229:    * @return The size in y direction in micrometers.
 230:    */
 231:   protected int getYMicrometers()
 232:   {
 233:     return y;
 234:   }
 235: 
 236:   /**
 237:    * Returns the hashcode for this object.
 238:    *
 239:    * @return The hashcode.
 240:    */
 241:   public int hashCode()
 242:   {
 243:     return x + y;
 244:   }
 245: 
 246:   /**
 247:    * Returns the string representation for this object.
 248:    * <p>
 249:    * The returned string is in the form "XxY um" with X standing
 250:    * for size in x and Y for the size in y direction. The used 
 251:    * micrometers units is indicated by the appended "um" notation.
 252:    * </p>
 253:    * 
 254:    * @return The string representation in micrometers.
 255:    */
 256:   public String toString()
 257:   {
 258:     return getXMicrometers() + "x" + getYMicrometers() + " um";
 259:   }
 260: 
 261:   /**
 262:    * Returns the string representation for this object.
 263:    * <p>
 264:    * The returned string is in the form "XxY U" with X standing
 265:    * for size in x and Y for the size in y direction. U denotes 
 266:    * the units name if one is supplied. The values are given as
 267:    * floating point values.
 268:    * </p>
 269:    * 
 270:    * @param units the units to use
 271:    * @param unitsName the name of the units. If <code>null</code>
 272:    * it is ommitted from the string representation.
 273:    *
 274:    * @return The string representation.
 275:    */
 276:   public String toString(int units, String unitsName)
 277:   {
 278:     if (unitsName == null)
 279:       return getX(units) + "x" + getY(units);
 280:     
 281:     return getX(units) + "x" + getY(units) + " " + unitsName;
 282:   }
 283: }