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.
(package private) static class	TextLayout.OptInfo temporary optimization

Field Summary

private static float	ALREADY_JUSTIFIED
private byte	baseline
private float[]	baselineOffsets
private Rectangle2D	boundsRect
private boolean	cacheIsValid
private boolean	caretsInLigaturesAreAllowed
private int	characterCount
static TextLayout.CaretPolicy	DEFAULT_CARET_POLICY This CaretPolicy is used when a policy is not specified by the client.
private static float	dx
private static float	dy
private int	hashCodeCache
private boolean	isVerticalLine
private float	justifyRatio
private TextLine.TextLineMetrics	lineMetrics
private Rectangle2D	naturalBounds
private TextLayout.OptInfo	optInfo
private TextLine	textLine
private float	visibleAdvance

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 attributes, FontRenderContext frc) Constructs a TextLayout from a String and an attribute set.
(package private)	TextLayout(TextLine textLine, byte baseline, float[] baselineOffsets, float justifyRatio) Creates a TextLayout from a TextLine and some paragraph data.

Method Summary

private GeneralPath	boundingShape(double[] path0, double[] path1)
private void	buildCache()
private GeneralPath	caretBoundingShape(int caret0, int caret1, Rectangle2D bounds)
private boolean	caretIsValid(int caret)
private TextHitInfo	caretToHit(int caret) Given a caret index, return a hit whose caret is at the index.
private float	caretToPointDistance(float[] caretInfo, float x, float y) Returns the distance from the point (x, y) to the caret along the line direction defined in caretInfo.
private void	checkTextHit(TextHitInfo hit)
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.
private void	ensureCache()
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.
private void	fastInit(char[] chars, Font font, Map attrs, FontRenderContext frc)
float	getAdvance() Returns the advance of this TextLayout.
float	getAscent() Returns the ascent of this TextLayout.
byte	getBaseline() Returns the baseline for this TextLayout.
(package private) static byte	getBaselineFromGraphic(GraphicAttribute graphic)
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.
private float[]	getCaretInfo(int caret, Rectangle2D bounds, float[] info)
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.
private double[]	getCaretPath(int caret, Rectangle2D bounds, boolean clipToBounds) Return an array of four floats corresponding the endpoints of the caret x0, y0, x1, y1.
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.
private Rectangle2D	getNaturalBounds()
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.
private TextHitInfo	getStrongHit(TextHitInfo hit1, TextHitInfo hit2) Return the "stronger" of the TextHitInfos.
(package private) TextLine	getTextLineForTesting() Package-only method for testing ONLY.
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.
private int	hitToCaret(TextHitInfo hit) Returns a caret index corresponding to hit.
private void	initTextLine()
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.
private GeneralPath	leftShape(Rectangle2D bounds)
private void	paragraphInit(byte aBaseline, LineMetrics lm, Map paragraphAttrs, char[] text) Initialize the paragraph-specific data.
private static GeneralPath	pathToShape(double[] path, boolean close)
private GeneralPath	rightShape(Rectangle2D bounds)
private static int	sameBaselineUpTo(Font font, char[] text, int start, int limit) Return the index of the first character with a different baseline from the character at start, or limit if all characters between start and limit have the same baseline.
private static Font	singleFont(char[] text, int start, int limit, Map attributes)
private void	standardInit(AttributedCharacterIterator text, char[] chars, FontRenderContext frc)
String	toString() Returns debugging information for this TextLayout.

Methods inherited from class java.lang.Object

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

Field Detail

characterCount

private int characterCount

isVerticalLine

private boolean isVerticalLine

baseline

private byte baseline

baselineOffsets

private float[] baselineOffsets

textLine

private TextLine textLine

lineMetrics

private TextLine.TextLineMetrics lineMetrics

visibleAdvance

private float visibleAdvance

hashCodeCache

private int hashCodeCache

optInfo

private TextLayout.OptInfo optInfo

cacheIsValid

