fontmetrics.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 336 行

/*
 * @(#)FontMetrics.java	1.31 06/10/10
 *
 * Copyright  1990-2008 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation. 
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt). 
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA 
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions. 
 *
 */

package java.awt;

/**
 * A font metrics object, which gives information about the rendering
 * of a particular font on a particular screen. Note that the
 * implementations of these methods are inefficient, they are usually
 * overridden with more efficient toolkit-specific implementations.
 * <p>
 * <b>Note to subclassers</b>: Since many of these methods form closed
 * mutually recursive loops, you must take care that you implement
 * at least one of the methods in each such loop in order to prevent
 * infinite recursion when your subclass is used.
 * In particular, the following is the minimal suggested set of methods
 * to override in order to ensure correctness and prevent infinite
 * recursion (though other subsets are equally feasible):
 * <ul>
 * <li><a href=#getAscent>getAscent</a>()
 * <li><a href=#getDescent>getDescent</a>()
 * <li><a href=#getLeading>getLeading</a>()
 * <li><a href=#getMaxAdvance>getMaxAdvance</a>()
 * <li><a href="#charWidth(char)">charWidth</a>(char ch)
 * <li><a href="#charsWidth(char[], int, int)">charsWidth</a>(char data[], int off, int len)
 * </ul>
 * <p>
 * <img src="images-awt/FontMetrics-1.gif" border=15 align
 * ALIGN=right HSPACE=10 VSPACE=7>
 * When an application asks AWT to place a character at the position
 * (<i>x</i>,&nbsp;<i>y</i>), the character is placed so that its
 * reference point (shown as the dot in the accompanying image) is
 * put at that position. The reference point specifies a horizontal
 * line called the <i>baseline</i> of the character. In normal
 * printing, the baselines of characters should align.
 * <p>
 * In addition, every character in a font has an <i>ascent</i>, a
 * <i>descent</i>, and an <i>advance width</i>. The ascent is the
 * amount by which the character ascends above the baseline. The
 * descent is the amount by which the character descends below the
 * baseline. The advance width indicates the position at which AWT
 * should place the next character.
 * <p>
 * If the current character is placed with its reference point
 * at the position (<i>x</i>,&nbsp;<i>y</i>), and
 * the character's advance width is <i>w</i>, then the following
 * character is placed with its reference point at the position
 * (<i>x&nbsp;</i><code>+</code><i>&nbsp;w</i>,&nbsp;<i>y</i>).
 * The advance width is often the same as the width of character's
 * bounding box, but need not be so. In particular, oblique and
 * italic fonts often have characters whose top-right corner extends
 * slightly beyond the advance width.
 * <p>
 * An array of characters or a string can also have an ascent, a
 * descent, and an advance width. The ascent of the array is the
 * maximum ascent of any character in the array. The descent is the
 * maximum descent of any character in the array. The advance width
 * is the sum of the advance widths of each of the characters in the
 * array.
 * @version 	1.19 01/05/01
 * @author 	Jim Graham
 * @see         java.awt.Font
 * @since       JDK1.0
 */
public abstract class FontMetrics implements java.io.Serializable {
    /**
     * The actual font.
     * @see #getFont
     * @since JDK1.0
     */
    protected Font font;
    /*
     * JDK 1.1 serialVersionUID
     */
    private static final long serialVersionUID = 1681126225205050147L;
    /**
     * Creates a new <code>FontMetrics</code> object for finding out
     * height and width information about the specified font and
     * specific character glyphs in that font.
     * @param     font the font
     * @see       java.awt.Font
     * @since     JDK1.0
     */
    protected FontMetrics(Font font) {
        this.font = font;
    }

    /**
     * Gets the font described by this font metric.
     * @return    the font described by this font metric.
     * @since     JDK1.0
     */
    public Font getFont() {
        return font;
    }

    /**
     * Determines the <em>standard leading</em> of the font described by
     * this font metric. The standard leading (interline spacing) is the
     * logical amount of space to be reserved between the descent of one
     * line of text and the ascent of the next line. The height metric is
     * calculated to include this extra space.
     * @return    the standard leading of the font.
     * @see       java.awt.FontMetrics#getHeight
     * @see       java.awt.FontMetrics#getAscent
     * @see       java.awt.FontMetrics#getDescent
     * @since     JDK1.0
     */
    public int getLeading() {
        return 0;
    }

    /**
     * Determines the <em>font ascent</em> of the font described by this
     * font metric. The font ascent is the distance from the font's
     * baseline to the top of most alphanumeric characters. Some
     * characters in the font may extend above the font ascent line.
     * @return     the font ascent of the font.
     * @see        java.awt.FontMetrics#getMaxAscent
     * @since      JDK1.0
     */
    public int getAscent() {
        return font.getSize();
    }

    /**
     * Determines the <em>font descent</em> of the font described by this
     * font metric. The font descent is the distance from the font's
     * baseline to the bottom of most alphanumeric characters with
     * descenders. Some characters in the font may extend below the font
     * descent line.
     * @return     the font descent of the font.
     * @see        java.awt.FontMetrics#getMaxDescent
     * @since      JDK1.0
     */
    public int getDescent() {
        return 0;
    }

