< prev index next >

src/java.desktop/share/classes/javax/print/attribute/standard/MediaPrintableArea.java

Print this page




  37  * dimensions of a media.
  38  * <p>
  39  * Most printers cannot print on the entire surface of the media, due
  40  * to printer hardware limitations. This class can be used to query
  41  * the acceptable values for a supposed print job, and to request an area
  42  * within the constraints of the printable area to be used in a print job.
  43  * <p>
  44  * To query for the printable area, a client must supply a suitable context.
  45  * Without specifying at the very least the size of the media being used
  46  * no meaningful value for printable area can be obtained.
  47  * <p>
  48  * The attribute is not described in terms of the distance from the edge
  49  * of the paper, in part to emphasise that this attribute is not independent
  50  * of a particular media, but must be described within the context of a
  51  * choice of other attributes. Additionally it is usually more convenient
  52  * for a client to use the printable area.
  53  * <p>
  54  * The hardware's minimum margins is not just a property of the printer,
  55  * but may be a function of the media size, orientation, media type, and
  56  * any specified finishings.
  57  * <code>PrintService</code> provides the method to query the supported
  58  * values of an attribute in a suitable context :
  59  * See  {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) PrintService.getSupportedAttributeValues()}
  60  * <p>
  61  * The rectangular printable area is defined thus:
  62  * The (x,y) origin is positioned at the top-left of the paper in portrait
  63  * mode regardless of the orientation specified in the requesting context.
  64  * For example a printable area for A4 paper in portrait or landscape
  65  * orientation will have height {@literal >} width.
  66  * <p>
  67  * A printable area attribute's values are stored
  68  * internally as integers in units of micrometers (µm), where 1 micrometer
  69  * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits
  70  * dimensions to be represented exactly to a precision of 1/1000 mm (= 1
  71  * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
  72 
  73  * negative powers of two, this permits dimensions to be represented exactly to
  74  * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
  75 
  76  * does not equal an integral number of µm).
  77  * <p>


 219      * Get the height of the printable area in the specified units.
 220      * @param  units
 221      *     Unit conversion factor, e.g. {@link #INCH INCH} or
 222      *     {@link #MM MM}.
 223      *
 224      * @return  height of the printable area in the specified units.
 225      *
 226      * @exception  IllegalArgumentException
 227      *     (unchecked exception) Thrown if {@code units < 1}.
 228      */
 229      public float getHeight(int units) {
 230         return convertFromMicrometers(h, units);
 231      }
 232 
 233     /**
 234      * Returns whether this media margins attribute is equivalent to the passed
 235      * in object.
 236      * To be equivalent, all of the following conditions must be true:
 237      * <OL TYPE=1>
 238      * <LI>
 239      * <CODE>object</CODE> is not null.
 240      * <LI>
 241      * <CODE>object</CODE> is an instance of class MediaPrintableArea.
 242      * <LI>
 243      * The origin and dimensions are the same.
 244      * </OL>
 245      *
 246      * @param  object  Object to compare to.
 247      *
 248      * @return  True if <CODE>object</CODE> is equivalent to this media margins
 249      *          attribute, false otherwise.
 250      */
 251     public boolean equals(Object object) {
 252         boolean ret = false;
 253         if (object instanceof MediaPrintableArea) {
 254            MediaPrintableArea mm = (MediaPrintableArea)object;
 255            if (x == mm.x &&  y == mm.y && w == mm.w && h == mm.h) {
 256                ret = true;
 257            }
 258         }
 259         return ret;
 260     }
 261 
 262     /**
 263      * Get the printing attribute class which is to be used as the "category"
 264      * for this printing attribute value.
 265      * <P>
 266      * For class MediaPrintableArea, the category is
 267      * class MediaPrintableArea itself.
 268      *
 269      * @return  Printing attribute class (category), an instance of class
 270      *          {@link java.lang.Class java.lang.Class}.
 271      */
 272     public final Class<? extends Attribute> getCategory() {
 273         return MediaPrintableArea.class;
 274     }
 275 
 276     /**
 277      * Get the name of the category of which this attribute value is an
 278      * instance.
 279      * <P>
 280      * For class MediaPrintableArea,
 281      * the category name is <CODE>"media-printable-area"</CODE>.
 282      * <p>This is not an IPP V1.1 attribute.
 283      *
 284      * @return  Attribute category name.
 285      */
 286     public final String getName() {
 287         return "media-printable-area";
 288     }
 289 
 290     /**
 291      * Returns a string version of this rectangular size attribute in the
 292      * given units.
 293      *
 294      * @param  units
 295      *     Unit conversion factor, e.g. {@link #INCH INCH} or
 296      *     {@link #MM MM}.
 297      * @param  unitsName
 298      *     Units name string, e.g. <CODE>"in"</CODE> or <CODE>"mm"</CODE>. If
 299      *     null, no units name is appended to the result.
 300      *
 301      * @return  String version of this two-dimensional size attribute.
 302      *
 303      * @exception  IllegalArgumentException
 304      *     (unchecked exception) Thrown if {@code units < 1}.
 305      */
 306     public String toString(int units, String unitsName) {
 307         if (unitsName == null) {
 308             unitsName = "";
 309         }
 310         float []vals = getPrintableArea(units);
 311         String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")";
 312         return str + unitsName;
 313     }
 314 
 315     /**
 316      * Returns a string version of this rectangular size attribute in mm.
 317      */
 318     public String toString() {


  37  * dimensions of a media.
  38  * <p>
  39  * Most printers cannot print on the entire surface of the media, due
  40  * to printer hardware limitations. This class can be used to query
  41  * the acceptable values for a supposed print job, and to request an area
  42  * within the constraints of the printable area to be used in a print job.
  43  * <p>
  44  * To query for the printable area, a client must supply a suitable context.
  45  * Without specifying at the very least the size of the media being used
  46  * no meaningful value for printable area can be obtained.
  47  * <p>
  48  * The attribute is not described in terms of the distance from the edge
  49  * of the paper, in part to emphasise that this attribute is not independent
  50  * of a particular media, but must be described within the context of a
  51  * choice of other attributes. Additionally it is usually more convenient
  52  * for a client to use the printable area.
  53  * <p>
  54  * The hardware's minimum margins is not just a property of the printer,
  55  * but may be a function of the media size, orientation, media type, and
  56  * any specified finishings.
  57  * {@code PrintService} provides the method to query the supported
  58  * values of an attribute in a suitable context :
  59  * See  {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) PrintService.getSupportedAttributeValues()}
  60  * <p>
  61  * The rectangular printable area is defined thus:
  62  * The (x,y) origin is positioned at the top-left of the paper in portrait
  63  * mode regardless of the orientation specified in the requesting context.
  64  * For example a printable area for A4 paper in portrait or landscape
  65  * orientation will have height {@literal >} width.
  66  * <p>
  67  * A printable area attribute's values are stored
  68  * internally as integers in units of micrometers (µm), where 1 micrometer
  69  * = 10<SUP>-6</SUP> meter = 1/1000 millimeter = 1/25400 inch. This permits
  70  * dimensions to be represented exactly to a precision of 1/1000 mm (= 1
  71  * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in
  72 
  73  * negative powers of two, this permits dimensions to be represented exactly to
  74  * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch
  75 
  76  * does not equal an integral number of µm).
  77  * <p>


 219      * Get the height of the printable area in the specified units.
 220      * @param  units
 221      *     Unit conversion factor, e.g. {@link #INCH INCH} or
 222      *     {@link #MM MM}.
 223      *
 224      * @return  height of the printable area in the specified units.
 225      *
 226      * @exception  IllegalArgumentException
 227      *     (unchecked exception) Thrown if {@code units < 1}.
 228      */
 229      public float getHeight(int units) {
 230         return convertFromMicrometers(h, units);
 231      }
 232 
 233     /**
 234      * Returns whether this media margins attribute is equivalent to the passed
 235      * in object.
 236      * To be equivalent, all of the following conditions must be true:
 237      * <OL TYPE=1>
 238      * <LI>
 239      * {@code object} is not null.
 240      * <LI>
 241      * {@code object} is an instance of class MediaPrintableArea.
 242      * <LI>
 243      * The origin and dimensions are the same.
 244      * </OL>
 245      *
 246      * @param  object  Object to compare to.
 247      *
 248      * @return  True if {@code object} is equivalent to this media margins
 249      *          attribute, false otherwise.
 250      */
 251     public boolean equals(Object object) {
 252         boolean ret = false;
 253         if (object instanceof MediaPrintableArea) {
 254            MediaPrintableArea mm = (MediaPrintableArea)object;
 255            if (x == mm.x &&  y == mm.y && w == mm.w && h == mm.h) {
 256                ret = true;
 257            }
 258         }
 259         return ret;
 260     }
 261 
 262     /**
 263      * Get the printing attribute class which is to be used as the "category"
 264      * for this printing attribute value.
 265      * <P>
 266      * For class MediaPrintableArea, the category is
 267      * class MediaPrintableArea itself.
 268      *
 269      * @return  Printing attribute class (category), an instance of class
 270      *          {@link java.lang.Class java.lang.Class}.
 271      */
 272     public final Class<? extends Attribute> getCategory() {
 273         return MediaPrintableArea.class;
 274     }
 275 
 276     /**
 277      * Get the name of the category of which this attribute value is an
 278      * instance.
 279      * <P>
 280      * For class MediaPrintableArea,
 281      * the category name is {@code "media-printable-area"}.
 282      * <p>This is not an IPP V1.1 attribute.
 283      *
 284      * @return  Attribute category name.
 285      */
 286     public final String getName() {
 287         return "media-printable-area";
 288     }
 289 
 290     /**
 291      * Returns a string version of this rectangular size attribute in the
 292      * given units.
 293      *
 294      * @param  units
 295      *     Unit conversion factor, e.g. {@link #INCH INCH} or
 296      *     {@link #MM MM}.
 297      * @param  unitsName
 298      *     Units name string, e.g. {@code "in"} or {@code "mm"}. If
 299      *     null, no units name is appended to the result.
 300      *
 301      * @return  String version of this two-dimensional size attribute.
 302      *
 303      * @exception  IllegalArgumentException
 304      *     (unchecked exception) Thrown if {@code units < 1}.
 305      */
 306     public String toString(int units, String unitsName) {
 307         if (unitsName == null) {
 308             unitsName = "";
 309         }
 310         float []vals = getPrintableArea(units);
 311         String str = "("+vals[0]+","+vals[1]+")->("+vals[2]+","+vals[3]+")";
 312         return str + unitsName;
 313     }
 314 
 315     /**
 316      * Returns a string version of this rectangular size attribute in mm.
 317      */
 318     public String toString() {
< prev index next >