Java Doc for FontMetrics.java in  » 6.0-JDK-Core » AWT » java » awt » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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):

• FontMetrics.getAscent()
• FontMetrics.getLeading()
• FontMetrics.getMaxAdvance()
• FontMetrics.charWidth(char)
• FontMetrics.charsWidth(char[],int,int)

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 (x, y), 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 java.awt.Font Font .
version:
   1.65 05/05/07
author:
   Jim Graham
See Also:   java.awt.Font
since:
   JDK1.0

Note: The returned bounds is in baseline-relative coordinates (see java.awt.FontMetrics class notes ).
Parameters:
  chars - an array of characters
Parameters:
  beginIndex - the initial offset of the array ofcharacters
Parameters:
  limit - the end offset of the array of characters
Parameters:
  context - the specified Graphics context a Rectangle2D that is the bounding box of thespecified character array in the specifiedGraphics context.

This method doesn't validate the specified character to be a valid Unicode code point. The caller must validate the character value using java.lang.Character.isValidCodePoint(int)Character.isValidCodePoint if necessary.
Parameters:
  codePoint - the character (Unicode code point) to be measured the advance width of the specified characterin the Font described by thisFontMetrics object.
See Also:   FontMetrics.charsWidth(char[],int,int)
See Also:   FontMetrics.stringWidth(String)

Note: This method cannot handle supplementary characters. To support all Unicode characters, including supplementary characters, use the FontMetrics.charWidth(int) method.
Parameters:
  ch - the character to be measured the advance width of the specified characterin the Font described by this FontMetrics object.
See Also:   FontMetrics.charsWidth(char[],int,int)
See Also:   FontMetrics.stringWidth(String)

Note that methods in this class which take a Graphics parameter measure text using the FontRenderContext of that Graphics object, and not this FontRenderContext the FontRenderContext used by this FontMetrics object.
since:
   1.6

Note: The returned bounds is in baseline-relative coordinates (see java.awt.FontMetrics class notes ).
Parameters:
  str - the specified String
Parameters:
  context - the specified Graphics context a Rectangle2D that is the bounding box of thespecified String in the specifiedGraphics context.
See Also:   java.awt.Font.getStringBounds(StringFontRenderContext)

Note: The returned bounds is in baseline-relative coordinates (see java.awt.FontMetrics class notes ).
Parameters:
  str - the specified String
Parameters:
  beginIndex - the offset of the beginning of str
Parameters:
  limit - the end offset of str
Parameters:
  context - the specified Graphics context a Rectangle2D that is the bounding box of thespecified String in the specifiedGraphics context.
See Also:   java.awt.Font.getStringBounds(StringintintFontRenderContext)

Note: The returned bounds is in baseline-relative coordinates (see java.awt.FontMetrics class notes ).
Parameters:
  chars - an array of characters
Parameters:
  beginIndex - the initial offset of the array ofcharacters
Parameters:
  limit - the end offset of the array of characters
Parameters:
  context - the specified Graphics context a Rectangle2D that is the bounding box of thespecified character array in the specifiedGraphics context.
See Also:   java.awt.Font.getStringBounds(char[]intintFontRenderContext)

Note: The returned bounds is in baseline-relative coordinates (see java.awt.FontMetrics class notes ).
Parameters:
  ci - the specified CharacterIterator
Parameters:
  beginIndex - the initial offset in ci
Parameters:
  limit - the end index of ci
Parameters:
  context - the specified Graphics context a Rectangle2D that is the bounding box of thecharacters indexed in the specified CharacterIteratorin the specified Graphics context.
See Also:   java.awt.Font.getStringBounds(CharacterIteratorintintFontRenderContext)

Note that the advance of a String is not necessarily the sum of the advances of its characters.
Parameters:
  str - the String to be measured the advance width of the specified Stringin the Font described by thisFontMetrics.
throws:
  NullPointerException - if str is null.
See Also:   FontMetrics.bytesWidth(byte[],int,int)
See Also:   FontMetrics.charsWidth(char[],int,int)
See Also:   FontMetrics.getStringBounds(String,Graphics)