Summary

Update the specification of FontMetrics.getMaxAdvance() to document its limitations.

Problem

FontMetrics.getMaxAdvance() asserts that it will report the maximum advance of any character, but it may be wrong, for multiple reasons, including the use of fall back fonts and rasterisation effects.

Solution

Document the limitations of FontMetrics.getMaxAdvance(). Do not make code changes which might break applications.

Specification

public int java.awt.FontMetrics.getMaxAdvance()

PREVIOUS specification :-

/**
 * Gets the maximum advance width of any character in this
 * {@code Font}.  The advance is the
 * distance from the leftmost point to the rightmost point on the
 * string's baseline.  The advance of a {@code String} is
 * not necessarily the sum of the advances of its characters.
 * @return    the maximum advance width of any character
 *            in the {@code Font}, or {@code -1} if the
 *            maximum advance width is not known.
 */

NEW specification :-

/**
 * Returns an estimate of the maximum advance width of any character
 * in the {@code Font} described by this {@code FontMetrics} object,
 * with important caveats, enumerated below.
 * <p>
 * The advance is the distance from the leftmost point used to position
 * the character to the rightmost point along the baseline.
 * This is not the same thing as the visible width of the glyph image
 * representing the character.
 * <p>
 * The advance of a {@code String} is not necessarily the sum of the
 * advances of its characters. It may differ substantially if
 * complex text layout is required for proper rendering.
 * <p>
 * Some of the caveats of the reported value include
 * <ul>
 * <li> The returned value is relying upon information from some
 * underlying system font, and the correctness of that information
 * is outside of AWT's control.
 * <li> When specific characters are mapped into glyphs
 * in some rendering context, instructions in the font itself
 * together with the rasterization process may cause some glyph
 * to have a wider advance than reported.
 * <li> When a font is requested in some style, eg {@code Font.BOLD},
 * for which no exact match is available, then techniques to satisfy
 * the requested rendering may similarly result in glyphs that are
 * wider than the reported maximum.
 * <li> Depending on the implementation, an AWT logical font or
 * physical font may need to locate some characters from one or more
 * "fall back" fonts, when the primary underlying physical font does not
 * support the character. These fonts may not all be known or considered
 * in the calculation of the reported maximum advance. It is common
 * for the design center of such fall back fonts to be for a different
 * script than the design center of the primary font, so their
 * advances can be quite different. This can also lead to the
 * unexpected result that a font such as {@code Font.MONOSPACED} can
 * render glyphs that are not all the same width.
 * </ul>
 * None of these caveats are exposed as they are all implementation details,
 * and there is no practical way to determine when these are in effect.
 * An application which needs a better estimate of the maximum advance,
 * and knows the subset of characters it expects to display can query
 * the advance of each such character to find the widest, however,
 * as discussed above, since the displayed width of a {@code String}
 * is not necessarily the sum of the advances the value still needs
 * to be used with caution.
 * <p>
 * In summary, this method makes no absolute guarantee, nor can
 * it even make a guarantee to be correct within some margin of error.
 * So it should be used at most only for estimating the total space
 * sufficient to display some number of as yet unknown characters from
 * the font. And that might be either an overestimate, or an
 * underestimate depending on the specific text and rendering conext.
 * @return    an estimate of the maximum advance width of any character
 *            in the {@code Font}, or {@code -1} if the
 *            maximum advance width is not known.
 */