java.awt.font
Class TextLayout

java.lang.Object   
  java.awt.font.TextLayout

All Implemented Interfaces:

Cloneable

public final class TextLayout
extends Object   
implements Cloneable   

TextLayout is an immutable graphical representation of styled character data.

It provides the following capabilities:

• implicit bidirectional analysis and reordering,
• cursor positioning and movement, including split cursors for mixed directional text,
• highlighting, including both logical and visual highlighting for mixed directional text,
• multiple baselines (roman, hanging, and centered),
• hit testing,
• justification,
• default font substitution,
• metric information such as ascent, descent, and advance, and
• rendering

A TextLayout object can be rendered using its draw method.

TextLayout can be constructed either directly or through the use of a LineBreakMeasurer . When constructed directly, the source text represents a single paragraph. LineBreakMeasurer allows styled text to be broken into lines that fit within a particular width. See the LineBreakMeasurer documentation for more information.

TextLayout construction logically proceeds as follows:

• paragraph attributes are extracted and examined,
• text is analyzed for bidirectional reordering, and reordering information is computed if needed,
• text is segmented into style runs
• fonts are chosen for style runs, first by using a font if the attribute TextAttribute.FONT is present, otherwise by computing a default font using the attributes that have been defined
• if text is on multiple baselines, the runs or subruns are further broken into subruns sharing a common baseline,
• glyphvectors are generated for each run using the chosen font,
• final bidirectional reordering is performed on the glyphvectors

All graphical information returned from a TextLayout object's methods is relative to the origin of the TextLayout, which is the intersection of the TextLayout object's baseline with its left edge. Also, coordinates passed into a TextLayout object's methods are assumed to be relative to the TextLayout object's origin. Clients usually need to translate between a TextLayout object's coordinate system and the coordinate system in another object (such as a Graphics object).

TextLayout objects are constructed from styled text, but they do not retain a reference to their source text. Thus, changes in the text previously used to generate a TextLayout do not affect the TextLayout.

Three methods on a TextLayout object (getNextRightHit, getNextLeftHit, and hitTestChar) return instances of TextHitInfo . The offsets contained in these TextHitInfo objects are relative to the start of the TextLayout, not to the text used to create the TextLayout. Similarly, TextLayout methods that accept TextHitInfo instances as parameters expect the TextHitInfo object's offsets to be relative to the TextLayout, not to any underlying text storage model.

Examples:

Constructing and drawing a TextLayout and its bounding rectangle:

   Graphics2D g = ...;
   Point2D loc = ...;
   Font font = Font.getFont("Helvetica-bold-italic");
   FontRenderContext frc = g.getFontRenderContext();
   TextLayout layout = new TextLayout("This is a string", font, frc);
   layout.draw(g, (float)loc.getX(), (float)loc.getY());

   Rectangle2D bounds = layout.getBounds();
   bounds.setRect(bounds.getX()+loc.getX(),
                  bounds.getY()+loc.getY(),
                  bounds.getWidth(),
                  bounds.getHeight());
   g.draw(bounds);
 

Hit-testing a TextLayout (determining which character is at a particular graphical location):

   Point2D click = ...;
   TextHitInfo hit = layout.hitTestChar(
                         (float) (click.getX() - loc.getX()),
                         (float) (click.getY() - loc.getY()));
 

Responding to a right-arrow key press:

   int insertionIndex = ...;
   TextHitInfo next = layout.getNextRightHit(insertionIndex);
   if (next != null) {
       // translate graphics to origin of layout on screen
       g.translate(loc.getX(), loc.getY());
       Shape[] carets = layout.getCaretShapes(next.getInsertionIndex());
       g.draw(carets[0]);
       if (carets[1] != null) {
           g.draw(carets[1]);
       }
   }
 

Drawing a selection range corresponding to a substring in the source text. The selected area may not be visually contiguous:

   // selStart, selLimit should be relative to the layout,
   // not to the source text

   int selStart = ..., selLimit = ...;
   Color selectionColor = ...;
   Shape selection = layout.getLogicalHighlightShape(selStart, selLimit);
   // selection may consist of disjoint areas
   // graphics is assumed to be tranlated to origin of layout
   g.setColor(selectionColor);
   g.fill(selection);
 