private boolean cacheIsValid

justifyRatio

private float justifyRatio

ALREADY_JUSTIFIED

private static final float ALREADY_JUSTIFIED

See Also:

Constant Field Values

dx

private static float dx

dy

private static float dy

naturalBounds

private Rectangle2D naturalBounds

boundsRect

private Rectangle2D boundsRect

caretsInLigaturesAreAllowed

private boolean caretsInLigaturesAreAllowed

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 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 frc)

Constructs a TextLayout from an iterator over styled text.

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

Parameters:

text - the styled text to display

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

TextLayout(TextLine textLine,
           byte baseline,
           float[] baselineOffsets,
           float justifyRatio)

Creates a TextLayout from a TextLine and some paragraph data. This method is used by TextMeasurer.

Parameters:

textLine - the line measurement attributes to apply to the the resulting TextLayout

baseline - the baseline of the text

baselineOffsets - the baseline offsets for this TextLayout. This should already be normalized to baseline

justifyRatio - 0 if the TextLayout cannot be justified; 1 otherwise.

Method Detail

singleFont

private static Font singleFont(char[] text,
                               int start,
                               int limit,
                               Map attributes)

paragraphInit

private void paragraphInit(byte aBaseline,
                           LineMetrics lm,
                           Map paragraphAttrs,
                           char[] text)

Initialize the paragraph-specific data.

fastInit

private void fastInit(char[] chars,
                      Font font,
                      Map attrs,
                      FontRenderContext frc)

initTextLine

private void initTextLine()

standardInit

private void standardInit(AttributedCharacterIterator text,
                          char[] chars,
                          FontRenderContext frc)

ensureCache

private void ensureCache()

buildCache

private void buildCache()

getNaturalBounds

private Rectangle2D getNaturalBounds()

clone

protected Object clone()

Creates a copy of this TextLayout.

Overrides:

clone in class Object

Returns:

a clone of this instance.

See Also:

Cloneable

checkTextHit

private void checkTextHit(TextHitInfo hit)

getJustifiedLayout

public TextLayout getJustifiedLayout(float justificationWidth)

Creates a copy of this TextLayout justified to the specified width.

If this TextLayout has already been justified, an exception is thrown. If this TextLayout object's justification ratio is zero, a TextLayout identical to this TextLayout is returned.

Parameters:

justificationWidth - the width to use when justifying the line. For best results, it should not be too different from the current advance of the line.

Returns:

a TextLayout justified to the specified width.

Throws:

Error - if this layout has already been justified, an Error is thrown.

handleJustify

protected void handleJustify(float justificationWidth)

Justify this layout. Overridden by subclassers to control justification (if there were subclassers, that is...) The layout will only justify if the paragraph attributes (from the source text, possibly defaulted by the layout attributes) indicate a non-zero justification ratio. The text will be justified to the indicated width. The current implementation also adjusts hanging punctuation and trailing whitespace to overhang the justification width. Once justified, the layout may not be rejustified.

Some code may rely on immutablity of layouts. Subclassers should not call this directly, but instead should call getJustifiedLayout, which will call this method on a clone of this layout, preserving the original.

Parameters:

justificationWidth - the width to use when justifying the line. For best results, it should not be too different from the current advance of the line.

See Also:

getJustifiedLayout(float)

getBaseline

public byte getBaseline()

Returns the baseline for this TextLayout. The baseline is one of the values defined in Font, which are roman, centered and hanging. Ascent and descent are relative to this baseline. The baselineOffsets are also relative to this baseline.

Returns:

the baseline of this TextLayout.

See Also:

getBaselineOffsets(), Font

getBaselineOffsets

public float[] getBaselineOffsets()

Returns the offsets array for the baselines used for this TextLayout.

The array is indexed by one of the values defined in Font, which are roman, centered and hanging. The values are relative to this TextLayout object's baseline, so that getBaselineOffsets[getBaseline()] == 0. Offsets are added to the position of the TextLayout object's baseline to get the position for the new baseline.

