001/* MediaPrintableArea.java --
002   Copyright (C) 2005, 2006  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
038
039package javax.print.attribute.standard;
040
041import javax.print.attribute.Attribute;
042import javax.print.attribute.DocAttribute;
043import javax.print.attribute.PrintJobAttribute;
044import javax.print.attribute.PrintRequestAttribute;
045
046/**
047 * The <code>MediaPrintableArea</code> attribute specifies the area
048 * of a media sheet which is available for printing.
049 * <p>
050 * Due to hardware limitation its not possible with most printers to use the
051 * whole area of a media sheet for printing. This attribute defines the area
052 * for printing through the values of the upper left corner position (x,y)
053 * on the sheet and the available width and height of the area. The units of
054 * the values are determined by two defined constants:
055 * <ul>
056 * <li>INCH - defines an inch</li>
057 * <li>MM - defines a millimeter</li>
058 * </ul>
059 * </p>
060 * <p>
061 * <b>Internal storage:</b><br>
062 * The values of x, y, width and height are stored internally in micrometers.
063 * The values of the provided constants for inch (value 25400) and millimeters
064 * (value 1000) are used as conversion factors to the internal storage units.
065 * To get the internal micrometers values a multiplication of a given
066 * size value with its units constant value is done. Retrieving the size value
067 * for specific units is done by dividing the internal stored value by the
068 * units constant value.
069 * </p>
070 * <p>
071 * <b>IPP Compatibility:</b> MediaPrintableArea is not an IPP 1.1 attribute.
072 * </p>
073 *
074 * @author Michael Koch (konqueror@gmx.de)
075 * @author Wolfgang Baer (WBaer@gmx.de)
076 */
077public final class MediaPrintableArea
078  implements DocAttribute, PrintJobAttribute, PrintRequestAttribute
079{
080  private static final long serialVersionUID = -1597171464050795793L;
081
082  /**
083   * Constant for the units of inches.
084   * The actual value is the conversion factor to micrometers.
085   */
086  public static final int INCH = 25400;
087
088  /**
089   * Constant for the units of millimeters.
090   * The actual value is the conversion factor to micrometers.
091   */
092  public static final int MM = 1000;
093
094  /** x in micrometers. */
095  private int x;
096  /** y in micrometers. */
097  private int y;
098  /** width in micrometers. */
099  private int w;
100  /** height in micrometers. */
101  private int h;
102
103  /**
104   * Creates a new <code>MediaPrintableArea</code> object with the given
105   * float values for the given units.
106   *
107   * @param x start of the printable area on the sheet in x direction.
108   * @param y start of the printable area on the sheet in y direction.
109   * @param w the width of the printable area.
110   * @param h the height of the printable area.
111   * @param units the units of the given values.
112   *
113   * @throws IllegalArgumentException if x i&lt; 0 or y i&lt; 0 or w i&lt;= 0
114   * or h i&lt;= 0 or units i&lt; 1
115   */
116  public MediaPrintableArea(float x, float y, float w, float h, int units)
117  {
118    if (x < 0.0f || y < 0.0f || w <= 0.0f || h <= 0.0f)
119      throw new IllegalArgumentException();
120
121    this.x = (int) (x * units + 0.5f);
122    this.y = (int) (y * units + 0.5f);
123    this.w = (int) (w * units + 0.5f);
124    this.h = (int) (h * units + 0.5f);
125  }
126
127  /**
128   * Creates a new <code>MediaPrintableArea</code> object with the given
129   * int values for the given units.
130   *
131   * @param x start of the printable area on the sheet in x direction.
132   * @param y start of the printable area on the sheet in y direction.
133   * @param w the width of the printable area.
134   * @param h the height of the printable area.
135   * @param units the units of the given values.
136   *
137   * @throws IllegalArgumentException if x i&lt; 0 or y i&lt; 0 or w i&lt;= 0
138   * or h i&lt;= 0 or units i&lt; 1
139   */
140  public MediaPrintableArea(int x, int y, int w, int h, int units)
141  {
142    if (x < 0 || y < 0 || w <= 0 || h <= 0)
143      throw new IllegalArgumentException();
144
145    this.x = x * units;
146    this.y = y * units;
147    this.w = w * units;
148    this.h = h * units;
149  }
150
151  /**
152   * Returns category of this class.
153   *
154   * @return The class <code>MediaPrintableArea</code> itself.
155   */
156  public Class< ? extends Attribute> getCategory()
157  {
158    return MediaPrintableArea.class;
159  }
160
161  /**
162   * Returns the name of this attribute.
163   *
164   * @return The name "media-printable-area".
165   */
166  public String getName()
167  {
168    return "media-printable-area";
169  }
170
171  /**
172   * Returns the height of the printable area for the given units.
173   *
174   * @param units the units conversion factor.
175   * @return The height.
176   *
177   * @throws IllegalArgumentException if <code>units</code> is &lt; 1
178   */
179  public float getHeight(int units)
180  {
181    if (units < 1)
182      throw new IllegalArgumentException("units may not be less than 1");
183
184    return h / ((float)units);
185  }
186
187  /**
188   * Returns the width of the printable area for the given units.
189   *
190   * @param units the units conversion factor.
191   * @return The width.
192   *
193   * @throws IllegalArgumentException if <code>units</code> is &lt; 1
194   */
195  public float getWidth(int units)
196  {
197    if (units < 1)
198      throw new IllegalArgumentException("units may not be less than 1");
199
200    return w / ((float)units);
201  }
202
203  /**
204   * Returns the position in x direction of the printable area
205   * for the given units.
206   *
207   * @param units the units conversion factor.
208   * @return The position in x direction.
209   *
210   * @throws IllegalArgumentException if <code>units</code> is &lt; 1
211   */
212  public float getX(int units)
213  {
214    if (units < 1)
215      throw new IllegalArgumentException("units may not be less than 1");
216
217    return x / ((float)units);
218  }
219
220  /**
221   * Returns the position in y direction of the printable area
222   * for the given units.
223   *
224   * @param units the units conversion factor.
225   * @return The position in y direction.
226   *
227   * @throws IllegalArgumentException if <code>units</code> is &lt; 1
228   */
229  public float getY(int units)
230  {
231    if (units < 1)
232      throw new IllegalArgumentException("units may not be less than 1");
233
234    return y / ((float)units);
235  }
236
237  /**
238   * Tests if the given object is equal to this object.
239   *
240   * @param obj the object to test
241   *
242   * @return <code>true</code> if both objects are equal, <code>false</code> otherwise.
243   */
244  public boolean equals(Object obj)
245  {
246    if (! (obj instanceof MediaPrintableArea))
247      return false;
248
249    MediaPrintableArea tmp = (MediaPrintableArea) obj;
250
251    return (x == tmp.getX(1) && y == tmp.getY(1)
252            && w == tmp.getWidth(1) && h == tmp.getHeight(1));
253  }
254
255  /**
256   * Returns the string representation for this object in units of millimeters..
257   * <p>
258   * The returned string is in the form "(x,y)->(width,height)mm".
259   * </p>
260   * @return The string representation in millimeters.
261   */
262  public String toString()
263  {
264    return toString(MM, "mm");
265  }
266
267  /**
268   * Returns the hashcode for this object.
269   *
270   * @return The hashcode.
271   */
272  public int hashCode()
273  {
274    return x ^ y + w ^ h;
275  }
276
277  /**
278   * Returns the string representation for this object in units of millimeters..
279   * <p>
280   * The returned string is in the form "(x,y)->(width,height)unitsName".
281   * </p>
282   * @param units the units to use for conversion.
283   * @param unitsName the name of the used units, appended to the resulting
284   * string if not <code>null</code>.
285   * @return The string representation in millimeters.
286   *
287   * @throws IllegalArgumentException if <code>units</code> is &lt; 1
288   */
289  public String toString(int units, String unitsName)
290  {
291    if (units < 1)
292      throw new IllegalArgumentException("units may not be less than 1");
293
294    String tmp = "(" + getX(units) + "," + getY(units) + ")->("
295                 + getWidth(units) + "," + getHeight(units) + ")";
296
297    return unitsName == null ? tmp : tmp + unitsName;
298  }
299
300  /**
301   * Returns the printable area as an float[] with 4 values
302   * (order x, y, width, height) in the given units.
303   *
304   * @param units the units to use.
305   * @return The printable area as float array.
306   */
307  public float[] getPrintableArea(int units)
308  {
309    return new float[] { getX(units), getY(units),
310                         getWidth(units), getHeight(units) };
311  }
312}