Drawing a visually contiguous selection range. The selection range may correspond to more than one substring in the source text. The ranges of the corresponding source text substrings can be obtained with getLogicalRangesForVisualSelection():

   TextHitInfo selStart = ..., selLimit = ...;
   Shape selection = layout.getVisualHighlightShape(selStart, selLimit);
   g.setColor(selectionColor);
   g.fill(selection);
   int[] ranges = getLogicalRangesForVisualSelection(selStart, selLimit);
   // ranges[0], ranges[1] is the first selection range,
   // ranges[2], ranges[3] is the second selection range, etc.
 

See Also:

LineBreakMeasurer , TextAttribute , TextHitInfo

Nested Class Summary

static class

TextLayout.CaretPolicy Defines a policy for determining the strong caret location.

Field Summary

static TextLayout.CaretPolicy

DEFAULT_CARET_POLICY This CaretPolicy is used when a policy is not specified by the client.

Constructor Summary

TextLayout (AttributedCharacterIterator text, FontRenderContext frc)
Constructs a TextLayout from an iterator over styled text.

TextLayout (String string, Font font, FontRenderContext frc)
Constructs a TextLayout from a String and a Font .

TextLayout (String string, Map <? extends AttributedCharacterIterator.Attribute ,?> attributes, FontRenderContext frc)
Constructs a TextLayout from a String and an attribute set.

Method Summary

protected Object	clone () Creates a copy of this TextLayout.
void	draw (Graphics2D g2, float x, float y) Renders this TextLayout at the specified location in the specified Graphics2D context.
boolean	equals (Object obj) Returns true if the specified Object is a TextLayout object and if the specified Object equals this TextLayout.
boolean	equals (TextLayout rhs) Returns true if the two layouts are equal.
float	getAdvance () Returns the advance of this TextLayout.
float	getAscent () Returns the ascent of this TextLayout.
byte	getBaseline () Returns the baseline for this TextLayout.
float[]	getBaselineOffsets () Returns the offsets array for the baselines used for this TextLayout.
Shape	getBlackBoxBounds (int firstEndpoint, int secondEndpoint) Returns the black box bounds of the characters in the specified range.
Rectangle2D	getBounds () Returns the bounds of this TextLayout.
float[]	getCaretInfo (TextHitInfo hit) Returns information about the caret corresponding to hit.
float[]	getCaretInfo (TextHitInfo hit, Rectangle2D bounds) Returns information about the caret corresponding to hit.
Shape	getCaretShape (TextHitInfo hit) Returns a Shape representing the caret at the specified hit inside the natural bounds of this TextLayout.
Shape	getCaretShape (TextHitInfo hit, Rectangle2D bounds) Returns a Shape representing the caret at the specified hit inside the specified bounds.
Shape []	getCaretShapes (int offset) Returns two paths corresponding to the strong and weak caret.
Shape []	getCaretShapes (int offset, Rectangle2D bounds) Returns two paths corresponding to the strong and weak caret.
Shape []	getCaretShapes (int offset, Rectangle2D bounds, TextLayout.CaretPolicy policy) Returns two paths corresponding to the strong and weak caret.
int	getCharacterCount () Returns the number of characters represented by this TextLayout.
byte	getCharacterLevel (int index) Returns the level of the character at index.
float	getDescent () Returns the descent of this TextLayout.
TextLayout	getJustifiedLayout (float justificationWidth) Creates a copy of this TextLayout justified to the specified width.
float	getLeading () Returns the leading of the TextLayout.
Shape	getLogicalHighlightShape (int firstEndpoint, int secondEndpoint) Returns a Shape enclosing the logical selection in the specified range, extended to the natural bounds of this TextLayout.
Shape	getLogicalHighlightShape (int firstEndpoint, int secondEndpoint, Rectangle2D bounds) Returns a Shape enclosing the logical selection in the specified range, extended to the specified bounds.
int[]	getLogicalRangesForVisualSelection (TextHitInfo firstEndpoint, TextHitInfo secondEndpoint) Returns the logical ranges of text corresponding to a visual selection.
TextHitInfo	getNextLeftHit (int offset) Returns the hit for the next caret to the left (top); if no such hit, returns null.
TextHitInfo	getNextLeftHit (int offset, TextLayout.CaretPolicy policy) Returns the hit for the next caret to the left (top); if no such hit, returns null.
TextHitInfo	getNextLeftHit (TextHitInfo hit) Returns the hit for the next caret to the left (top); if no such hit, returns null.
TextHitInfo	getNextRightHit (int offset) Returns the hit for the next caret to the right (bottom); if no such hit, returns null.
TextHitInfo	getNextRightHit (int offset, TextLayout.CaretPolicy policy) Returns the hit for the next caret to the right (bottom); if no such hit, returns null.
TextHitInfo	getNextRightHit (TextHitInfo hit) Returns the hit for the next caret to the right (bottom); if there is no such hit, returns null.
Shape	getOutline (AffineTransform tx) Returns a Shape representing the outline of this TextLayout.
float	getVisibleAdvance () Returns the advance of this TextLayout, minus trailing whitespace.
Shape	getVisualHighlightShape (TextHitInfo firstEndpoint, TextHitInfo secondEndpoint) Returns a Shape enclosing the visual selection in the specified range, extended to the bounds.
Shape	getVisualHighlightShape (TextHitInfo firstEndpoint, TextHitInfo secondEndpoint, Rectangle2D bounds) Returns a path enclosing the visual selection in the specified range, extended to bounds.
TextHitInfo	getVisualOtherHit (TextHitInfo hit) Returns the hit on the opposite side of the specified hit's caret.
protected void	handleJustify (float justificationWidth) Justify this layout.
int	hashCode () Returns the hash code of this TextLayout.
TextHitInfo	hitTestChar (float x, float y) Returns a TextHitInfo corresponding to the specified point.
TextHitInfo	hitTestChar (float x, float y, Rectangle2D bounds) Returns a TextHitInfo corresponding to the specified point.
boolean	isLeftToRight () Returns true if this TextLayout has a left-to-right base direction or false if it has a right-to-left base direction.
boolean	isVertical () Returns true if this TextLayout is vertical.
String	toString () Returns debugging information for this TextLayout.

