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