MediaPrintableArea


1   /*
2    * @(#)MediaPrintableArea.java  1.12 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package javax.print.attribute.standard;
8   
9   import javax.print.attribute.Attribute  ;
10  import javax.print.attribute.DocAttribute  ;
11  import javax.print.attribute.PrintJobAttribute  ;
12  import javax.print.attribute.PrintRequestAttribute  ;
13  
14  /**
15   * Class MediaPrintableArea is a printing attribute used to distinguish
16   * the printable and non-printable areas of media.
17   * <p>
18   * The printable area is specified to be a rectangle, within the overall
19   * dimensions of a media. 
20   * <p>
21   * Most printers cannot print on the entire surface of the media, due
22   * to printer hardware limitations. This class can be used to query
23   * the acceptable values for a supposed print job, and to request an area
24   * within the constraints of the printable area to be used in a print job.
25   * <p>
26   * To query for the printable area, a client must supply a suitable context.
27   * Without specifying at the very least the size of the media being used
28   * no meaningful value for printable area can be obtained.
29   * <p>
30   * The attribute is not described in terms of the distance from the edge
31   * of the paper, in part to emphasise that this attribute is not independent
32   * of a particular media, but must be described within the context of a
33   * choice of other attributes. Additionally it is usually more convenient
34   * for a client to use the printable area.
35   * <p>
36   * The hardware's minimum margins is not just a property of the printer,
37   * but may be a function of the media size, orientation, media type, and
38   * any specified finishings.
39   * <code>PrintService</code> provides the method to query the supported
40   * values of an attribute in a suitable context :
41   * See  {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) <code>PrintService.getSupportedAttributeValues()</code>}
42   * <p>
43   * The rectangular printable area is defined thus:
44   * The (x,y) origin is positioned at the top-left of the paper in portrait
45   * mode regardless of the orientation specified in the requesting context.
46   * For example a printable area for A4 paper in portrait or landscape 
47   * orientation will have height > width.
48   * <p>
49   * A printable area attribute's values are stored
50   * internally as integers in units of micrometers (&#181;m), where 1 micrometer
51   * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits
52   * dimensions to be represented exactly to a precision of 1/1000 mm (= 1
53   * &#181;m) or 1/100 inch (= 254 &#181;m). If fractional inches are expressed in
54  
55   * negative powers of two, this permits dimensions to be represented exactly to
56   * a precision of 1/8 inch (= 3175 &#181;m) but not 1/16 inch (because 1/16 inch
57  
58   * does not equal an integral number of &#181;m).
59   * <p>
60   * <B>IPP Compatibility:</B> MediaPrintableArea is not an IPP attribute.
61   */
62  
63  public final class MediaPrintableArea 
64        implements DocAttribute  , PrintRequestAttribute  , PrintJobAttribute   {
65  
66      private int x, y, w, h;
67      private int units;
68  
69      private static final long serialVersionUID = -1597171464050795793L;
70  
71      /**
72       * Value to indicate units of inches (in). It is actually the conversion
73       * factor by which to multiply inches to yield &#181;m (25400).
74       */
75      public static final int INCH = 25400;
76  
77      /**
78       * Value to indicate units of millimeters (mm). It is actually the
79       * conversion factor by which to multiply mm to yield &#181;m (1000).
80       */
81      public static final int MM = 1000;
82  
83      /**
84        * Constructs a MediaPrintableArea object from floating point values.
85        * @param x      printable x
86        * @param y      printable y
87        * @param w      printable width
88        * @param h      printable height
89        * @param units  in which the values are expressed.
90        *
91        * @exception  IllegalArgumentException
92        *     Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0
93        *     or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or 
94        *     <CODE>units</CODE> < 1.
95        */
96      public MediaPrintableArea(float x, float y, float w, float h, int units) {
97      if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) ||
98          (units < 1)) {
99          throw new IllegalArgumentException  ("0 or negative value argument");
100     }
101 
102         this.x = (int) (x * units + 0.5f);
103         this.y = (int) (y * units + 0.5f);
104         this.w = (int) (w * units + 0.5f);
105         this.h = (int) (h * units + 0.5f);
106  
107     } 
108 
109     /**
110       * Constructs a MediaPrintableArea object from integer values.
111       * @param x      printable x
112       * @param y      printable y
113       * @param w      printable width
114       * @param h      printable height
115       * @param units  in which the values are expressed.
116       * 
117       * @exception  IllegalArgumentException
118       *     Thrown if <CODE>x</CODE> < 0 or <CODE>y</CODE> < 0
119       *     or <CODE>w</CODE> <= 0 or <CODE>h</CODE> <= 0 or 
120       *     <CODE>units</CODE> < 1.
121       */
122     public MediaPrintableArea(int x, int y, int w, int h, int units) {
123     if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) ||
124         (units < 1)) {
125         throw new IllegalArgumentException  ("0 or negative value argument");
126     }
127         this.x = x * units;
128         this.y = y * units;
129         this.w = w * units;
130         this.h = h * units;
131 
132     } 
133 
134     /**
135      * Get the printable area as an array of 4 values in the order
136      * x, y, w, h. The values returned are in the given units.
137      * @param  units
138      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
139      *     {@link #MM <CODE>MM</CODE>}.
140      *
141      * @return printable area as array of x, y, w, h in the specified units.
142      *
143      * @exception  IllegalArgumentException
144      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
145      */
146     public float[] getPrintableArea(int units) {
147         return new float[] { getX(units), getY(units),
148                              getWidth(units), getHeight(units) };
149     }
150 
151     /**
152      * Get the x location of the origin of the printable area in the
153      * specified units.
154      * @param  units
155      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
156      *     {@link #MM <CODE>MM</CODE>}.
157      *
158      * @return  x location of the origin of the printable area in the
159      * specified units.
160      *
161      * @exception  IllegalArgumentException
162      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
163      */
164      public float getX(int units) {
165         return convertFromMicrometers(x, units);
166      }
167 
168     /**
169      * Get the y location of the origin of the printable area in the
170      * specified units.
171      * @param  units
172      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
173      *     {@link #MM <CODE>MM</CODE>}.
174      *
175      * @return  y location of the origin of the printable area in the
176      * specified units.
177      *
178      * @exception  IllegalArgumentException
179      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
180      */
181      public float getY(int units) {
182         return convertFromMicrometers(y, units);
183      }
184 
185     /**
186      * Get the width of the printable area in the specified units.
187      * @param  units
188      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
189      *     {@link #MM <CODE>MM</CODE>}.
190      *
191      * @return  width of the printable area in the specified units.
192      *
193      * @exception  IllegalArgumentException
194      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
195      */
196      public float getWidth(int units) {
197         return convertFromMicrometers(w, units);
198      }
199 
200     /**
201      * Get the height of the printable area in the specified units.
202      * @param  units
203      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
204      *     {@link #MM <CODE>MM</CODE>}.
205      *
206      * @return  height of the printable area in the specified units.
207      *
208      * @exception  IllegalArgumentException
209      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
210      */
211      public float getHeight(int units) {
212         return convertFromMicrometers(h, units);
213      }
214 
215     /**
216      * Returns whether this media margins attribute is equivalent to the passed
217      * in object.
218      * To be equivalent, all of the following conditions must be true:
219      * <OL TYPE=1>
220      * <LI>
221      * <CODE>object</CODE> is not null.
222      * <LI>
223      * <CODE>object</CODE> is an instance of class MediaPrintableArea.
224      * <LI>
225      * The origin and dimensions are the same.
226      * </OL>
227      *
228      * @param  object  Object to compare to.
229      *
230      * @return  True if <CODE>object</CODE> is equivalent to this media margins
231      *          attribute, false otherwise.
232      */
233     public boolean equals(Object   object) {
234         boolean ret = false;
235         if (object instanceof MediaPrintableArea  ) {
236            MediaPrintableArea   mm = (MediaPrintableArea  )object;
237            if (x == mm.x &&  y == mm.y && w == mm.w && h == mm.h) {
238                ret = true;
239            }
240         }
241         return ret;
242     }
243 
244     /**
245      * Get the printing attribute class which is to be used as the "category"
246      * for this printing attribute value.
247      * <P>
248      * For class MediaPrintableArea, the category is
249      * class MediaPrintableArea itself.
250      *
251      * @return  Printing attribute class (category), an instance of class
252      *          {@link java.lang.Class java.lang.Class}.
253      */
254     public final Class  <? extends Attribute  > getCategory() {
255         return MediaPrintableArea  .class;
256     }
257 
258     /**
259      * Get the name of the category of which this attribute value is an
260      * instance.
261      * <P>
262      * For class MediaPrintableArea,
263      * the category name is <CODE>"media-printable-area"</CODE>.
264      * <p>This is not an IPP V1.1 attribute.
265      *
266      * @return  Attribute category name.
267      */
268     public final String   getName() {
269         return "media-printable-area";
270     }
271 
272     /**
273      * Returns a string version of this rectangular size attribute in the
274      * given units.
275      *
276      * @param  units
277      *     Unit conversion factor, e.g. {@link #INCH <CODE>INCH</CODE>} or
278      *     {@link #MM <CODE>MM</CODE>}.
279      * @param  unitsName
280      *     Units name string, e.g. <CODE>"in"</CODE> or <CODE>"mm"</CODE>. If
281      *     null, no units name is appended to the result.
282      *
283      * @return  String version of this two-dimensional size attribute.
284      *
285      * @exception  IllegalArgumentException
286      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1.
287      */
288     public String   toString(int units, String   unitsName) {
289         if (unitsName == null) {
290             unitsName = "";
291         }
292     float []vals = getPrintableArea(units);
293         String   str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")";
294         return str + unitsName;
295     }
296 
297     /**
298      * Returns a string version of this rectangular size attribute in mm.
299      */
300     public String   toString() {
301         return(toString(MM, "mm"));
302     }
303 
304     /**
305      * Returns a hash code value for this attribute.
306      */
307     public int hashCode() {
308     return x + 37*y + 43*w + 47*h;
309     }
310 
311     private static float convertFromMicrometers(int x, int units) {
312         if (units < 1) {
313             throw new IllegalArgumentException  ("units is < 1");
314         }
315         return ((float)x) / ((float)units);
316     }
317 }
318
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags