Chapter 15. The java.awt.font Package

FontRenderContext	Java 1.2
java.awt.font

This class stores the information necessary to precisely measure the size of text. It is used by a number of Font methods and also by TextLayout and LineBreakMeasurer. Although FontRenderContext has a public constructor, it is more common to obtain a FontRenderContext by calling the getFontRenderContext() method of a Graphics2D object.

Passed To: Too many methods to list.

Returned By: Graphics2D.getFontRenderContext(), GlyphVector.getFontRenderContext()

GlyphJustificationInfo	Java 1.2
java.awt.font

This class contains information about how much whitespace may be added to or removed from the left and right sides of a glyph without unduly compromising the appearance of the text output. This information is used by algorithms that perform fill justification to force a line of text to an exact size. Only applications that perform high-end typography need to use this class.

Returned By: GlyphVector.getGlyphJustificationInfo(), GraphicAttribute.getJustificationInfo()

GlyphMetrics	Java 1.2
java.awt.font

This class contains measurements for a single glyph of a font. Although GlyphMetrics has a public constructor, the only way to obtain actual metrics for a glyph is by calling the getGlyphMetrics() method of a GlyphVector.

Each glyph has an origin. The getAdvance() method returns the standard distance between the origin of this glyph and the origin of the next glyph in the GlyphVector from which the GlyphMetrics was obtained. getBounds2D() returns the bounding box of the glyph. This rectangle is positioned relative to the origin of the glyph. getLSB() returns the left-side bearing of the glyph: the distance between the origin and the left side of the bounding box. getRSB() returns the right-side bearing: the distance between the right side of the bounding box and the start of the next glyph. For some glyphs, these bearing values may be negative.

getType() returns the type of the glyph; the return value is one of the constants defined by the class. Most glyphs are of STANDARD type. Glyphs with no visible representation are of type WHITESPACE. Glyphs that represent more than one character have type LIGATURE. Accents and other diacritical marks that modify other glyphs have type COMBINING. Finally, when one character is represented by two or more glyphs, the extra glyph or glyphs have the type COMPONENT.

Returned By: GlyphVector.getGlyphMetrics()

GlyphVector	Java 1.2
java.awt.font	cloneable

This class represents an array of glyphs taken from a single font that are to be drawn on a single line. You obtain a GlyphVector by calling the createGlyphVector() method of a Font object, and you draw a GlyphVector with the drawGlyphVector() method of a Graphics2D object.

When a string is drawn using the drawString() method of Graphics or Graphics2D, the characters of the string first must be converted to font glyphs, and then those glyphs must be drawn. Thus, if a string is to be drawn repeatedly, it can be more efficient to separate these two steps, converting the string to a GlyphVector once and then drawing that GlyphVector multiple times.

Hierarchy: Object-->GlyphVector(Cloneable)

Passed To: Graphics2D.drawGlyphVector(), GlyphVector.equals()

Returned By: Font.createGlyphVector()

GraphicAttribute	Java 1.2
java.awt.font

This abstract class represents a graphic to be embedded in a line of text in lieu of a regular font glyph. A GraphicAttribute is used as the value of an TextAttribute.CHAR_REPLACEMENT attribute in a java.text.AttributedString or java.text.AttributedCharacterIterator. Most applications use one of the two subclasses ImageGraphicAttribute and ShapeGraphicAttribute. Few applications need to create custom subclasses of their own.

The draw() method is responsible for actually drawing the desired graphic. The other methods return various measurements for the graphic. The constants are possible alignment values returned by getAligment().

Subclasses: ImageGraphicAttribute, ShapeGraphicAttribute

ImageGraphicAttribute	Java 1.2
java.awt.font

This concrete subclass of GraphicAttribute allows an image to be drawn within a string of text. Create an ImageGraphicAttribute by specifying an image to draw, an alignment (one of the constants defined by GraphicAttribute), and, optionally, an origin for the image. The origin coordinates are relative to the image itself. Use the ImageGraphicAttribute by specifying it as the value of a TextAttribute.CHAR_REPLACEMENT attribute in a java.text.AttributedString or java.text.AttributedCharacterIterator.

See also ShapeGraphicAttribute.

Hierarchy: Object-->GraphicAttribute-->ImageGraphicAttribute

Passed To: ImageGraphicAttribute.equals()

LineBreakMeasurer	Java 1.2
java.awt.font

