Styled Text Tutorial
Lesson 5: Drawing Styled Text

[Contents]

This lesson describes some of the java.awt.font.TextLayout methods. You have seen some of these methods in previous lessons, while others introduced here for the first time here.

• Baseline and Baseline Offsets
• Ascent, Descent, and Leading
• Advance and Visual Advance
• Bounds and Black Box Bounds
• Justified Text
• Character Level

Baseline

The baseline is the hypothetical line upon which characters rest. Some characters such as y and g have descenders that drop below the baseline.

A TextLayout object has methods for returning information about the baseline of the text. The methods support writing systems that use different baselines, and multiple such writing systems in the same line of text.

• TextLayout.getBaseline
• TextLayout.getBaselineOffsets

The baselines supported are Roman, centered, and hanging.

• Roman text uses the baseline that runs under the bottoms of the characters that do not have descenders.
• Chinese text uses a centered baseline that runs through the centers of the characters.
• The hanging baseline is used for languages, like Hindi, which generally align at the top.

Note: Currently, a TextLayout object uses the Roman baseline no matter what language the text is in. Many fonts assume the Roman baseline too, so these methods exist for typographic features that are not currently in widespread use. When TextLayout supports the Roman, centered, and hanging baselines, you will be able to use the information returned by these methods to align a line of text that uses different baselines.

Ascent, Descent, and Leading

Ascent, descent, and leading are properties of fonts. The ascent of a font is the distance from the tops of the tallest glyphs to the baseline.

The descent of a font is the distance from the baseline to the bottom of the lowest descenders on the glyphs.

The leading is the recommended vertical distance from the bottom of the descenders to the top of the next line in a multiline setting.

A TextLayout object has methods for returning information about the ascent, descent, and leading of the font. If the text string uses more than one font, the ascent and descent are computed as the maximum values for the fonts used in the TextLayout object.

• TextLayout.getAscent
• TextLayout.getDescent
• TextLayout.getLeading

Advance

The advance is the length of the string in the TextLayout, which is calculated as the distance from the left edge of the left-most glyph to the right edge of the right-most glyph.

The visual advance is the length of the string in the TextLayout object minus trailing whitespace.

A TextLayout object has methods for returning its advance and visual advance.

• TextLayout.getAdvance
• TextLayout.getVisualAdvance

Bounds

The bounding box encloses the text in the TextLayout object. It includes all the visible glyphs and the caret boundaries, some of which might hang over the origin or origin plus advance.

A TextLayout object has methods to return its bounds and the black box bounds for a range of characters. The bounding box returned by TextLayout.getBounds is relative to the origin of the TextLayout, and not to any particular screen position.

The black box bounds is the union of the bounding boxes of all the glyphs corresponding to the characters between a starting point and an ending point. In bidirectional text, this path might be disjoint either on the display or in the source text. See the Selection Highlighting section in Lesson 4 for information on how a range of characters in bidirectional text is not always contiguous.

• TextLayout.getBounds
• TextLayout.getBlackBoxBounds

Justified Text

TextLayout.getCharacterLevel is not implemented yet so you cannot justify a paragraph of text so all lines are equal in length. However, you can right, center, or left justify text by drawing the TextLayout object in a different location computed by calling TextLayout.getVisibleAdvance.

The LineBreakSample.java code shows how to left-align left-to-right text and right-align right-to-left text. Here is how to align the other possibilities.

To right-align a left-to-right layout: Draw at (rightMargin - layout.getVisibleAdvance()).

To center a left-to-right layout: Draw at
(leftMargin + rightMargin - layout.getVisibleAdvance()) / 2.

To left-align a right-to-left layout: Draw at
(leftMargin + (layout.getVisibleAdvance() - layout.getAdvance)).

To center a right-to-left layout: Draw at
(leftMargin + rightMargin + layout.getAdvance ()) / 2 - layout.getAdvance().

Character Level

TextLayout.getCharacterLevel returns the bidirectional level of the character as computed by the bidirectional algorithm. This is primarily used to determine if the character in question is a left-to-right or a right-to-left character (which depends on context and style information, and is not a simple character property). The level (0-16 inclusive) is returned so clients with particular user interface needs (for instance, clients building user interfaces that show nested bidirectional levels in some way) have access to the full information.

© 1994-2005 Sun Microsystems, Inc.