| /* |
| * 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 <code>FontMetrics</code> class defines a font metrics object, which |
| * encapsulates information about the rendering of a particular font on a |
| * particular screen. |
| * <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 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>{@link #getAscent()} |
| * <li>{@link #getLeading()} |
| * <li>{@link #getMaxAdvance()} |
| * <li>{@link #charWidth(char)} |
| * <li>{@link #charsWidth(char[], int, int)} |
| * </ul> |
| * <p> |
| * <img src="doc-files/FontMetrics-1.gif" alt="The letter 'p' showing its 'reference point'" border=15 align |
| * ALIGN=right HSPACE=10 VSPACE=7> |
| * Note that the implementations of these methods are |
| * inefficient, so they are usually overridden with more efficient |
| * toolkit-specific implementations. |
| * <p> |
| * When an application asks to place a character at the position |
| * (<i>x</i>, <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> |
| * 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 <code>String</code> is the |
| * distance along the baseline of the <code>String</code>. This |
| * distance is the width that should be used for centering or |
| * right-aligning the <code>String</code>. |
| * <p>Note that the advance of a <code>String</code> 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 <em>ligature</em>. Measuring characters individually does |
| * not account for these transformations. |
| * <p>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 <code>FontMetrics</code> object for finding out |
| * height and width information about the specified <code>Font</code> |
| * and specific character glyphs in that <code>Font</code>. |
| * @param font the <code>Font</code> |
| * @see java.awt.Font |
| */ |
| protected FontMetrics(Font font) { |
| this.font = font; |
| } |
| |
| /** |
| * Gets the <code>Font</code> described by this |
| * <code>FontMetrics</code> object. |
| * @return the <code>Font</code> described by this |
| * <code>FontMetrics</code> object. |
| */ |
| public Font getFont() { |
| return font; |
| } |
| |
| /** |
| * Gets the <code>FontRenderContext</code> used by this |
| * <code>FontMetrics</code> object to measure text. |
| * <p> |
| * Note that methods in this class which take a <code>Graphics</code> |
| * parameter measure text using the <code>FontRenderContext</code> |
| * of that <code>Graphics</code> object, and not this |
| * <code>FontRenderContext</code> |
| * @return the <code>FontRenderContext</code> used by this |
| * <code>FontMetrics</code> object. |
| * @since 1.6 |
| */ |
| public FontRenderContext getFontRenderContext() { |
| return DEFAULT_FRC; |
| } |
| |
| /** |
| * Determines the <em>standard leading</em> of the |
| * <code>Font</code> described by this <code>FontMetrics</code> |
| * 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 <code>Font</code>. |
| * @see #getHeight() |
| * @see #getAscent() |
| * @see #getDescent() |
| */ |
| public int getLeading() { |
| return 0; |
| } |
| |
| /** |
| * Determines the <em>font ascent</em> of the <code>Font</code> |
| * described by this <code>FontMetrics</code> object. The font ascent |
| * is the distance from the font's baseline to the top of most |
| * alphanumeric characters. Some characters in the <code>Font</code> |
| * might extend above the font ascent line. |
| * @return the font ascent of the <code>Font</code>. |
| * @see #getMaxAscent() |
| */ |
| public int getAscent() { |
| return font.getSize(); |
| } |
| |
| /** |
| * Determines the <em>font descent</em> of the <code>Font</code> |
| * described by this |
| * <code>FontMetrics</code> 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 |
| * <code>Font</code> might extend |
| * below the font descent line. |
| * @return the font descent of the <code>Font</code>. |
| * @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 <code>Font</code> |
| * described by this <code>FontMetrics</code> object. No character |
| * extends further above the font's baseline than this height. |
| * @return the maximum ascent of any character in the |
| * <code>Font</code>. |
| * @see #getAscent() |
| */ |
| public int getMaxAscent() { |
| return getAscent(); |
| } |
| |
| /** |
| * Determines the maximum descent of the <code>Font</code> |
| * described by this <code>FontMetrics</code> object. No character |
| * extends further below the font's baseline than this height. |
| * @return the maximum descent of any character in the |
| * <code>Font</code>. |
| * @see #getDescent() |
| */ |
| public int getMaxDescent() { |
| return getDescent(); |
| } |
| |
| /** |
| * For backward compatibility only. |
| * @return the maximum descent of any character in the |
| * <code>Font</code>. |
| * @see #getMaxDescent() |
| * @deprecated As of JDK version 1.1.1, |
| * replaced by <code>getMaxDescent()</code>. |
| */ |
| @Deprecated |
| public int getMaxDecent() { |
| return getMaxDescent(); |
| } |
| |
| /** |
| * Gets the maximum advance width of any character in this |
| * <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * string's baseline. The advance of a <code>String</code> is |
| * not necessarily the sum of the advances of its characters. |
| * @return the maximum advance width of any character |
| * in the <code>Font</code>, or <code>-1</code> if the |
| * maximum advance width is not known. |
| */ |
| public int getMaxAdvance() { |
| return -1; |
| } |
| |
| /** |
| * Returns the advance width of the specified character in this |
| * <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * character's baseline. Note that the advance of a |
| * <code>String</code> is not necessarily the sum of the advances |
| * of its characters. |
| * |
| * <p>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 <code>Font</code> described by this |
| * <code>FontMetrics</code> 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 |
| * <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * character's baseline. Note that the advance of a |
| * <code>String</code> is not necessarily the sum of the advances |
| * of its characters. |
| * |
| * <p><b>Note:</b> This method cannot handle <a |
| * href="../lang/Character.html#supplementary"> supplementary |
| * characters</a>. 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 <code>Font</code> described by this |
| * <code>FontMetrics</code> 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 |
| * <code>String</code> in this <code>Font</code>. The advance |
| * is the distance from the leftmost point to the rightmost point |
| * on the string's baseline. |
| * <p> |
| * Note that the advance of a <code>String</code> is |
| * not necessarily the sum of the advances of its characters. |
| * @param str the <code>String</code> to be measured |
| * @return the advance width of the specified <code>String</code> |
| * in the <code>Font</code> described by this |
| * <code>FontMetrics</code>. |
| * @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 <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * string's baseline. The advance of a <code>String</code> |
| * is not necessarily the sum of the advances of its characters. |
| * This is equivalent to measuring a <code>String</code> 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 |
| * <code>char</code> array in the font described by |
| * this <code>FontMetrics</code> object. |
| * @throws NullPointerException if <code>data</code> is null. |
| * @throws IndexOutOfBoundsException if the <code>off</code> |
| * and <code>len</code> arguments index characters outside |
| * the bounds of the <code>data</code> 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 <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * string's baseline. The advance of a <code>String</code> |
| * is not necessarily the sum of the advances of its characters. |
| * This is equivalent to measuring a <code>String</code> 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 |
| * <code>byte</code> array in the <code>Font</code> |
| * described by |
| * this <code>FontMetrics</code> object. |
| * @throws NullPointerException if <code>data</code> is null. |
| * @throws IndexOutOfBoundsException if the <code>off</code> |
| * and <code>len</code> arguments index bytes outside |
| * the bounds of the <code>data</code> 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 |
| * <code>Font</code>. The advance is the |
| * distance from the leftmost point to the rightmost point on the |
| * character's baseline. Note that the advance of a |
| * <code>String</code> is not necessarily the sum of the advances |
| * of its characters. |
| * @return an array storing the advance widths of the |
| * characters in the <code>Font</code> |
| * described by this <code>FontMetrics</code> 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 <code>Font</code> has uniform line metrics. A |
| * composite font may consist of several different fonts to cover |
| * various character sets. In such cases, the |
| * <code>FontLineMetrics</code> 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 <code>true</code> if the font has uniform line metrics; |
| * <code>false</code> otherwise. |
| * @see java.awt.Font#hasUniformLineMetrics() |
| */ |
| public boolean hasUniformLineMetrics() { |
| return font.hasUniformLineMetrics(); |
| } |
| |
| /** |
| * Returns the {@link LineMetrics} object for the specified |
| * <code>String</code> in the specified {@link Graphics} context. |
| * @param str the specified <code>String</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>LineMetrics</code> object created with the |
| * specified <code>String</code> and <code>Graphics</code> 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 |
| * <code>String</code> in the specified {@link Graphics} context. |
| * @param str the specified <code>String</code> |
| * @param beginIndex the initial offset of <code>str</code> |
| * @param limit the end offset of <code>str</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>LineMetrics</code> object created with the |
| * specified <code>String</code> and <code>Graphics</code> 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 <code>chars</code> |
| * @param limit the end offset of <code>chars</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>LineMetrics</code> object created with the |
| * specified character array and <code>Graphics</code> 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 <code>CharacterIterator</code> |
| * @param beginIndex the initial offset in <code>ci</code> |
| * @param limit the end index of <code>ci</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>LineMetrics</code> 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 <code>String</code> in the |
| * specified <code>Graphics</code> context. The bounds is used |
| * to layout the <code>String</code>. |
| * <p>Note: The returned bounds is in baseline-relative coordinates |
| * (see {@link java.awt.FontMetrics class notes}). |
| * @param str the specified <code>String</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a {@link Rectangle2D} that is the bounding box of the |
| * specified <code>String</code> in the specified |
| * <code>Graphics</code> 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 <code>String</code> in the |
| * specified <code>Graphics</code> context. The bounds is used |
| * to layout the <code>String</code>. |
| * <p>Note: The returned bounds is in baseline-relative coordinates |
| * (see {@link java.awt.FontMetrics class notes}). |
| * @param str the specified <code>String</code> |
| * @param beginIndex the offset of the beginning of <code>str</code> |
| * @param limit the end offset of <code>str</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>Rectangle2D</code> that is the bounding box of the |
| * specified <code>String</code> in the specified |
| * <code>Graphics</code> 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 <code>Graphics</code> context. |
| * The bounds is used to layout the <code>String</code> |
| * created with the specified array of characters, |
| * <code>beginIndex</code> and <code>limit</code>. |
| * <p>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 <code>Graphics</code> context |
| * @return a <code>Rectangle2D</code> that is the bounding box of the |
| * specified character array in the specified |
| * <code>Graphics</code> 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 |
| * <code>CharacterIterator</code> in the |
| * specified <code>Graphics</code> context. |
| * <p>Note: The returned bounds is in baseline-relative coordinates |
| * (see {@link java.awt.FontMetrics class notes}). |
| * @param ci the specified <code>CharacterIterator</code> |
| * @param beginIndex the initial offset in <code>ci</code> |
| * @param limit the end index of <code>ci</code> |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>Rectangle2D</code> that is the bounding box of the |
| * characters indexed in the specified <code>CharacterIterator</code> |
| * in the specified <code>Graphics</code> 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 <code>Graphics</code> context. |
| * @param context the specified <code>Graphics</code> context |
| * @return a <code>Rectangle2D</code> 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 <code>FontMetrics</code> |
| * object's values as a <code>String</code>. |
| * @return a <code>String</code> representation of this |
| * <code>FontMetrics</code> 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(); |
| } |