This class breaks a paragraph of text into individual lines of a specified width, where each line is represented by a TextLayout object. When you create a LineBreakMeasurer, you must specify the paragraph to be broken with a java.text.AttributedCharacterIterator, which is usually is obtained from a java.text.AttributedString. You may optionally specify a java.text.BreakIterator to indicate where line breaks are allowed. The default is to use the line breaking rules of the current locale. You must also pass a FontRenderContext to the LineBreakMeasurer() constructor. The FontRenderContext is usually obtained with the getFontRenderContext() method of Graphics2D.

Once you have created a LineBreakMeasurer for your paragraph, you use it by repeatedly calling nextLayout() to create TextLayout objects that represent lines. nextLayout() returns null when it reaches the end of the paragraph. The desired width of each line is passed as an argument to nextLayout(). This allows the first line of a paragraph to be made shorter than the following lines, for example.

LineMetrics	Java 1.2
java.awt.font

This class provides access to various measurements for the characters in a font. The name LineMetrics is somewhat confusing; it refers to the general line metrics of a font, not the metrics of some particular line of text rendered with the font. LineMetrics provides more accurate metrics than java.awt.FontMetrics and also includes some metrics that are simply not available through that class.

Obtain a LineMetrics object by calling one of the getLineMetrics() methods of Font or FontMetrics. These methods require that you supply some form of text to measure. The returned LineMetrics object does not contain the width of that text, but the font measurements it does return may depend on the content of the text. For example, the metrics for English text may differ from metrics for Japanese text. (Note, however, that the initial implementation from Sun simply ignores the text you specify.) If the supplied text contains characters from more than one language, the returned metrics may apply only to a prefix of the text. The getNumChars() method returns the length of this prefix.

Once you have obtained a LineMetrics object, you can call its various accessor methods to obtain information about the font. getAscent() returns the distance between the baseline and the top of the tallest character. getDescent() returns the distance between the baseline and the bottom of the lowest descender. getLeading() returns the recommended interline spacing for the font (so named for the strips of lead that used to be placed between rows of movable type). getHeight() returns the distance between the baseline of one line and the baseline of the next. It is equal to the sum of the ascent, descent, and leading. getUnderlineOffset() returns the recommended position of an underline, relative to the baseline for the font, and getUnderlineThickness() returns the recommended thickness of an underline. Two similar methods return the position and thickness of lines used to strike through characters in the font.

Returned By: Font.getLineMetrics(), FontMetrics.getLineMetrics()

MultipleMaster	Java 1.2
java.awt.font

This interface describes capabilities of Type 1 Multiple Master fonts. If a Font object represents a Multiple Master font, it implements the MultipleMaster interface. Most fonts have only one parameter that you can vary: the point size. A Multiple Master font is a generalization that allows you to vary any number of design axes of the font. These design axes may be things such as font weight, average glyph width, italic angle, and so forth. The methods of the MultipleMaster interface allow you to query the names, defaults, and valid ranges of these design axes and derive new versions of the font by specifying values for each axis.

OpenType	Java 1.2
java.awt.font

This interface is implemented by Font objects that represent OpenType and TrueType fonts. It allows access to tables of raw font data. You should use this interface only if you are intimately familiar with the font data format for OpenType and TrueType fonts.

ShapeGraphicAttribute	Java 1.2
java.awt.font

This concrete subclass of GraphicAttribute allows an arbitrary shape to be drawn within a string of text. Create a ShapeGraphicAttribute by specifying a shape to draw and an alignment (one of the constants defined by GraphicAttribute) that specifies how the shape is aligned with the rest of the text. Pass true for the third argument, stroke, if the shape should simply be drawn, or pass false if the shape should be filled. Use the ShapeGraphicAttribute by specifying it as the value of a TextAttribute.CHAR_REPLACEMENT attribute in a java.text.AttributedString or java.text.AttributedCharacterIterator

See also ImageGraphicAttribute.

Hierarchy: Object-->GraphicAttribute-->ShapeGraphicAttribute

Passed To: ShapeGraphicAttribute.equals()

TextAttribute	Java 1.2
java.awt.font	serializable

This class defines constants that serve as attribute names and attribute values for use with java.text.AttributedString and java.text.AttributedCharacterIterator objects. The constants of type TextAttribute serve as attribute names. The other constants define commonly used values for those attributes. Note that the value of the CHAR_REPLACEMENT attribute should be a GraphicAttribute object, and the value of the TRANSFORM attribute should be a TransformAttribute object.

