001 /* Size2DSyntax.java --
002 Copyright (C) 2003, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.print.attribute;
039
040 import 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 */
082 public 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 }