Returns:

the offsets array containing the baselines used for this TextLayout.

See Also:

getBaseline(), Font

getAdvance

public float getAdvance()

Returns the advance of this TextLayout. The advance is the distance from the origin to the advance of the rightmost (bottommost) character measuring in the line direction.

Returns:

the advance of this TextLayout.

getVisibleAdvance

public float getVisibleAdvance()

Returns the advance of this TextLayout, minus trailing whitespace.

Returns:

the advance of this TextLayout without the trailing whitespace.

See Also:

getAdvance()

getAscent

public float getAscent()

Returns the ascent of this TextLayout. The ascent is the distance from the top (right) of the TextLayout to the baseline. It is always either positive or zero. The ascent is sufficient to accomodate superscripted text and is the maximum of the sum of the ascent, offset, and baseline of each glyph.

Returns:

the ascent of this TextLayout.

getDescent

public float getDescent()

Returns the descent of this TextLayout. The descent is the distance from the baseline to the bottom (left) of the TextLayout. It is always either positive or zero. The descent is sufficient to accomodate subscripted text and is the maximum of the sum of the descent, offset, and baseline of each glyph.

Returns:

the descent of this TextLayout.

getLeading

public float getLeading()

Returns the leading of the TextLayout. The leading is the suggested interline spacing for this TextLayout.

The leading is computed from the leading, descent, and baseline of all glyphvectors in the TextLayout. The algorithm is roughly as follows:

 maxD = 0;
 maxDL = 0;
 for (GlyphVector g in all glyphvectors) {
    maxD = max(maxD, g.getDescent() + offsets[g.getBaseline()]);
    maxDL = max(maxDL, g.getDescent() + g.getLeading() +
                       offsets[g.getBaseline()]);
 }
 return maxDL - maxD;
 

Returns:

the leading of this TextLayout.

getBounds

public Rectangle2D getBounds()

Returns the bounds of this TextLayout. The bounds contains all of the pixels the TextLayout can draw. It might not coincide exactly with the ascent, descent, origin or advance of the TextLayout.

Returns:

a Rectangle2D that is the bounds of this TextLayout.

isLeftToRight

public 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. The TextLayout has a base direction of either left-to-right (LTR) or right-to-left (RTL). The base direction is independent of the actual direction of text on the line, which may be either LTR, RTL, or mixed. Left-to-right layouts by default should position flush left. If the layout is on a tabbed line, the tabs run left to right, so that logically successive layouts position left to right. The opposite is true for RTL layouts. By default they should position flush left, and tabs run right-to-left.

Returns:

true if the base direction of this TextLayout is left-to-right; false otherwise.

isVertical

public boolean isVertical()

Returns true if this TextLayout is vertical.

Returns:

true if this TextLayout is vertical; false otherwise.

getCharacterCount

public int getCharacterCount()

Returns the number of characters represented by this TextLayout.

Returns:

the number of characters in this TextLayout.

getCaretInfo

private float[] getCaretInfo(int caret,
                             Rectangle2D bounds,
                             float[] info)

getCaretInfo

public float[] getCaretInfo(TextHitInfo hit,
                            Rectangle2D bounds)

Returns information about the caret corresponding to hit. The first element of the array is the intersection of the caret with the baseline. The second element of the array is the inverse slope (run/rise) of the caret.

This method is meant for informational use. To display carets, it is better to use getCaretShapes.

Parameters:

hit - a hit on a character in this TextLayout

bounds - the bounds to which the caret info is constructed

Returns:

a two-element array containing the position and slope of the caret.

See Also:

getCaretShapes(int, Rectangle2D, TextLayout.CaretPolicy), Font.getItalicAngle()

getCaretInfo

public float[] getCaretInfo(TextHitInfo hit)

Returns information about the caret corresponding to hit. This method is a convenience overload of getCaretInfo and uses the natural bounds of this TextLayout.

