Working with Text

Support for working with primitive text is spread between the AWT Graphics, Font,, and FontMetrics classes.
Drawing Text
When you're writing code to draw text, you should first consider whether you can use a text-oriented Component, such as the Label, TextField, or TextArea class. If a Component isn't appropriate, you can use the Graphics drawBytes(), drawChars(), or drawString() methods.
Here is an example of code that draws a string to the screen:
g.drawString("Hello World!", x, y);
For the text drawing methods, x and y are integers that specify the position of the lower left corner of the text. To be precise, the y coordinate specifies the baseline of the text -- the line that most letters rest on -- which doesn't include room for the tails (descenders) on letters such as "y". Be sure to make y large enough to allow vertical space for the text, but small enough to allow room for descenders.
Here's a figure that shows the baseline, as well as the ascender and descender lines. You'll learn more about ascenders and descenders a bit later.
Here is a simple applet that illustrates what can happen when you're not careful about where you position your text:

Note: Because some old browsers don't support 1.1, the above applet is a 1.0 version (here is the 1.0 code; here's the 1.1 code). To run the 1.1 version of the applet, go to example-1dot1/TextXY.html. For more information about running applets, refer to About Our Examples.
The top string is probably cut off, since its y argument is 5, which leaves only 5 pixels above the baseline for the string -- not enough for most fonts. The middle string probably shows up just fine, unless you have a huge default font. Most of the letters in the bottom string display fine, except for letters with descenders. All descenders in the bottom string are cut off, since the code that displays this string doesn't allow room for them.
Note: The text-drawing methods' interpretation of x and y is different from that of the shape-drawing methods. When drawing a shape (such as a rectangle), x and y specify the upper left corner of the shape's bounding rectangle, instead of the lower left corner.
Getting Information about a Font: FontMetrics
The shape-drawing example from before could be improved by choosing a font that's smaller than the usual default font. The following example does this and also enlarges the shapes to take up the space freed by the font's smaller height. Here is the improved applet:

Note: Because some old browsers don't support 1.1, the above applet is a 1.0 version (here is the 1.0 code; here's the 1.1 code). To run the 1.1 version of the applet, go to example-1dot1/FontDemo.html. For more information about running applets, refer to About Our Examples.
The example chooses the appropriate font by using a FontMetrics object to get details of the font's size. For example, the following loop ensures that the longest string displayed by the applet ("drawRoundRect()") fits within the space each shape is allotted.
boolean fontFits = false;
Font font = g.getFont();
FontMetrics fontMetrics = g.getFontMetrics();
int size = font.getSize();
String name = font.getName();
int style = font.getStyle();

while (!fontFits) {
    if ( (fontMetrics.getHeight() <= maxCharHeight)
      && (fontMetrics.stringWidth(longString) 
	  <= xSpace)) {
        fontFits = true;
    } else {
        if (size <= minFontSize) {
            fontFits = true;
        } else {
            g.setFont(font = new Font(name,
                                      style,
                                      --size));
            fontMetrics = g.getFontMetrics();
        }
    }
}
The example code above uses the Graphics getFont(), setFont(), and getFontMetrics() methods to get and set the current font and to get the FontMetrics object that corresponds to the font. From the FontMetrics getHeight() and getStringWidth() methods, the example code gets vertical and horizontal size information about the font.
The following figure shows some of the information that a FontMetrics object can provide about a font's size.

Here's a summary of the FontMetrics methods that return information about a font's vertical size:

getAscent(), getMaxAscent()
The getAscent() method returns the number of pixels between the ascender line and the baseline. Generally, the ascender line represents the typical height of capital letters. Specifically, the ascent and descent values are chosen by the font's designer to represent the correct text "color", or density of ink, so that the text appears as the designer planned it. The ascent typically provides enough room for almost all of the characters in the font, except perhaps for accents on capital letters. The getMaxAscent() method accounts for these exceptionally tall characters.

getDescent(), getMaxDescent()
The getDescent() method returns the number of pixels between the baseline and the descender line. In most fonts, all characters fall within the descender line at their lowest point. Just in case, though, you can use the getMaxDescent() method to get a distance guaranteed to encompass all characters.

getHeight()
Returns the number of pixels normally found between the baseline of one line of text and the baseline of the next line of text. Note that this includes an allowance for leading.

getLeading()
Returns the suggested distance (in pixels) between one line of text and the next. Specifically the leading is the distance between the descender line of one line of text and the ascender line of the next line of text. By the way, leading is pronounced LEDDing.

Note that the font size (returned by the Font class getSize() method) is an abstract measurement. Theoretically, it corresponds to the ascent plus the descent. Practically, however, the font designer decides exactly how tall a "12 point" font (for example) is. For example, 12-point Times is often slightly shorter than 12-point Helvetica. Typically, font size is measured in points, which are approximately 1/72 of an inch.
The following list shows the methods that FontMetrics provides to return information about the horizontal size of a font's characters. These methods take into account the spacing around each character. More precisely, each method returns not the number of pixels taken up by a particular character (or characters), but the number of pixels by which the current point will be advanced when that character (or characters) is shown. We call this the advance width to distinguish it from the character or text width.

getMaxAdvance()
The advance width (in pixels) of the widest character in the font.
bytesWidth(byte[], int, int)
The advance width of the text represented by the specified array of bytes. The first integer argument specifies the starting offset of the data within the byte array. The second integer argument specifies the maximum number of bytes to check.
charWidth(int), charWidth(char)
The advance width of the specified character.
charsWidth(char[], int, int)
The advance width of the string represented by the specified character array.
stringWidth(String)
The advance width of the specified string.
getWidths()
The advance width of each of the first 256 characters in the font.

Working with Graphics