Home » openjdk-7 » java » awt » font » [javadoc | source]

    1   /*
    2    * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   /*
   27    * @author Charlton Innovations, Inc.
   28    */
   29   
   30   package java.awt.font;
   31   
   32   import java.awt.RenderingHints;
   33   import static java.awt.RenderingHints.*;
   34   import java.awt.geom.AffineTransform;
   35   
   36   /**
   37   *   The <code>FontRenderContext</code> class is a container for the
   38   *   information needed to correctly measure text.  The measurement of text
   39   *   can vary because of rules that map outlines to pixels, and rendering
   40   *   hints provided by an application.
   41   *   <p>
   42   *   One such piece of information is a transform that scales
   43   *   typographical points to pixels. (A point is defined to be exactly 1/72
   44   *   of an inch, which is slightly different than
   45   *   the traditional mechanical measurement of a point.)  A character that
   46   *   is rendered at 12pt on a 600dpi device might have a different size
   47   *   than the same character rendered at 12pt on a 72dpi device because of
   48   *   such factors as rounding to pixel boundaries and hints that the font
   49   *   designer may have specified.
   50   *   <p>
   51   *   Anti-aliasing and Fractional-metrics specified by an application can also
   52   *   affect the size of a character because of rounding to pixel
   53   *   boundaries.
   54   *   <p>
   55   *   Typically, instances of <code>FontRenderContext</code> are
   56   *   obtained from a {@link java.awt.Graphics2D Graphics2D} object.  A
   57   *   <code>FontRenderContext</code> which is directly constructed will
   58   *   most likely not represent any actual graphics device, and may lead
   59   *   to unexpected or incorrect results.
   60   *   <p>
   61   *   @see java.awt.RenderingHints#KEY_TEXT_ANTIALIASING
   62   *   @see java.awt.RenderingHints#KEY_FRACTIONALMETRICS
   63   *   @see java.awt.Graphics2D#getFontRenderContext()
   64   *   @see java.awt.font.LineMetrics
   65   */
   66   
   67   public class FontRenderContext {
   68       private transient AffineTransform tx;
   69       private transient Object aaHintValue;
   70       private transient Object fmHintValue;
   71       private transient boolean defaulting;
   72   
   73       /**
   74        * Constructs a new <code>FontRenderContext</code>
   75        * object.
   76        *
   77        */
   78       protected FontRenderContext() {
   79           aaHintValue = VALUE_TEXT_ANTIALIAS_DEFAULT;
   80           fmHintValue = VALUE_FRACTIONALMETRICS_DEFAULT;
   81           defaulting = true;
   82       }
   83   
   84       /**
   85        * Constructs a <code>FontRenderContext</code> object from an
   86        * optional {@link AffineTransform} and two <code>boolean</code>
   87        * values that determine if the newly constructed object has
   88        * anti-aliasing or fractional metrics.
   89        * In each case the boolean values <CODE>true</CODE> and <CODE>false</CODE>
   90        * correspond to the rendering hint values <CODE>ON</CODE> and
   91        * <CODE>OFF</CODE> respectively.
   92        * <p>
   93        * To specify other hint values, use the constructor which
   94        * specifies the rendering hint values as parameters :
   95        * {@link #FontRenderContext(AffineTransform, Object, Object)}.
   96        * @param tx the transform which is used to scale typographical points
   97        * to pixels in this <code>FontRenderContext</code>.  If null, an
   98        * identity transform is used.
   99        * @param isAntiAliased determines if the newly constructed object
  100        * has anti-aliasing.
  101        * @param usesFractionalMetrics determines if the newly constructed
  102        * object has fractional metrics.
  103        */
  104       public FontRenderContext(AffineTransform tx,
  105                               boolean isAntiAliased,
  106                               boolean usesFractionalMetrics) {
  107           if (tx != null && !tx.isIdentity()) {
  108               this.tx = new AffineTransform(tx);
  109           }
  110           if (isAntiAliased) {
  111               aaHintValue = VALUE_TEXT_ANTIALIAS_ON;
  112           } else {
  113               aaHintValue = VALUE_TEXT_ANTIALIAS_OFF;
  114           }
  115           if (usesFractionalMetrics) {
  116               fmHintValue = VALUE_FRACTIONALMETRICS_ON;
  117           } else {
  118               fmHintValue = VALUE_FRACTIONALMETRICS_OFF;
  119           }
  120       }
  121   
  122       /**
  123        * Constructs a <code>FontRenderContext</code> object from an
  124        * optional {@link AffineTransform} and two <code>Object</code>
  125        * values that determine if the newly constructed object has
  126        * anti-aliasing or fractional metrics.
  127        * @param tx the transform which is used to scale typographical points
  128        * to pixels in this <code>FontRenderContext</code>.  If null, an
  129        * identity tranform is used.
  130        * @param aaHint - one of the text antialiasing rendering hint values
  131        * defined in {@link java.awt.RenderingHints java.awt.RenderingHints}.
  132        * Any other value will throw <code>IllegalArgumentException</code>.
  133        * {@link java.awt.RenderingHints#VALUE_TEXT_ANTIALIAS_DEFAULT VALUE_TEXT_ANTIALIAS_DEFAULT}
  134        * may be specified, in which case the mode used is implementation
  135        * dependent.
  136        * @param fmHint - one of the text fractional rendering hint values defined
  137        * in {@link java.awt.RenderingHints java.awt.RenderingHints}.
  138        * {@link java.awt.RenderingHints#VALUE_FRACTIONALMETRICS_DEFAULT VALUE_FRACTIONALMETRICS_DEFAULT}
  139        * may be specified, in which case the mode used is implementation
  140        * dependent.
  141        * Any other value will throw <code>IllegalArgumentException</code>
  142        * @throws IllegalArgumentException if the hints are not one of the
  143        * legal values.
  144        * @since 1.6
  145        */
  146       public FontRenderContext(AffineTransform tx, Object aaHint, Object fmHint){
  147           if (tx != null && !tx.isIdentity()) {
  148               this.tx = new AffineTransform(tx);
  149           }
  150           try {
  151               if (KEY_TEXT_ANTIALIASING.isCompatibleValue(aaHint)) {
  152                   aaHintValue = aaHint;
  153               } else {
  154                   throw new IllegalArgumentException("AA hint:" + aaHint);
  155               }
  156           } catch (Exception e) {
  157               throw new IllegalArgumentException("AA hint:" +aaHint);
  158           }
  159           try {
  160               if (KEY_FRACTIONALMETRICS.isCompatibleValue(fmHint)) {
  161                   fmHintValue = fmHint;
  162               } else {
  163                   throw new IllegalArgumentException("FM hint:" + fmHint);
  164               }
  165           } catch (Exception e) {
  166               throw new IllegalArgumentException("FM hint:" +fmHint);
  167           }
  168       }
  169   
  170       /**
  171        * Indicates whether or not this <code>FontRenderContext</code> object
  172        * measures text in a transformed render context.
  173        * @return  <code>true</code> if this <code>FontRenderContext</code>
  174        *          object has a non-identity AffineTransform attribute.
  175        *          <code>false</code> otherwise.
  176        * @see     java.awt.font.FontRenderContext#getTransform
  177        * @since   1.6
  178        */
  179       public boolean isTransformed() {
  180           if (!defaulting) {
  181               return tx != null;
  182           } else {
  183               return !getTransform().isIdentity();
  184           }
  185       }
  186   
  187       /**
  188        * Returns the integer type of the affine transform for this
  189        * <code>FontRenderContext</code> as specified by
  190        * {@link java.awt.geom.AffineTransform#getType()}
  191        * @return the type of the transform.
  192        * @see AffineTransform
  193        * @since 1.6
  194        */
  195       public int getTransformType() {
  196           if (!defaulting) {
  197               if (tx == null) {
  198                   return AffineTransform.TYPE_IDENTITY;
  199               } else {
  200                   return tx.getType();
  201               }
  202           } else {
  203               return getTransform().getType();
  204           }
  205       }
  206   
  207       /**
  208       *   Gets the transform that is used to scale typographical points
  209       *   to pixels in this <code>FontRenderContext</code>.
  210       *   @return the <code>AffineTransform</code> of this
  211       *    <code>FontRenderContext</code>.
  212       *   @see AffineTransform
  213       */
  214       public AffineTransform getTransform() {
  215           return (tx == null) ? new AffineTransform() : new AffineTransform(tx);
  216       }
  217   
  218       /**
  219       * Returns a boolean which indicates whether or not some form of
  220       * antialiasing is specified by this <code>FontRenderContext</code>.
  221       * Call {@link #getAntiAliasingHint() getAntiAliasingHint()}
  222       * for the specific rendering hint value.
  223       *   @return    <code>true</code>, if text is anti-aliased in this
  224       *   <code>FontRenderContext</code>; <code>false</code> otherwise.
  225       *   @see        java.awt.RenderingHints#KEY_TEXT_ANTIALIASING
  226       *   @see #FontRenderContext(AffineTransform,boolean,boolean)
  227       *   @see #FontRenderContext(AffineTransform,Object,Object)
  228       */
  229       public boolean isAntiAliased() {
  230           return !(aaHintValue == VALUE_TEXT_ANTIALIAS_OFF ||
  231                    aaHintValue == VALUE_TEXT_ANTIALIAS_DEFAULT);
  232       }
  233   
  234       /**
  235       * Returns a boolean which whether text fractional metrics mode
  236       * is used in this <code>FontRenderContext</code>.
  237       * Call {@link #getFractionalMetricsHint() getFractionalMetricsHint()}
  238       * to obtain the corresponding rendering hint value.
  239       *   @return    <code>true</code>, if layout should be performed with
  240       *   fractional metrics; <code>false</code> otherwise.
  241       *               in this <code>FontRenderContext</code>.
  242       *   @see java.awt.RenderingHints#KEY_FRACTIONALMETRICS
  243       *   @see #FontRenderContext(AffineTransform,boolean,boolean)
  244       *   @see #FontRenderContext(AffineTransform,Object,Object)
  245       */
  246       public boolean usesFractionalMetrics() {
  247           return !(fmHintValue == VALUE_FRACTIONALMETRICS_OFF ||
  248                    fmHintValue == VALUE_FRACTIONALMETRICS_DEFAULT);
  249       }
  250   
  251       /**
  252        * Return the text anti-aliasing rendering mode hint used in this
  253        * <code>FontRenderContext</code>.
  254        * This will be one of the text antialiasing rendering hint values
  255        * defined in {@link java.awt.RenderingHints java.awt.RenderingHints}.
  256        * @return  text anti-aliasing rendering mode hint used in this
  257        * <code>FontRenderContext</code>.
  258        * @since 1.6
  259        */
  260       public Object getAntiAliasingHint() {
  261           if (defaulting) {
  262               if (isAntiAliased()) {
  263                    return VALUE_TEXT_ANTIALIAS_ON;
  264               } else {
  265                   return VALUE_TEXT_ANTIALIAS_OFF;
  266               }
  267           }
  268           return aaHintValue;
  269       }
  270   
  271       /**
  272        * Return the text fractional metrics rendering mode hint used in this
  273        * <code>FontRenderContext</code>.
  274        * This will be one of the text fractional metrics rendering hint values
  275        * defined in {@link java.awt.RenderingHints java.awt.RenderingHints}.
  276        * @return the text fractional metrics rendering mode hint used in this
  277        * <code>FontRenderContext</code>.
  278        * @since 1.6
  279        */
  280       public Object getFractionalMetricsHint() {
  281           if (defaulting) {
  282               if (usesFractionalMetrics()) {
  283                    return VALUE_FRACTIONALMETRICS_ON;
  284               } else {
  285                   return VALUE_FRACTIONALMETRICS_OFF;
  286               }
  287           }
  288           return fmHintValue;
  289       }
  290   
  291       /**
  292        * Return true if obj is an instance of FontRenderContext and has the same
  293        * transform, antialiasing, and fractional metrics values as this.
  294        * @param obj the object to test for equality
  295        * @return <code>true</code> if the specified object is equal to
  296        *         this <code>FontRenderContext</code>; <code>false</code>
  297        *         otherwise.
  298        */
  299       public boolean equals(Object obj) {
  300           try {
  301               return equals((FontRenderContext)obj);
  302           }
  303           catch (ClassCastException e) {
  304               return false;
  305           }
  306       }
  307   
  308       /**
  309        * Return true if rhs has the same transform, antialiasing,
  310        * and fractional metrics values as this.
  311        * @param rhs the <code>FontRenderContext</code> to test for equality
  312        * @return <code>true</code> if <code>rhs</code> is equal to
  313        *         this <code>FontRenderContext</code>; <code>false</code>
  314        *         otherwise.
  315        * @since 1.4
  316        */
  317       public boolean equals(FontRenderContext rhs) {
  318           if (this == rhs) {
  319               return true;
  320           }
  321           if (rhs == null) {
  322               return false;
  323           }
  324   
  325           /* if neither instance is a subclass, reference values directly. */
  326           if (!rhs.defaulting && !defaulting) {
  327               if (rhs.aaHintValue == aaHintValue &&
  328                   rhs.fmHintValue == fmHintValue) {
  329   
  330                   return tx == null ? rhs.tx == null : tx.equals(rhs.tx);
  331               }
  332               return false;
  333           } else {
  334               return
  335                   rhs.getAntiAliasingHint() == getAntiAliasingHint() &&
  336                   rhs.getFractionalMetricsHint() == getFractionalMetricsHint() &&
  337                   rhs.getTransform().equals(getTransform());
  338           }
  339       }
  340   
  341       /**
  342        * Return a hashcode for this FontRenderContext.
  343        */
  344       public int hashCode() {
  345           int hash = tx == null ? 0 : tx.hashCode();
  346           /* SunHints value objects have identity hashcode, so we can rely on
  347            * this to ensure that two equal FRC's have the same hashcode.
  348            */
  349           if (defaulting) {
  350               hash += getAntiAliasingHint().hashCode();
  351               hash += getFractionalMetricsHint().hashCode();
  352           } else {
  353               hash += aaHintValue.hashCode();
  354               hash += fmHintValue.hashCode();
  355           }
  356           return hash;
  357       }
  358   }

Home » openjdk-7 » java » awt » font » [javadoc | source]