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 &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}