home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / FontMetrics.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  12.4 KB  |  335 lines
  1. /*
  2.  * @(#)FontMetrics.java    1.21 98/03/18
  3.  *
  4.  * Copyright 1995-1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. /** 
  18.  * A font metrics object, which gives information about the rendering 
  19.  * of a particular font on a particular screen. Note that the 
  20.  * implementations of these methods are inefficient, they are usually 
  21.  * overridden with more efficient toolkit-specific implementations.
  22.  * <p>
  23.  * <b>Note to subclassers</b>: Since many of these methods form closed
  24.  * mutually recursive loops, you must take care that you implement
  25.  * at least one of the methods in each such loop in order to prevent
  26.  * infinite recursion when your subclass is used.
  27.  * In particular, the following is the minimal suggested set of methods
  28.  * to override in order to ensure correctness and prevent infinite
  29.  * recursion (though other subsets are equally feasible):
  30.  * <ul>
  31.  * <li><a href="#getAscent">getAscent</a>()
  32.  * <li><a href="#getAscent">getDescent</a>()
  33.  * <li><a href="#getLeading">getLeading</a>()
  34.  * <li><a href="#getMaxAdvance">getMaxAdvance</a>()
  35.  * <li><a href="#charWidth(char)">charWidth</a>(char ch)
  36.  * <li><a href="#charsWidth(char[], int, int)">charsWidth</a>(char data[], int off, int len)
  37.  * </ul>
  38.  * <p>
  39.  * <img src="images-awt/FontMetrics-1.gif" border=15 align
  40.  * ALIGN=right HSPACE=10 VSPACE=7>
  41.  * When an application asks AWT to place a character at the position 
  42.  * (<i>x</i>, <i>y</i>), the character is placed so that its 
  43.  * reference point (shown as the dot in the accompanying image) is 
  44.  * put at that position. The reference point specifies a horizontal 
  45.  * line called the <i>baseline</i> of the character. In normal 
  46.  * printing, the baselines of characters should align. 
  47.  * <p> 
  48.  * In addition, every character in a font has an <i>ascent</i>, a 
  49.  * <i>descent</i>, and an <i>advance width</i>. The ascent is the 
  50.  * amount by which the character ascends above the baseline. The 
  51.  * descent is the amount by which the character descends below the 
  52.  * baseline. The advance width indicates the position at which AWT  
  53.  * should place the next character. 
  54.  * <p>
  55.  * If the current character is placed with its reference point 
  56.  * at the position (<i>x</i>, <i>y</i>), and 
  57.  * the character's advance width is <i>w</i>, then the following 
  58.  * character is placed with its reference point at the position 
  59.  * (<i>x </i><code>+</code><i> w</i>, <i>y</i>). 
  60.  * The advance width is often the same as the width of character's 
  61.  * bounding box, but need not be so. In particular, oblique and 
  62.  * italic fonts often have characters whose top-right corner extends 
  63.  * slightly beyond the advance width. 
  64.  * <p>
  65.  * An array of characters or a string can also have an ascent, a 
  66.  * descent, and an advance width. The ascent of the array is the 
  67.  * maximum ascent of any character in the array. The descent is the 
  68.  * maximum descent of any character in the array. The advance width 
  69.  * is the sum of the advance widths of each of the characters in the 
  70.  * array. 
  71.  * @version     1.21 03/18/98
  72.  * @author     Jim Graham
  73.  * @see         java.awt.Font
  74.  * @since       JDK1.0
  75.  */
  76. public abstract class FontMetrics implements java.io.Serializable {
  77.  
  78.     static {
  79.         initIDs();
  80.     }
  81.  
  82.     /**
  83.      * The actual font.
  84.      * @see #getFont
  85.      */
  86.     protected Font font;
  87.  
  88.     /*
  89.      * JDK 1.1 serialVersionUID 
  90.      */
  91.     private static final long serialVersionUID = 1681126225205050147L;
  92.  
  93.     /**
  94.      * Creates a new <code>FontMetrics</code> object for finding out 
  95.      * height and width information about the specified font and  
  96.      * specific character glyphs in that font. 
  97.      * @param     font the font
  98.      * @see       java.awt.Font
  99.      */
  100.     protected FontMetrics(Font font) {
  101.     this.font = font;
  102.     }
  103.  
  104.     /**
  105.      * Gets the font described by this font metric.
  106.      * @return    the font described by this font metric.
  107.      */
  108.     public Font getFont() {
  109.     return font;
  110.     }
  111.  
  112.     /**
  113.      * Determines the <em>standard leading</em> of the font described by 
  114.      * this font metric. The standard leading (interline spacing) is the 
  115.      * logical amount of space to be reserved between the descent of one 
  116.      * line of text and the ascent of the next line. The height metric is 
  117.      * calculated to include this extra space. 
  118.      * @return    the standard leading of the font.
  119.      * @see       java.awt.FontMetrics#getHeight
  120.      * @see       java.awt.FontMetrics#getAscent
  121.      * @see       java.awt.FontMetrics#getDescent
  122.      */
  123.     public int getLeading() {
  124.     return 0;
  125.     }
  126.  
  127.     /**
  128.      * Determines the <em>font ascent</em> of the font described by this 
  129.      * font metric. The font ascent is the distance from the font's 
  130.      * baseline to the top of most alphanumeric characters. Some 
  131.      * characters in the font may extend above the font ascent line. 
  132.      * @return     the font ascent of the font.
  133.      * @see        java.awt.FontMetrics#getMaxAscent
  134.      */
  135.     public int getAscent() {
  136.     return font.getSize();
  137.     }
  138.  
  139.     /**
  140.      * Determines the <em>font descent</em> of the font described by this 
  141.      * font metric. The font descent is the distance from the font's 
  142.      * baseline to the bottom of most alphanumeric characters with 
  143.      * descenders. Some characters in the font may extend below the font 
  144.      * descent line. 
  145.      * @return     the font descent of the font.
  146.      * @see        java.awt.FontMetrics#getMaxDescent
  147.      */
  148.     public int getDescent() {
  149.     return 0;
  150.     }
  151.  
  152.     /**
  153.      * Gets the standard height of a line of text in this font.  This
  154.      * is the distance between the baseline of adjacent lines of text.
  155.      * It is the sum of the leading + ascent + descent.  There is no
  156.      * guarantee that lines of text spaced at this distance will be
  157.      * disjoint; such lines may overlap if some characters overshoot
  158.      * either the standard ascent or the standard descent metric.
  159.      * @return    the standard height of the font.
  160.      * @see       java.awt.FontMetrics#getLeading
  161.      * @see       java.awt.FontMetrics#getAscent
  162.      * @see       java.awt.FontMetrics#getDescent
  163.      */
  164.     public int getHeight() {
  165.     return getLeading() + getAscent() + getDescent();
  166.     }
  167.  
  168.     /**
  169.      * Determines the maximum ascent of the font described by this font 
  170.      * metric. No character extends further above the font's baseline 
  171.      * than this height. 
  172.      * @return    the maximum ascent of any character in the font.
  173.      * @see       java.awt.FontMetrics#getAscent
  174.      */
  175.     public int getMaxAscent() {
  176.     return getAscent();
  177.     }
  178.  
  179.     /**
  180.      * Determines the maximum descent of the font described by this font 
  181.      * metric. No character extends further below the font's baseline 
  182.      * than this height. 
  183.      * @return    the maximum descent of any character in the font.
  184.      * @see       java.awt.FontMetrics#getDescent
  185.      */
  186.     public int getMaxDescent() {
  187.     return getDescent();
  188.     }
  189.  
  190.     /**
  191.      * For backward compatibility only.
  192.      * @see #getMaxDescent
  193.      * @deprecated As of JDK version 1.1.1,
  194.      * replaced by <code>getMaxDescent()</code>.
  195.      */
  196.     public int getMaxDecent() {
  197.     return getMaxDescent();
  198.     }
  199.  
  200.     /**
  201.      * Gets the maximum advance width of any character in this Font. 
  202.      * The advance width is the amount by which the current point is
  203.      * moved from one character to the next in a line of text.
  204.      * @return    the maximum advance width of any character 
  205.      *            in the font, or <code>-1</code> if the 
  206.      *            maximum advance width is not known.
  207.      */
  208.     public int getMaxAdvance() {
  209.     return -1;
  210.     }
  211.  
  212.     /** 
  213.      * Returns the advance width of the specified character in this Font.
  214.      * The advance width is the amount by which the current point is
  215.      * moved from one character to the next in a line of text.
  216.      * @param ch the character to be measured
  217.      * @return    the advance width of the specified <code>char</code> 
  218.      *                 in the font described by this font metric.
  219.      * @see       java.awt.FontMetrics#charsWidth
  220.      * @see       java.awt.FontMetrics#stringWidth
  221.      */
  222.     public int charWidth(int ch) {
  223.     return charWidth((char)ch);
  224.     }
  225.  
  226.     /** 
  227.      * Returns the advance width of the specified character in this Font.
  228.      * The advance width is the amount by which the current point is
  229.      * moved from one character to the next in a line of text.
  230.      * @param ch the character to be measured
  231.      * @return     the advance width of the specified <code>char</code> >
  232.      *                  in the font described by this font metric.
  233.      * @see        java.awt.FontMetrics#charsWidth
  234.      * @see        java.awt.FontMetrics#stringWidth
  235.      */
  236.     public int charWidth(char ch) {
  237.     if (ch < 256) {
  238.         return getWidths()[ch];
  239.     }
  240.     char data[] = {ch};
  241.     return charsWidth(data, 0, 1);
  242.     }
  243.  
  244.     /** 
  245.      * Returns the total advance width for showing the specified String
  246.      * in this Font.
  247.      * The advance width is the amount by which the current point is
  248.      * moved from one character to the next in a line of text.
  249.      * @param str the String to be measured
  250.      * @return    the advance width of the specified string 
  251.      *                  in the font described by this font metric.
  252.      * @see       java.awt.FontMetrics#bytesWidth
  253.      * @see       java.awt.FontMetrics#charsWidth
  254.      */
  255.     public int stringWidth(String str) {
  256.     int len = str.length();
  257.     char data[] = new char[len];
  258.     str.getChars(0, len, data, 0);
  259.     return charsWidth(data, 0, len);
  260.     }
  261.  
  262.     /** 
  263.      * Returns the total advance width for showing the specified array
  264.      * of characters in this Font.
  265.      * The advance width is the amount by which the current point is
  266.      * moved from one character to the next in a line of text.
  267.      * @param data the array of characters to be measured
  268.      * @param off the start offset of the characters in the array
  269.      * @param len the number of characters to be measured from the array
  270.      * @return    the advance width of the subarray of the specified 
  271.      *               <code>char</code> array in the font described by 
  272.      *               this font metric.
  273.      * @see       java.awt.FontMetrics#charWidth(int)
  274.      * @see       java.awt.FontMetrics#charWidth(char)
  275.      * @see       java.awt.FontMetrics#bytesWidth
  276.      * @see       java.awt.FontMetrics#stringWidth
  277.      */
  278.     public int charsWidth(char data[], int off, int len) {
  279.     return stringWidth(new String(data, off, len));
  280.     }
  281.  
  282.     /** 
  283.      * Returns the total advance width for showing the specified array
  284.      * of bytes in this Font.
  285.      * The advance width is the amount by which the current point is
  286.      * moved from one character to the next in a line of text.
  287.      * @param data the array of bytes to be measured
  288.      * @param off the start offset of the bytes in the array
  289.      * @param len the number of bytes to be measured from the array
  290.      * @return    the advance width of the subarray of the specified 
  291.      *               <code>byte</code> array in the font described by 
  292.      *               this font metric.
  293.      * @see       java.awt.FontMetrics#charsWidth
  294.      * @see       java.awt.FontMetrics#stringWidth
  295.      */
  296.     public int bytesWidth(byte data[], int off, int len) {
  297.     return stringWidth(new String(data, 0, off, len));
  298.     }
  299.  
  300.     /**
  301.      * Gets the advance widths of the first 256 characters in the Font.
  302.      * The advance width is the amount by which the current point is
  303.      * moved from one character to the next in a line of text.
  304.      * @return    an array giving the advance widths of the 
  305.      *                 characters in the font 
  306.      *                 described by this font metric.
  307.      */
  308.     public int[] getWidths() {
  309.     int widths[] = new int[256];
  310.     for (char ch = 0 ; ch < 256 ; ch++) {
  311.         widths[ch] = charWidth(ch);
  312.     }
  313.     return widths;
  314.     }
  315.  
  316.     /** 
  317.      * Returns a representation of this <code>FontMetric</code> 
  318.      * object's values as a string.
  319.      * @return    a string representation of this font metric.
  320.      * @since     JDK1.0.
  321.      */
  322.     public String toString() {
  323.     return getClass().getName() + 
  324.         "[font=" + getFont() + 
  325.         "ascent=" + getAscent() + 
  326.         ", descent=" + getDescent() + 
  327.         ", height=" + getHeight() + "]";
  328.     }
  329.  
  330.     /**
  331.      * Initialize JNI field and method IDs
  332.      */
  333.     private static native void initIDs();
  334. }
  335.