Parameters:

hit - a hit on a character in this TextLayout

Returns:

the information about a caret corresponding to a hit.

hitToCaret

private int hitToCaret(TextHitInfo hit)

Returns a caret index corresponding to hit. Carets are numbered from left to right (top to bottom) starting from zero. This always places carets next to the character hit, on the indicated side of the character.

Parameters:

hit - a hit on a character in this TextLayout

Returns:

a caret index corresponding to the specified hit.

caretToHit

private TextHitInfo caretToHit(int caret)

Given a caret index, return a hit whose caret is at the index. The hit is NOT guaranteed to be strong!!!

Parameters:

caret - a caret index.

Returns:

a hit on this layout whose strong caret is at the requested index.

caretIsValid

private boolean caretIsValid(int caret)

getNextRightHit

public TextHitInfo getNextRightHit(TextHitInfo hit)

Returns the hit for the next caret to the right (bottom); if there is no such hit, returns null. If the hit character index is out of bounds, an IllegalArgumentException is thrown.

Parameters:

hit - a hit on a character in this layout

Returns:

a hit whose caret appears at the next position to the right (bottom) of the caret of the provided hit or null.

getNextRightHit

public TextHitInfo getNextRightHit(int offset,
                                   TextLayout.CaretPolicy policy)

Returns the hit for the next caret to the right (bottom); if no such hit, returns null. The hit is to the right of the strong caret at the specified offset, as determined by the specified policy. The returned hit is the stronger of the two possible hits, as determined by the specified policy.

Parameters:

offset - an insertion offset in this TextLayout. Cannot be less than 0 or greater than this TextLayout object's character count.

policy - the policy used to select the strong caret

Returns:

a hit whose caret appears at the next position to the right (bottom) of the caret of the provided hit, or null.

getNextRightHit

public TextHitInfo getNextRightHit(int offset)

Returns the hit for the next caret to the right (bottom); if no such hit, returns null. The hit is to the right of the strong caret at the specified offset, as determined by the default policy. The returned hit is the stronger of the two possible hits, as determined by the default policy.

Parameters:

offset - an insertion offset in this TextLayout. Cannot be less than 0 or greater than the TextLayout object's character count.

Returns:

a hit whose caret appears at the next position to the right (bottom) of the caret of the provided hit, or null.

getNextLeftHit

public TextHitInfo getNextLeftHit(TextHitInfo hit)

Returns the hit for the next caret to the left (top); if no such hit, returns null. If the hit character index is out of bounds, an IllegalArgumentException is thrown.

Parameters:

hit - a hit on a character in this TextLayout.

Returns:

a hit whose caret appears at the next position to the left (top) of the caret of the provided hit, or null.

getNextLeftHit

public TextHitInfo getNextLeftHit(int offset,
                                  TextLayout.CaretPolicy policy)

Returns the hit for the next caret to the left (top); if no such hit, returns null. The hit is to the left of the strong caret at the specified offset, as determined by the specified policy. The returned hit is the stronger of the two possible hits, as determined by the specified policy.

Parameters:

offset - an insertion offset in this TextLayout. Cannot be less than 0 or greater than this TextLayout object's character count.

policy - the policy used to select the strong caret

Returns:

a hit whose caret appears at the next position to the left (top) of the caret of the provided hit, or null.

getNextLeftHit

public TextHitInfo getNextLeftHit(int offset)

Returns the hit for the next caret to the left (top); if no such hit, returns null. The hit is to the left of the strong caret at the specified offset, as determined by the default policy. The returned hit is the stronger of the two possible hits, as determined by the default policy.

Parameters:

offset - an insertion offset in this TextLayout. Cannot be less than 0 or greater than this TextLayout object's character count.

Returns:

a hit whose caret appears at the next position to the left (top) of the caret of the provided hit, or null.

getVisualOtherHit

public TextHitInfo getVisualOtherHit(TextHitInfo hit)