Methods inherited from class java.lang.Object

finalize , getClass , notify , notifyAll , wait , wait , wait

Field Detail

DEFAULT_CARET_POLICY

public static final TextLayout.CaretPolicy    DEFAULT_CARET_POLICY

This CaretPolicy is used when a policy is not specified by the client. With this policy, a hit on a character whose direction is the same as the line direction is stronger than a hit on a counterdirectional character. If the characters' directions are the same, a hit on the leading edge of a character is stronger than a hit on the trailing edge of a character.

Constructor Detail

TextLayout

public TextLayout(String    string,
                  Font    font,
                  FontRenderContext    frc)

Constructs a TextLayout from a String and a Font . All the text is styled using the specified Font.

The String must specify a single paragraph of text, because an entire paragraph is required for the bidirectional algorithm.

Parameters:

string - the text to display

font - a Font used to style the text

frc - contains information about a graphics device which is needed to measure the text correctly. Text measurements can vary slightly depending on the device resolution, and attributes such as antialiasing. This parameter does not specify a translation between the TextLayout and user space.

TextLayout

public TextLayout(String    string,
                  Map   <? extends AttributedCharacterIterator.Attribute   ,?> attributes,
                  FontRenderContext    frc)

Constructs a TextLayout from a String and an attribute set.

All the text is styled using the provided attributes.

string must specify a single paragraph of text because an entire paragraph is required for the bidirectional algorithm.

Parameters:

string - the text to display

attributes - the attributes used to style the text

frc - contains information about a graphics device which is needed to measure the text correctly. Text measurements can vary slightly depending on the device resolution, and attributes such as antialiasing. This parameter does not specify a translation between the TextLayout and user space.

TextLayout

public TextLayout(AttributedCharacterIterator    text,
                  FontRenderContext