001/* Size2DSyntax.java -- 002 Copyright (C) 2003, 2005 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 038package javax.print.attribute; 039 040import java.io.Serializable; 041 042/** 043 * <code>Size2DSyntax</code> is the abstract base class of all attribute 044 * classes which provide a two dimensional size as value (e.g. the size of 045 * a media like Letter or A4). 046 * <p> 047 * A <code>Size2DSyntax</code> instance consists of two integer values 048 * describing the size in the x and y dimension. The units of 049 * the given values is determined by two defined constants: 050 * <ul> 051 * <li>INCH - defines an inch</li> 052 * <li>MM - defines a millimeter</li> 053 * </ul> 054 * </p> 055 * <p> 056 * A size 2D attribute is constructed by two values for the size of the x and 057 * y dimension and the actual units of the given values as defined by the 058 * constants. 059 * </p> 060 * <p> 061 * There are different methods provided to return the size values for the 062 * dimensions in either of the two predefined units or with a given client 063 * supplied units conversion factor. 064 * </p> 065 * <p> 066 * <b>Internal storage:</b><br> 067 * The size of the x,y dimensions are stored internally in micrometers. The 068 * values of the provided constants for inch (value 25400) and millimeters 069 * (value 1000) are used as conversion factors to the internal storage units. 070 * To get the internal micrometers values a multiplication of a given 071 * size value with its units constant value is done. Retrieving the size value 072 * for specific units is done by dividing the internal stored value by the 073 * units constant value. Clients are therefore able to provide their own 074 * size units by supplying other conversion factors. 075 * Subclasses of <code>Size2DSyntax</code> have access to the internal 076 * size values through the protected methods 077 * {@link #getXMicrometers()} and {@link #getYMicrometers()}. 078 * </p> 079 * 080 * @author Michael Koch (konqueror@gmx.de) 081 */ 082public abstract class Size2DSyntax implements Cloneable, Serializable 083{ 084 /** 085 * Constant for the units of inches. 086 * The actual value is the conversion factor to micrometers. 087 */ 088 public static final int INCH = 25400; 089 090 /** 091 * Constant for the units of millimeters. 092 * The actual value is the conversion factor to micrometers. 093 */ 094 public static final int MM = 1000; 095 096 /** x size in micrometers. */ 097 private int x; 098 /** y size in micrometers. */ 099 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 < 0 or units < 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 < 0 or units < 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 < 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 < 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 < 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}