Returns the hit on the opposite side of the specified hit's caret.

Parameters:

hit - the specified hit

Returns:

a hit that is on the opposite side of the specified hit's caret.

getCaretPath

private double[] getCaretPath(int caret,
                              Rectangle2D bounds,
                              boolean clipToBounds)

Return an array of four floats corresponding the endpoints of the caret x0, y0, x1, y1. This creates a line along the slope of the caret intersecting the baseline at the caret position, and extending from ascent above the baseline to descent below it.

pathToShape

private static GeneralPath pathToShape(double[] path,
                                       boolean close)

getCaretShape

public Shape getCaretShape(TextHitInfo hit,
                           Rectangle2D bounds)

Returns a Shape representing the caret at the specified hit inside the specified bounds.

Parameters:

hit - the hit at which to generate the caret

bounds - the bounds of the TextLayout to use in generating the caret.

Returns:

a Shape representing the caret.

getCaretShape

public Shape getCaretShape(TextHitInfo hit)

Returns a Shape representing the caret at the specified hit inside the natural bounds of this TextLayout.

Parameters:

hit - the hit at which to generate the caret

Returns:

a Shape representing the caret.

getStrongHit

private final TextHitInfo getStrongHit(TextHitInfo hit1,
                                       TextHitInfo hit2)

Return the "stronger" of the TextHitInfos. The TextHitInfos should be logical or visual counterparts. They are not checked for validity.

getCharacterLevel

public byte getCharacterLevel(int index)

Returns the level of the character at index. Indices -1 and characterCount are assigned the base level of this TextLayout.

Parameters:

index - the index of the character from which to get the level

Returns:

the level of the character at the specified index.

getCaretShapes

public Shape[] getCaretShapes(int offset,
                              Rectangle2D bounds,
                              TextLayout.CaretPolicy policy)

Returns two paths corresponding to the strong and weak caret.

Parameters:

offset - an offset in this TextLayout

bounds - the bounds to which to extend the carets

policy - the specified CaretPolicy

Returns:

an array of two paths. Element zero is the strong caret. If there are two carets, element one is the weak caret, otherwise it is null.

getCaretShapes

public Shape[] getCaretShapes(int offset,
                              Rectangle2D bounds)

Returns two paths corresponding to the strong and weak caret. This method is a convenience overload of getCaretShapes that uses the default caret policy.

Parameters:

offset - an offset in this TextLayout

bounds - the bounds to which to extend the carets

Returns:

two paths corresponding to the strong and weak caret as defined by the DEFAULT_CARET_POLICY

getCaretShapes

public Shape[] getCaretShapes(int offset)

Returns two paths corresponding to the strong and weak caret. This method is a convenience overload of getCaretShapes that uses the default caret policy and this TextLayout object's natural bounds.

Parameters:

offset - an offset in this TextLayout

Returns:

two paths corresponding to the strong and weak caret as defined by the DEFAULT_CARET_POLICY

boundingShape

private GeneralPath boundingShape(double[] path0,
                                  double[] path1)

caretBoundingShape

private GeneralPath caretBoundingShape(int caret0,
                                       int caret1,
                                       Rectangle2D bounds)

leftShape

private GeneralPath leftShape(Rectangle2D bounds)

rightShape

private GeneralPath rightShape(Rectangle2D bounds)

getLogicalRangesForVisualSelection

public int[] getLogicalRangesForVisualSelection(TextHitInfo firstEndpoint,
                                                TextHitInfo secondEndpoint)

Returns the logical ranges of text corresponding to a visual selection.

Parameters:

firstEndpoint - an endpoint of the visual range

secondEndpoint - the other endpoint of the visual range. This endpoint can be less than firstEndpoint.

Returns:

an array of integers representing start/limit pairs for the selected ranges.

See Also:

getVisualHighlightShape(TextHitInfo, TextHitInfo, Rectangle2D)

getVisualHighlightShape