Hierarchy: Object-->java.text.AttributedCharacterIterator.Attribute(Serializable)-->TextAttribute

Type Of: Too many fields to list.

TextHitInfo	Java 1.2
java.awt.font

This class encapsulates the position of a character within a string of text and the bias, or side, of the character. The hitTestChar() method of TextLayout takes the position of a mouse click and returns a TextHitInfo that specifies where the click occurred.

getCharIndex() returns the position of the character that was hit. getInsertionIndex() returns the position at which characters should be inserted or deleted. This may or may not be the same as the value returned by getCharIndex(). isLeadingEdge() specifies whether the hit was on the leading edge of the character.

If you want to place the insertion cursor at the position of the mouse click, it is not sufficient to know which character was clicked on; you must also know whether the leading edge or the trailing edge of the character was clicked on. This is particularly important when working with bidirectional text, such as Arabic or Hebrew. If the TextHitInfo specifies that the trailing edge was selected, the insertion cursor should be placed before the character. Otherwise, it should be placed after the character.

In bidirectional text, positioning the cursor correctly in response to user requests to move it left or right can be quite tricky. TextHitInfo is also returned by the getNextLeftHit() and getNextRightHit() methods of TextLayout, to help solve this problem.

Passed To: Too many methods to list.

Returned By: Too many methods to list.

TextLayout	Java 1.2
java.awt.font	cloneable

This class represents and displays a line of styled, possibly bidirectional, text and provides algorithms for the visual manipulation of that text. This is a powerful and complex class. Many applications prefer to use high-level Swing components, such as JTextField and JTextPane, to handle text display and editing. Some applications may want to use the lower-level GlyphVector class for maximum text drawing speed.

Using the TextLayout() constructor, you can create a TextLayout from a java.text.AttributedCharacterIterator, from a string and a font, or from a string and a java.util.Map of attributes. All versions of the constructor also require a FontRenderContext, obtained with the getFontRenderContext() method of Graphics2D.

Once you have created a TextLayout, you can draw it by calling its draw() method. TextLayout also provides various other methods to support applications that allow the user to edit the text. If the user clicks on the text, you can determine what character was clicked on with hitTestChar(), which returns a TextHitInfo. Once you have an insertion position specified with a TextHitInfo, you can obtain a Shape appropriate for use as an insertion cursor by calling getCaretShape(). The returned shape is relative to the origin of the TextLayout, and it takes into account whether the text is italic. getCaretShapes() is passed a character index within the TextLayout; it returns an array of one or two Shape objects that represent insertion cursors for that character position. Usually this array contains only one cursor, but in bidirectional text, it may contain both a primary insertion cursor and a secondary insertion cursor.

If the user selects text by clicking and dragging with the mouse, you can call getVisualHighlightShape() to determine how to highlight the selected text. This method returns a Shape object suitable for drawing the highlighted regions. Alternatively, you can use getLogicalHightlightShape() to highlight a specified contiguous group of characters in the TextLayout. Note, however, that in bidirectional text, this logical highlight might map to two visually disjoint regions.

Hierarchy: Object-->TextLayout(Cloneable)

Passed To: TextLayout.equals(), TextLayout.CaretPolicy.getStrongCaret()

Returned By: LineBreakMeasurer.nextLayout(), TextLayout.getJustifiedLayout()

TextLayout.CaretPolicy	Java 1.2
java.awt.font

This class defines a policy for deciding which insertion position is the dominant one in bidirectional text. Most applications never need to use this class.

If you want to specify a policy other than the default, you should subclass this class and override getStrongCaret() to choose between two TextHitInfo objects, returning the one that represents the dominant insertion position. Then pass an instance of your subclass to the getCaretShapes(), getNextLeftHit(), and getNextRightHit() methods of TextLayout.

Passed To: TextLayout.{getCaretShapes(), getNextLeftHit(), getNextRightHit()}

Type Of: TextLayout.DEFAULT_CARET_POLICY

TextLine.TextLineMetrics	Java 1.2
java.awt.font

This public inner class is defined within a private class. It was inadvertently included in the public API of java.awt.font but should be considered private.

TransformAttribute	Java 1.2
java.awt.font	serializable

This class is a simple immutable wrapper around a java.awt.geom.AffineTransform. This wrapper makes it safe to use a transform as the value of a TextAttribute.TRANSFORM attribute.

Hierarchy: Object-->TransformAttribute(Serializable)