    /**
     * Gets the standard height of a line of text in this font.  This
     * is the distance between the baseline of adjacent lines of text.
     * It is the sum of the leading + ascent + descent.  There is no
     * guarantee that lines of text spaced at this distance will be
     * disjoint; such lines may overlap if some characters overshoot
     * either the standard ascent or the standard descent metric.
     * @return    the standard height of the font.
     * @see       java.awt.FontMetrics#getLeading
     * @see       java.awt.FontMetrics#getAscent
     * @see       java.awt.FontMetrics#getDescent
     * @since     JDK1.0
     */
    public int getHeight() {
        return getLeading() + getAscent() + getDescent();
    }

    /**
     * Determines the maximum ascent of the font described by this font
     * metric. No character extends further above the font's baseline
     * than this height.
     * @return    the maximum ascent of any character in the font.
     * @see       java.awt.FontMetrics#getAscent
     * @since     JDK1.0
     */
    public int getMaxAscent() {
        return getAscent();
    }

    /**
     * Determines the maximum descent of the font described by this font
     * metric. No character extends further below the font's baseline
     * than this height.
     * @return    the maximum descent of any character in the font.
     * @see       java.awt.FontMetrics#getDescent
     * @since     JDK1.0
     */
    public int getMaxDescent() {
        return getDescent();
    }

    /**
     * Gets the maximum advance width of any character in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @return    the maximum advance width of any character
     *            in the font, or <code>-1</code> if the
     *            maximum advance width is not known.
     * @since     JDK1.0
     */
    public int getMaxAdvance() {
        return -1;
    }

    /**
     * Returns the advance width of the specified character in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @param ch the character to be measured
     * @return    the advance width of the specified <code>char</code>
     *                 in the font described by this font metric.
     * @see       java.awt.FontMetrics#charsWidth
     * @see       java.awt.FontMetrics#stringWidth
     * @since     JDK1.0
     */
    public int charWidth(int ch) {
        return charWidth((char) ch);
    }

    /**
     * Returns the advance width of the specified character in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @param ch the character to be measured
     * @return     the advance width of the specified <code>char</code> >
     *                  in the font described by this font metric.
     * @see        java.awt.FontMetrics#charsWidth
     * @see        java.awt.FontMetrics#stringWidth
     * @since      JDK1.0
     */
    public int charWidth(char ch) {
        char data[] = {ch};
        return charsWidth(data, 0, 1);
    }

    /**
     * Returns the total advance width for showing the specified String
     * in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @param str the String to be measured
     * @return    the advance width of the specified string
     *                  in the font described by this font metric.
     * @see       java.awt.FontMetrics#bytesWidth
     * @see       java.awt.FontMetrics#charsWidth
     * @since     JDK1.0
     */
    public int stringWidth(String str) {
        int len = str.length();
        char data[] = new char[len];
        str.getChars(0, len, data, 0);
        return charsWidth(data, 0, len);
    }

    /**
     * Returns the total advance width for showing the specified array
     * of characters in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @param data the array of characters to be measured
     * @param off the start offset of the characters in the array
     * @param len the number of characters to be measured from the array
     * @return    the advance width of the subarray of the specified
     *               <code>char</code> array in the font described by
     *               this font metric.
     * @see       java.awt.FontMetrics#charWidth(int)
     * @see       java.awt.FontMetrics#charWidth(char)
     * @see       java.awt.FontMetrics#bytesWidth
     * @see       java.awt.FontMetrics#stringWidth
     * @since     JDK1.0
     */
    public int charsWidth(char data[], int off, int len) {
        return stringWidth(new String(data, off, len));
    }

    /**
     * Returns the total advance width for showing the specified array
     * of bytes in this Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @param data the array of bytes to be measured
     * @param off the start offset of the bytes in the array
     * @param len the number of bytes to be measured from the array
     * @return    the advance width of the subarray of the specified
     *               <code>byte</code> array in the font described by
     *               this font metric.
     * @see       java.awt.FontMetrics#charsWidth
     * @see       java.awt.FontMetrics#stringWidth
     * @since     JDK1.0
     */
    public int bytesWidth(byte data[], int off, int len) {
        return stringWidth(new String(data, off, len));
    }

    /**
     * Gets the advance widths of the first 256 characters in the Font.
     * The advance width is the amount by which the current point is
     * moved from one character to the next in a line of text.
     * @return    an array giving the advance widths of the
     *                 characters in the font
     *                 described by this font metric.
     * @since     JDK1.0
     */
    public int[] getWidths() {
        int widths[] = new int[256];
        for (char ch = 0; ch < 256; ch++) {
            widths[ch] = charWidth(ch);
        }
        return widths;
    }

    /**
     * Returns a representation of this <code>FontMetric</code>
     * object's values as a string.
     * @return    a string representation of this font metric.
     * @since     JDK1.0.
     */
    public String toString() {
        return getClass().getName() + "[font=" + getFont() + "ascent=" +
            getAscent() + ", descent=" + getDescent() + ", height=" + getHeight() + "]";
    }
}