public Shape getVisualHighlightShape(TextHitInfo firstEndpoint,
                                     TextHitInfo secondEndpoint,
                                     Rectangle2D bounds)

Returns a path enclosing the visual selection in the specified range, extended to bounds.

If the selection includes the leftmost (topmost) position, the selection is extended to the left (top) of bounds. If the selection includes the rightmost (bottommost) position, the selection is extended to the right (bottom) of the bounds. The height (width on vertical lines) of the selection is always extended to bounds.

Although the selection is always contiguous, the logically selected text can be discontiguous on lines with mixed-direction text. The logical ranges of text selected can be retrieved using getLogicalRangesForVisualSelection. For example, consider the text 'ABCdef' where capital letters indicate right-to-left text, rendered on a right-to-left line, with a visual selection from 0L (the leading edge of 'A') to 3T (the trailing edge of 'd'). The text appears as follows, with bold underlined areas representing the selection:

    defCBA  
 

The logical selection ranges are 0-3, 4-6 (ABC, ef) because the visually contiguous text is logically discontiguous. Also note that since the rightmost position on the layout (to the right of 'A') is selected, the selection is extended to the right of the bounds.

Parameters:

firstEndpoint - one end of the visual selection

secondEndpoint - the other end of the visual selection

bounds - the bounding rectangle to which to extend the selection

Returns:

a Shape enclosing the selection.

See Also:

getLogicalRangesForVisualSelection(TextHitInfo, TextHitInfo), getLogicalHighlightShape(int, int, Rectangle2D)

getVisualHighlightShape

public Shape getVisualHighlightShape(TextHitInfo firstEndpoint,
                                     TextHitInfo secondEndpoint)

Returns a Shape enclosing the visual selection in the specified range, extended to the bounds. This method is a convenience overload of getVisualHighlightShape that uses the natural bounds of this TextLayout.

Parameters:

firstEndpoint - one end of the visual selection

secondEndpoint - the other end of the visual selection

Returns:

a Shape enclosing the selection.

getLogicalHighlightShape

public Shape getLogicalHighlightShape(int firstEndpoint,
                                      int secondEndpoint,
                                      Rectangle2D bounds)

Returns a Shape enclosing the logical selection in the specified range, extended to the specified bounds.

If the selection range includes the first logical character, the selection is extended to the portion of bounds before the start of this TextLayout. If the range includes the last logical character, the selection is extended to the portion of bounds after the end of this TextLayout. The height (width on vertical lines) of the selection is always extended to bounds.

The selection can be discontiguous on lines with mixed-direction text. Only those characters in the logical range between start and limit appear selected. For example, consider the text 'ABCdef' where capital letters indicate right-to-left text, rendered on a right-to-left line, with a logical selection from 0 to 4 ('ABCd'). The text appears as follows, with bold standing in for the selection, and underlining for the extension:

    defCBA  
 

The selection is discontiguous because the selected characters are visually discontiguous. Also note that since the range includes the first logical character (A), the selection is extended to the portion of the bounds before the start of the layout, which in this case (a right-to-left line) is the right portion of the bounds.

Parameters:

firstEndpoint - an endpoint in the range of characters to select

secondEndpoint - the other endpoint of the range of characters to select. Can be less than firstEndpoint. The range includes the character at min(firstEndpoint, secondEndpoint), but excludes max(firstEndpoint, secondEndpoint).

bounds - the bounding rectangle to which to extend the selection

Returns:

an area enclosing the selection.

See Also:

getVisualHighlightShape(TextHitInfo, TextHitInfo, Rectangle2D)

getLogicalHighlightShape

public 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. This method is a convenience overload of getLogicalHighlightShape that uses the natural bounds of this TextLayout.

Parameters:

firstEndpoint - an endpoint in the range of characters to select

secondEndpoint - the other endpoint of the range of characters to select. Can be less than firstEndpoint. The range includes the character at min(firstEndpoint, secondEndpoint), but excludes max(firstEndpoint, secondEndpoint).

