FontMetrics.java revision 2362
3261N/A * Copyright (c) 1995, 2005, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 243N/A * The <code>FontMetrics</code> class defines a font metrics object, which 0N/A * encapsulates information about the rendering of a particular font on a 0N/A * particular screen. 0N/A * <b>Note to subclassers</b>: Since many of these methods form closed, 0N/A * mutually recursive loops, you must take care that you implement 0N/A * at least one of the methods in each such loop to prevent 0N/A * infinite recursion when your subclass is used. 0N/A * In particular, the following is the minimal suggested set of methods 0N/A * to override in order to ensure correctness and prevent infinite 0N/A * recursion (though other subsets are equally feasible): 0N/A * <li>{@link #getAscent()} 0N/A * <li>{@link #getLeading()} 0N/A * <li>{@link #getMaxAdvance()} 0N/A * <li>{@link #charWidth(char)} 0N/A * <li>{@link #charsWidth(char[], int, int)} 0N/A * ALIGN=right HSPACE=10 VSPACE=7> 0N/A * Note that the implementations of these methods are 0N/A * inefficient, so they are usually overridden with more efficient 0N/A * toolkit-specific implementations. 0N/A * When an application asks to place a character at the position 0N/A * (<i>x</i>, <i>y</i>), the character is placed so that its 0N/A * reference point (shown as the dot in the accompanying image) is 0N/A * put at that position. The reference point specifies a horizontal 0N/A * line called the <i>baseline</i> of the character. In normal 0N/A * printing, the baselines of characters should align. 0N/A * In addition, every character in a font has an <i>ascent</i>, a 0N/A * <i>descent</i>, and an <i>advance width</i>. The ascent is the 0N/A * amount by which the character ascends above the baseline. The 0N/A * descent is the amount by which the character descends below the 0N/A * baseline. The advance width indicates the position at which AWT 0N/A * should place the next character. 0N/A * An array of characters or a string can also have an ascent, a 0N/A * descent, and an advance width. The ascent of the array is the 0N/A * maximum ascent of any character in the array. The descent is the 0N/A * maximum descent of any character in the array. The advance width 0N/A * is the sum of the advance widths of each of the characters in the 0N/A * character array. The advance of a <code>String</code> is the 0N/A * distance along the baseline of the <code>String</code>. This 0N/A * distance is the width that should be used for centering or 0N/A * right-aligning the <code>String</code>. 0N/A * <p>Note that the advance of a <code>String</code> is not necessarily 0N/A * the sum of the advances of its characters measured in isolation 0N/A * because the width of a character can vary depending on its context. 0N/A * For example, in Arabic text, the shape of a character can change 0N/A * in order to connect to other characters. Also, in some scripts, 0N/A * certain character sequences can be represented by a single shape, 0N/A * called a <em>ligature</em>. Measuring characters individually does 0N/A * not account for these transformations. 0N/A * <p>Font metrics are baseline-relative, meaning that they are 0N/A * generally independent of the rotation applied to the font (modulo 0N/A * possible grid hinting effects). See {@link java.awt.Font Font}. 0N/A * @author Jim Graham 0N/A * @see java.awt.Font 0N/A /* ensure that the necessary native libraries are loaded */ 0N/A * The actual {@link Font} from which the font metrics are 0N/A * This cannot be null. 0N/A * JDK 1.1 serialVersionUID 0N/A * Creates a new <code>FontMetrics</code> object for finding out 0N/A * height and width information about the specified <code>Font</code> 0N/A * and specific character glyphs in that <code>Font</code>. 0N/A * @param font the <code>Font</code> 0N/A * @see java.awt.Font 0N/A * Gets the <code>Font</code> described by this 0N/A * <code>FontMetrics</code> object. 0N/A * @return the <code>Font</code> described by this 0N/A * <code>FontMetrics</code> object. 0N/A * Gets the <code>FontRenderContext</code> used by this 0N/A * <code>FontMetrics</code> object to measure text. 0N/A * Note that methods in this class which take a <code>Graphics</code> 0N/A * parameter measure text using the <code>FontRenderContext</code> 0N/A * of that <code>Graphics</code> object, and not this 0N/A * <code>FontRenderContext</code> 0N/A * @return the <code>FontRenderContext</code> used by this 0N/A * <code>FontMetrics</code> object. 0N/A * Determines the <em>standard leading</em> of the 0N/A * <code>Font</code> described by this <code>FontMetrics</code> 0N/A * object. The standard leading, or 0N/A * interline spacing, is the logical amount of space to be reserved 0N/A * between the descent of one line of text and the ascent of the next 0N/A * line. The height metric is calculated to include this extra space. 0N/A * @return the standard leading of the <code>Font</code>. 0N/A * @see #getDescent() 0N/A * Determines the <em>font ascent</em> of the <code>Font</code> 0N/A * described by this <code>FontMetrics</code> object. The font ascent 0N/A * is the distance from the font's baseline to the top of most 0N/A * alphanumeric characters. Some characters in the <code>Font</code> 0N/A * might extend above the font ascent line. 0N/A * @return the font ascent of the <code>Font</code>. 0N/A * @see #getMaxAscent() 0N/A * Determines the <em>font descent</em> of the <code>Font</code> 0N/A * <code>FontMetrics</code> object. The font descent is the distance 0N/A * from the font's baseline to the bottom of most alphanumeric 0N/A * characters with descenders. Some characters in the 0N/A * <code>Font</code> might extend 0N/A * below the font descent line. 0N/A * @return the font descent of the <code>Font</code>. 0N/A * @see #getMaxDescent() 0N/A * Gets the standard height of a line of text in this font. This 0N/A * is the distance between the baseline of adjacent lines of text. 0N/A * It is the sum of the leading + ascent + descent. Due to rounding 0N/A * this may not be the same as getAscent() + getDescent() + getLeading(). 0N/A * There is no guarantee that lines of text spaced at this distance are 0N/A * disjoint; such lines may overlap if some characters overshoot 0N/A * either the standard ascent or the standard descent metric. 0N/A * @return the standard height of the font. 0N/A * @see #getLeading() 0N/A * @see #getDescent() 0N/A * Determines the maximum ascent of the <code>Font</code> 0N/A * described by this <code>FontMetrics</code> object. No character 0N/A * extends further above the font's baseline than this height. 0N/A * @return the maximum ascent of any character in the 0N/A * <code>Font</code>. 0N/A * Determines the maximum descent of the <code>Font</code> 0N/A * described by this <code>FontMetrics</code> object. No character 0N/A * extends further below the font's baseline than this height. 0N/A * @return the maximum descent of any character in the 0N/A * <code>Font</code>. 0N/A * @see #getDescent() 0N/A * For backward compatibility only. 0N/A * @return the maximum descent of any character in the 0N/A * <code>Font</code>. 0N/A * @see #getMaxDescent() 0N/A * @deprecated As of JDK version 1.1.1, 0N/A * replaced by <code>getMaxDescent()</code>. 0N/A * Gets the maximum advance width of any character in this 0N/A * <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * string's baseline. The advance of a <code>String</code> is 0N/A * not necessarily the sum of the advances of its characters. 0N/A * @return the maximum advance width of any character 0N/A * in the <code>Font</code>, or <code>-1</code> if the 0N/A * maximum advance width is not known. 0N/A * Returns the advance width of the specified character in this 0N/A * <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * character's baseline. Note that the advance of a 0N/A * <code>String</code> is not necessarily the sum of the advances 0N/A * of its characters. 0N/A * <p>This method doesn't validate the specified character to be a 0N/A * valid Unicode code point. The caller must validate the 0N/A * character value using {@link 0N/A * java.lang.Character#isValidCodePoint(int) 0N/A * Character.isValidCodePoint} if necessary. 0N/A * @param codePoint the character (Unicode code point) to be measured 0N/A * @return the advance width of the specified character 0N/A * in the <code>Font</code> described by this 0N/A * <code>FontMetrics</code> object. 0N/A * @see #charsWidth(char[], int, int) 0N/A * @see #stringWidth(String) 0N/A * Returns the advance width of the specified character in this 0N/A * <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * character's baseline. Note that the advance of a 0N/A * <code>String</code> is not necessarily the sum of the advances 0N/A * of its characters. 0N/A * <p><b>Note:</b> This method cannot handle <a 0N/A * characters</a>. To support all Unicode characters, including 0N/A * supplementary characters, use the {@link #charWidth(int)} method. 0N/A * @param ch the character to be measured 0N/A * @return the advance width of the specified character 0N/A * in the <code>Font</code> described by this 0N/A * <code>FontMetrics</code> object. 0N/A * @see #charsWidth(char[], int, int) 0N/A * @see #stringWidth(String) 0N/A * Returns the total advance width for showing the specified 0N/A * <code>String</code> in this <code>Font</code>. The advance 0N/A * is the distance from the leftmost point to the rightmost point 0N/A * on the string's baseline. 0N/A * Note that the advance of a <code>String</code> is 0N/A * not necessarily the sum of the advances of its characters. 0N/A * @param str the <code>String</code> to be measured 0N/A * @return the advance width of the specified <code>String</code> 0N/A * in the <code>Font</code> described by this 0N/A * <code>FontMetrics</code>. 0N/A * @throws NullPointerException if str is null. 0N/A * @see #bytesWidth(byte[], int, int) 0N/A * @see #charsWidth(char[], int, int) 0N/A * @see #getStringBounds(String, Graphics) 0N/A * Returns the total advance width for showing the specified array 0N/A * of characters in this <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * string's baseline. The advance of a <code>String</code> 0N/A * is not necessarily the sum of the advances of its characters. 0N/A * This is equivalent to measuring a <code>String</code> of the 0N/A * characters in the specified range. 0N/A * @param data the array of characters to be measured 0N/A * @param off the start offset of the characters in the array 0N/A * @param len the number of characters to be measured from the array 0N/A * @return the advance width of the subarray of the specified 0N/A * <code>char</code> array in the font described by 0N/A * this <code>FontMetrics</code> object. 0N/A * @throws NullPointerException if <code>data</code> is null. 0N/A * @throws IndexOutOfBoundsException if the <code>off</code> 0N/A * and <code>len</code> arguments index characters outside 3025N/A * the bounds of the <code>data</code> array. 0N/A * @see #charWidth(int) 0N/A * @see #charWidth(char) 0N/A * @see #bytesWidth(byte[], int, int) 0N/A * @see #stringWidth(String) 0N/A * Returns the total advance width for showing the specified array 0N/A * of bytes in this <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * string's baseline. The advance of a <code>String</code> 243N/A * is not necessarily the sum of the advances of its characters. 0N/A * This is equivalent to measuring a <code>String</code> of the 544N/A * characters in the specified range. 544N/A * @param data the array of bytes to be measured 544N/A * @param off the start offset of the bytes in the array 544N/A * @param len the number of bytes to be measured from the array 544N/A * @return the advance width of the subarray of the specified 0N/A * <code>byte</code> array in the <code>Font</code> 0N/A * this <code>FontMetrics</code> object. 0N/A * @throws NullPointerException if <code>data</code> is null. 0N/A * @throws IndexOutOfBoundsException if the <code>off</code> 0N/A * and <code>len</code> arguments index bytes outside 0N/A * the bounds of the <code>data</code> array. 0N/A * @see #charsWidth(char[], int, int) 0N/A * @see #stringWidth(String) 0N/A * Gets the advance widths of the first 256 characters in the 0N/A * <code>Font</code>. The advance is the 0N/A * distance from the leftmost point to the rightmost point on the 0N/A * character's baseline. Note that the advance of a 0N/A * <code>String</code> is not necessarily the sum of the advances 0N/A * of its characters. 0N/A * @return an array storing the advance widths of the 0N/A * characters in the <code>Font</code> 0N/A * described by this <code>FontMetrics</code> object. 0N/A * Checks to see if the <code>Font</code> has uniform line metrics. A 0N/A * composite font may consist of several different fonts to cover 0N/A * various character sets. In such cases, the 0N/A * <code>FontLineMetrics</code> objects are not uniform. 0N/A * Different fonts may have a different ascent, descent, metrics and 0N/A * so on. This information is sometimes necessary for line 0N/A * measuring and line breaking. 0N/A * @return <code>true</code> if the font has uniform line metrics; 0N/A * <code>false</code> otherwise. 0N/A * @see java.awt.Font#hasUniformLineMetrics() 0N/A * Returns the {@link LineMetrics} object for the specified 0N/A * <code>String</code> in the specified {@link Graphics} context. 0N/A * @param str the specified <code>String</code> 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>LineMetrics</code> object created with the 0N/A * specified <code>String</code> and <code>Graphics</code> context. 0N/A * @see java.awt.Font#getLineMetrics(String, FontRenderContext) 0N/A * Returns the {@link LineMetrics} object for the specified 0N/A * <code>String</code> in the specified {@link Graphics} context. 0N/A * @param str the specified <code>String</code> 0N/A * @param beginIndex the initial offset of <code>str</code> 0N/A * @param limit the end offset of <code>str</code> 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>LineMetrics</code> object created with the 0N/A * specified <code>String</code> and <code>Graphics</code> context. 0N/A * @see java.awt.Font#getLineMetrics(String, int, int, FontRenderContext) 0N/A * Returns the {@link LineMetrics} object for the specified 0N/A * character array in the specified {@link Graphics} context. 0N/A * @param chars the specified character array 0N/A * @param beginIndex the initial offset of <code>chars</code> 0N/A * @param limit the end offset of <code>chars</code> 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>LineMetrics</code> object created with the 0N/A * specified character array and <code>Graphics</code> context. 0N/A * @see java.awt.Font#getLineMetrics(char[], int, int, FontRenderContext) 0N/A * Returns the {@link LineMetrics} object for the specified 544N/A * {@link CharacterIterator} in the specified {@link Graphics} 544N/A * @param ci the specified <code>CharacterIterator</code> 544N/A * @param beginIndex the initial offset in <code>ci</code> 544N/A * @param limit the end index of <code>ci</code> 0N/A * @param context the specified <code>Graphics</code> context 544N/A * @return a <code>LineMetrics</code> object created with the 544N/A * @see java.awt.Font#getLineMetrics(CharacterIterator, int, int, FontRenderContext) 0N/A * Returns the bounds of the specified <code>String</code> in the 0N/A * specified <code>Graphics</code> context. The bounds is used 0N/A * to layout the <code>String</code>. 0N/A * <p>Note: The returned bounds is in baseline-relative coordinates 544N/A * (see {@link java.awt.FontMetrics class notes}). 544N/A * @param str the specified <code>String</code> 544N/A * @param context the specified <code>Graphics</code> context 544N/A * @return a {@link Rectangle2D} that is the bounding box of the 544N/A * specified <code>String</code> in the specified 544N/A * <code>Graphics</code> context. 544N/A * @see java.awt.Font#getStringBounds(String, FontRenderContext) 544N/A * Returns the bounds of the specified <code>String</code> in the 544N/A * specified <code>Graphics</code> context. The bounds is used 0N/A * to layout the <code>String</code>. 0N/A * <p>Note: The returned bounds is in baseline-relative coordinates 0N/A * (see {@link java.awt.FontMetrics class notes}). 0N/A * @param str the specified <code>String</code> 0N/A * @param beginIndex the offset of the beginning of <code>str</code> 0N/A * @param limit the end offset of <code>str</code> 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>Rectangle2D</code> that is the bounding box of the 0N/A * specified <code>String</code> in the specified 0N/A * <code>Graphics</code> context. 0N/A * @see java.awt.Font#getStringBounds(String, int, int, FontRenderContext) 0N/A * Returns the bounds of the specified array of characters 0N/A * in the specified <code>Graphics</code> context. 0N/A * The bounds is used to layout the <code>String</code> 0N/A * created with the specified array of characters, 0N/A * <code>beginIndex</code> and <code>limit</code>. 0N/A * <p>Note: The returned bounds is in baseline-relative coordinates 0N/A * (see {@link java.awt.FontMetrics class notes}). 0N/A * @param chars an array of characters 0N/A * @param beginIndex the initial offset of the array of 0N/A * @param limit the end offset of the array of characters 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>Rectangle2D</code> that is the bounding box of the 0N/A * specified character array in the specified 0N/A * <code>Graphics</code> context. 0N/A * @see java.awt.Font#getStringBounds(char[], int, int, FontRenderContext) 0N/A * Returns the bounds of the characters indexed in the specified 0N/A * <code>CharacterIterator</code> in the 0N/A * specified <code>Graphics</code> context. 0N/A * <p>Note: The returned bounds is in baseline-relative coordinates 0N/A * (see {@link java.awt.FontMetrics class notes}). 0N/A * @param ci the specified <code>CharacterIterator</code> 0N/A * @param beginIndex the initial offset in <code>ci</code> 0N/A * @param limit the end index of <code>ci</code> 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>Rectangle2D</code> that is the bounding box of the 0N/A * characters indexed in the specified <code>CharacterIterator</code> 0N/A * in the specified <code>Graphics</code> context. 0N/A * @see java.awt.Font#getStringBounds(CharacterIterator, int, int, FontRenderContext) 0N/A * Returns the bounds for the character with the maximum bounds 0N/A * in the specified <code>Graphics</code> context. 0N/A * @param context the specified <code>Graphics</code> context 0N/A * @return a <code>Rectangle2D</code> that is the 0N/A * bounding box for the character with the maximum bounds. 0N/A * @see java.awt.Font#getMaxCharBounds(FontRenderContext) 0N/A * Returns a representation of this <code>FontMetrics</code> 0N/A * object's values as a <code>String</code>. 0N/A * @return a <code>String</code> representation of this 0N/A * <code>FontMetrics</code> object. 0N/A * Initialize JNI field and method IDs