/* * Copyright (c) 1995, 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code 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. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code 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 in the LICENSE file that * accompanied this code). * * 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; import java.awt.Graphics2D; import java.awt.font.FontRenderContext; import java.awt.font.LineMetrics; import java.awt.geom.Rectangle2D; import java.text.CharacterIterator; /** * The FontMetrics class defines a font metrics object, which * encapsulates information about the rendering of a particular font on a * particular screen. *

* Note to subclassers: 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 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): *

*

* The letter 'p' showing its 'reference point' * Note that the implementations of these methods are * inefficient, so they are usually overridden with more efficient * toolkit-specific implementations. *

* When an application asks to place a character at the position * (xy), 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 baseline of the character. In normal * printing, the baselines of characters should align. *

* In addition, every character in a font has an ascent, a * descent, and an advance width. 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. *

* 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 * character array. The advance of a String is the * distance along the baseline of the String. This * distance is the width that should be used for centering or * right-aligning the String. *

Note that the advance of a String is not necessarily * the sum of the advances of its characters measured in isolation * because the width of a character can vary depending on its context. * For example, in Arabic text, the shape of a character can change * in order to connect to other characters. Also, in some scripts, * certain character sequences can be represented by a single shape, * called a ligature. Measuring characters individually does * not account for these transformations. *

Font metrics are baseline-relative, meaning that they are * generally independent of the rotation applied to the font (modulo * possible grid hinting effects). See {@link java.awt.Font Font}. * * @author Jim Graham * @see java.awt.Font * @since JDK1.0 */ public abstract class FontMetrics implements java.io.Serializable { static { /* ensure that the necessary native libraries are loaded */ Toolkit.loadLibraries(); if (!GraphicsEnvironment.isHeadless()) { initIDs(); } } private static final FontRenderContext DEFAULT_FRC = new FontRenderContext(null, false, false); /** * The actual {@link Font} from which the font metrics are * created. * This cannot be null. * * @serial * @see #getFont() */ protected Font font; /* * JDK 1.1 serialVersionUID */ private static final long serialVersionUID = 1681126225205050147L; /** * Creates a new FontMetrics 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 */ protected FontMetrics(Font font) { this.font = font; } /** * Gets the Font described by this * FontMetrics object. * @return the Font described by this * FontMetrics object. */ public Font getFont() { return font; } /** * Gets the FontRenderContext used by this * FontMetrics object to measure text. *

* Note that methods in this class which take a Graphics * parameter measure text using the FontRenderContext * of that Graphics object, and not this * FontRenderContext * @return the FontRenderContext used by this * FontMetrics object. * @since 1.6 */ public FontRenderContext getFontRenderContext() { return DEFAULT_FRC; } /** * Determines the standard leading of the * Font described by this FontMetrics * object. The standard leading, or * 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 #getHeight() * @see #getAscent() * @see #getDescent() */ public int getLeading() { return 0; } /** * Determines the font ascent of the Font * described by this FontMetrics object. The font ascent * is the distance from the font's baseline to the top of most * alphanumeric characters. Some characters in the Font * might extend above the font ascent line. * @return the font ascent of the Font. * @see #getMaxAscent() */ public int getAscent() { return font.getSize(); } /** * Determines the font descent of the Font * described by this * FontMetrics object. 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 might extend * below the font descent line. * @return the font descent of the Font. * @see #getMaxDescent() */ 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. Due to rounding * this may not be the same as getAscent() + getDescent() + getLeading(). * There is no guarantee that lines of text spaced at this distance are * 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 #getLeading() * @see #getAscent() * @see #getDescent() */ public int getHeight() { return getLeading() + getAscent() + getDescent(); } /** * Determines the maximum ascent of the Font * described by this FontMetrics object. No character * extends further above the font's baseline than this height. * @return the maximum ascent of any character in the * Font. * @see #getAscent() */ public int getMaxAscent() { return getAscent(); } /** * Determines the maximum descent of the Font * described by this FontMetrics object. No character * extends further below the font's baseline than this height. * @return the maximum descent of any character in the * Font. * @see #getDescent() */ public int getMaxDescent() { return getDescent(); } /** * For backward compatibility only. * @return the maximum descent of any character in the * Font. * @see #getMaxDescent() * @deprecated As of JDK version 1.1.1, * replaced by getMaxDescent(). */ @Deprecated public int getMaxDecent() { return getMaxDescent(); } /** * Gets the maximum advance width of any character in this * Font. The advance is the * distance from the leftmost point to the rightmost point on the * string's baseline. The advance of a String is * not necessarily the sum of the advances of its characters. * @return the maximum advance width of any character * in the Font, or -1 if the * maximum advance width is not known. */ public int getMaxAdvance() { return -1; } /** * Returns the advance width of the specified character in this * Font. The advance is the * distance from the leftmost point to the rightmost point on the * character's baseline. Note that the advance of a * String is not necessarily the sum of the advances * of its characters. * *

This method doesn't validate the specified character to be a * valid Unicode code point. The caller must validate the * character value using {@link * java.lang.Character#isValidCodePoint(int) * Character.isValidCodePoint} if necessary. * * @param codePoint the character (Unicode code point) to be measured * @return the advance width of the specified character * in the Font described by this * FontMetrics object. * @see #charsWidth(char[], int, int) * @see #stringWidth(String) */ public int charWidth(int codePoint) { if (!Character.isValidCodePoint(codePoint)) { codePoint = 0xffff; // substitute missing glyph width } if (codePoint < 256) { return getWidths()[codePoint]; } else { char[] buffer = new char[2]; int len = Character.toChars(codePoint, buffer, 0); return charsWidth(buffer, 0, len); } } /** * Returns the advance width of the specified character in this * Font. The advance is the * distance from the leftmost point to the rightmost point on the * character's baseline. Note that the advance of a * String is not necessarily the sum of the advances * of its characters. * *

Note: This method cannot handle supplementary * characters. To support all Unicode characters, including * supplementary characters, use the {@link #charWidth(int)} method. * * @param ch the character to be measured * @return the advance width of the specified character * in the Font described by this * FontMetrics object. * @see #charsWidth(char[], int, int) * @see #stringWidth(String) */ public int charWidth(char ch) { if (ch < 256) { return getWidths()[ch]; } char data[] = {ch}; return charsWidth(data, 0, 1); } /** * Returns the total advance width for showing the specified * String in this Font. The advance * is the distance from the leftmost point to the rightmost point * on the string's baseline. *

* Note that the advance of a String is * not necessarily the sum of the advances of its characters. * @param str the String to be measured * @return the advance width of the specified String * in the Font described by this * FontMetrics. * @throws NullPointerException if str is null. * @see #bytesWidth(byte[], int, int) * @see #charsWidth(char[], int, int) * @see #getStringBounds(String, Graphics) */ 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 is the * distance from the leftmost point to the rightmost point on the * string's baseline. The advance of a String * is not necessarily the sum of the advances of its characters. * This is equivalent to measuring a String of the * characters in the specified range. * @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 * char array in the font described by * this FontMetrics object. * @throws NullPointerException if data is null. * @throws IndexOutOfBoundsException if the off * and len arguments index characters outside * the bounds of the data array. * @see #charWidth(int) * @see #charWidth(char) * @see #bytesWidth(byte[], int, int) * @see #stringWidth(String) */ 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 is the * distance from the leftmost point to the rightmost point on the * string's baseline. The advance of a String * is not necessarily the sum of the advances of its characters. * This is equivalent to measuring a String of the * characters in the specified range. * @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 * byte array in the Font * described by * this FontMetrics object. * @throws NullPointerException if data is null. * @throws IndexOutOfBoundsException if the off * and len arguments index bytes outside * the bounds of the data array. * @see #charsWidth(char[], int, int) * @see #stringWidth(String) */ public int bytesWidth(byte data[], int off, int len) { return stringWidth(new String(data, 0, off, len)); } /** * Gets the advance widths of the first 256 characters in the * Font. The advance is the * distance from the leftmost point to the rightmost point on the * character's baseline. Note that the advance of a * String is not necessarily the sum of the advances * of its characters. * @return an array storing the advance widths of the * characters in the Font * described by this FontMetrics object. */ public int[] getWidths() { int widths[] = new int[256]; for (char ch = 0 ; ch < 256 ; ch++) { widths[ch] = charWidth(ch); } return widths; } /** * Checks to see if the Font has uniform line metrics. A * composite font may consist of several different fonts to cover * various character sets. In such cases, the * FontLineMetrics objects are not uniform. * Different fonts may have a different ascent, descent, metrics and * so on. This information is sometimes necessary for line * measuring and line breaking. * @return true if the font has uniform line metrics; * false otherwise. * @see java.awt.Font#hasUniformLineMetrics() */ public boolean hasUniformLineMetrics() { return font.hasUniformLineMetrics(); } /** * Returns the {@link LineMetrics} object for the specified * String in the specified {@link Graphics} context. * @param str the specified String * @param context the specified Graphics context * @return a LineMetrics object created with the * specified String and Graphics context. * @see java.awt.Font#getLineMetrics(String, FontRenderContext) */ public LineMetrics getLineMetrics( String str, Graphics context) { return font.getLineMetrics(str, myFRC(context)); } /** * Returns the {@link LineMetrics} object for the specified * String in the specified {@link Graphics} context. * @param str the specified String * @param beginIndex the initial offset of str * @param limit the end offset of str * @param context the specified Graphics context * @return a LineMetrics object created with the * specified String and Graphics context. * @see java.awt.Font#getLineMetrics(String, int, int, FontRenderContext) */ public LineMetrics getLineMetrics( String str, int beginIndex, int limit, Graphics context) { return font.getLineMetrics(str, beginIndex, limit, myFRC(context)); } /** * Returns the {@link LineMetrics} object for the specified * character array in the specified {@link Graphics} context. * @param chars the specified character array * @param beginIndex the initial offset of chars * @param limit the end offset of chars * @param context the specified Graphics context * @return a LineMetrics object created with the * specified character array and Graphics context. * @see java.awt.Font#getLineMetrics(char[], int, int, FontRenderContext) */ public LineMetrics getLineMetrics(char [] chars, int beginIndex, int limit, Graphics context) { return font.getLineMetrics( chars, beginIndex, limit, myFRC(context)); } /** * Returns the {@link LineMetrics} object for the specified * {@link CharacterIterator} in the specified {@link Graphics} * context. * @param ci the specified CharacterIterator * @param beginIndex the initial offset in ci * @param limit the end index of ci * @param context the specified Graphics context * @return a LineMetrics object created with the * specified arguments. * @see java.awt.Font#getLineMetrics(CharacterIterator, int, int, FontRenderContext) */ public LineMetrics getLineMetrics(CharacterIterator ci, int beginIndex, int limit, Graphics context) { return font.getLineMetrics(ci, beginIndex, limit, myFRC(context)); } /** * Returns the bounds of the specified String in the * specified Graphics context. The bounds is used * to layout the String. *

Note: The returned bounds is in baseline-relative coordinates * (see {@link java.awt.FontMetrics class notes}). * @param str the specified String * @param context the specified Graphics context * @return a {@link Rectangle2D} that is the bounding box of the * specified String in the specified * Graphics context. * @see java.awt.Font#getStringBounds(String, FontRenderContext) */ public Rectangle2D getStringBounds( String str, Graphics context) { return font.getStringBounds(str, myFRC(context)); } /** * Returns the bounds of the specified String in the * specified Graphics context. The bounds is used * to layout the String. *

Note: The returned bounds is in baseline-relative coordinates * (see {@link java.awt.FontMetrics class notes}). * @param str the specified String * @param beginIndex the offset of the beginning of str * @param limit the end offset of str * @param context the specified Graphics context * @return a Rectangle2D that is the bounding box of the * specified String in the specified * Graphics context. * @see java.awt.Font#getStringBounds(String, int, int, FontRenderContext) */ public Rectangle2D getStringBounds( String str, int beginIndex, int limit, Graphics context) { return font.getStringBounds(str, beginIndex, limit, myFRC(context)); } /** * Returns the bounds of the specified array of characters * in the specified Graphics context. * The bounds is used to layout the String * created with the specified array of characters, * beginIndex and limit. *

Note: The returned bounds is in baseline-relative coordinates * (see {@link java.awt.FontMetrics class notes}). * @param chars an array of characters * @param beginIndex the initial offset of the array of * characters * @param limit the end offset of the array of characters * @param context the specified Graphics context * @return a Rectangle2D that is the bounding box of the * specified character array in the specified * Graphics context. * @see java.awt.Font#getStringBounds(char[], int, int, FontRenderContext) */ public Rectangle2D getStringBounds( char [] chars, int beginIndex, int limit, Graphics context) { return font.getStringBounds(chars, beginIndex, limit, myFRC(context)); } /** * Returns the bounds of the characters indexed in the specified * CharacterIterator in the * specified Graphics context. *

Note: The returned bounds is in baseline-relative coordinates * (see {@link java.awt.FontMetrics class notes}). * @param ci the specified CharacterIterator * @param beginIndex the initial offset in ci * @param limit the end index of ci * @param context the specified Graphics context * @return a Rectangle2D that is the bounding box of the * characters indexed in the specified CharacterIterator * in the specified Graphics context. * @see java.awt.Font#getStringBounds(CharacterIterator, int, int, FontRenderContext) */ public Rectangle2D getStringBounds(CharacterIterator ci, int beginIndex, int limit, Graphics context) { return font.getStringBounds(ci, beginIndex, limit, myFRC(context)); } /** * Returns the bounds for the character with the maximum bounds * in the specified Graphics context. * @param context the specified Graphics context * @return a Rectangle2D that is the * bounding box for the character with the maximum bounds. * @see java.awt.Font#getMaxCharBounds(FontRenderContext) */ public Rectangle2D getMaxCharBounds(Graphics context) { return font.getMaxCharBounds(myFRC(context)); } private FontRenderContext myFRC(Graphics context) { if (context instanceof Graphics2D) { return ((Graphics2D)context).getFontRenderContext(); } return DEFAULT_FRC; } /** * Returns a representation of this FontMetrics * object's values as a String. * @return a String representation of this * FontMetrics object. * @since JDK1.0. */ public String toString() { return getClass().getName() + "[font=" + getFont() + "ascent=" + getAscent() + ", descent=" + getDescent() + ", height=" + getHeight() + "]"; } /** * Initialize JNI field and method IDs */ private static native void initIDs(); }