Returns:

a Shape enclosing the selection.

getBlackBoxBounds

public Shape getBlackBoxBounds(int firstEndpoint,
                               int secondEndpoint)

Returns the black box bounds of the characters in the specified range. The black box bounds is an area consisting of the union of the bounding boxes of all the glyphs corresponding to the characters between start and limit. This path may be disjoint.

Parameters:

firstEndpoint - one end of the character range

secondEndpoint - the other end of the character range. Can be less than firstEndpoint.

Returns:

a path enclosing the black box bounds.

caretToPointDistance

private float caretToPointDistance(float[] caretInfo,
                                   float x,
                                   float y)

Returns the distance from the point (x, y) to the caret along the line direction defined in caretInfo. Distance is negative if the point is to the left of the caret on a horizontal line, or above the caret on a vertical line. Utility for use by hitTestChar.

hitTestChar

public TextHitInfo hitTestChar(float x,
                               float y,
                               Rectangle2D bounds)

Returns a TextHitInfo corresponding to the specified point. Coordinates outside the bounds of the TextLayout map to hits on the leading edge of the first logical character, or the trailing edge of the last logical character, as appropriate, regardless of the position of that character in the line. Only the direction along the baseline is used to make this evaluation.

Parameters:

x - the x offset from the origin of this TextLayout

y - the y offset from the origin of this TextLayout

bounds - the bounds of the TextLayout

Returns:

a hit describing the character and edge (leading or trailing) under the specified point.

hitTestChar

public TextHitInfo hitTestChar(float x,
                               float y)

Returns a TextHitInfo corresponding to the specified point. This method is a convenience overload of hitTestChar that uses the natural bounds of this TextLayout.

Parameters:

x - the x offset from the origin of this TextLayout

y - the y offset from the origin of this TextLayout

Returns:

a hit describing the character and edge (leading or trailing) under the specified point.

hashCode

public int hashCode()

Returns the hash code of this TextLayout.

Overrides:

hashCode in class Object

Returns:

the hash code of this TextLayout.

See Also:

Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)

Returns true if the specified Object is a TextLayout object and if the specified Object equals this TextLayout.

Overrides:

equals in class Object

Parameters:

obj - an Object to test for equality

Returns:

true if the specified Object equals this TextLayout; false otherwise.

See Also:

Object.hashCode(), Hashtable

equals

public boolean equals(TextLayout rhs)

Returns true if the two layouts are equal. Two layouts are equal if they contain equal glyphvectors in the same order.

Parameters:

rhs - the TextLayout to compare to this TextLayout

Returns:

true if the specified TextLayout equals this TextLayout.

toString

public String toString()

Returns debugging information for this TextLayout.

Overrides:

toString in class Object

Returns:

the textLine of this TextLayout as a String.

draw

public void draw(Graphics2D g2,
                 float x,
                 float y)

Renders this TextLayout at the specified location in the specified Graphics2D context. The origin of the layout is placed at x, y. Rendering may touch any point within getBounds() of this position. This leaves the g2 unchanged.

Parameters:

g2 - the Graphics2D context into which to render the layout

See Also:

getBounds()

getTextLineForTesting

TextLine getTextLineForTesting()

Package-only method for testing ONLY. Please don't abuse.

sameBaselineUpTo

private static int sameBaselineUpTo(Font font,
                                    char[] text,
                                    int start,
                                    int limit)

Return the index of the first character with a different baseline from the character at start, or limit if all characters between start and limit have the same baseline.

getBaselineFromGraphic

static byte getBaselineFromGraphic(GraphicAttribute graphic)

getOutline

public Shape getOutline(AffineTransform tx)

Returns a Shape representing the outline of this TextLayout.

Parameters:

tx - an optional AffineTransform to apply to the outline of this TextLayout.

Returns:

a Shape that is the outline of this TextLayout.